From e647517d1592191a802922815a241c337315aa66 Mon Sep 17 00:00:00 2001 From: Kresimir Bestak Date: Thu, 13 Nov 2025 22:01:18 +0100 Subject: [PATCH] docker workflow and documentation fix --- .github/workflows/docker-publish.yml | 37 ++++++++++++------ CHANGELOG.md | 14 ++++++- README.md | 56 ++++++++++++++++++++-------- backsub/_version.py | 2 +- 4 files changed, 80 insertions(+), 29 deletions(-) diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml index cd9ef43..d261165 100644 --- a/.github/workflows/docker-publish.yml +++ b/.github/workflows/docker-publish.yml @@ -6,10 +6,11 @@ name: Docker # documentation. on: - release: - types: published pull_request: branches: [ "main" ] + + release: + types: [ published ] env: # Use docker.io for Docker Hub if empty @@ -33,14 +34,19 @@ jobs: - name: Checkout repository uses: actions/checkout@v4 + # Enable QEMU for cross-platform builds + # https://github.com/docker/setup-qemu-action + - name: Set up QEMU + uses: docker/setup-qemu-action@v3 + # Install the cosign tool except on PR # https://github.com/sigstore/cosign-installer - - name: Install Cosign + - name: Install cosign if: github.event_name != 'pull_request' - uses: sigstore/cosign-installer@v3.1.1 + uses: sigstore/cosign-installer@59acb6260d9c0ba8f4a2f9d9b48431a222b68e20 #v3.5.0 with: cosign-release: 'v2.2.4' - + # Set up BuildKit Docker container builder to be able to build # multi-platform images and export cache # https://github.com/docker/setup-buildx-action @@ -64,12 +70,6 @@ jobs: uses: docker/metadata-action@96383f45573cb7f253c731d3b3ab81c87ef81934 # v5.0.0 with: images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} - - - name: Get the tag name - run: echo "TAG=${GITHUB_REF/refs\/tags\//}" >> $GITHUB_ENV - - - name: Set up QEMU - uses: docker/setup-qemu-action@v3 # Build and push Docker image with Buildx (don't push on PR) # https://github.com/docker/build-push-action @@ -84,3 +84,18 @@ jobs: labels: ${{ steps.meta.outputs.labels }} cache-from: type=gha cache-to: type=gha,mode=max + + # Sign the resulting Docker image digest except on PRs. + # This will only write to the public Rekor transparency log when the Docker + # repository is public to avoid leaking data. If you would like to publish + # transparency data even for private images, pass --force to cosign below. + # https://github.com/sigstore/cosign + - name: Sign the published Docker image + if: ${{ github.event_name != 'pull_request' }} + env: + # https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions#using-an-intermediate-environment-variable + TAGS: ${{ steps.meta.outputs.tags }} + DIGEST: ${{ steps.build-and-push.outputs.digest }} + # This step uses the identity token to provision an ephemeral certificate + # against the sigstore community Fulcio instance. + run: echo "${TAGS}" | xargs -I {} cosign sign --yes {}@${DIGEST} diff --git a/CHANGELOG.md b/CHANGELOG.md index 060b348..756a609 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,7 +3,19 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## v0.5.0 - [2025.11.##] +## v0.5.1 - [2025.11.13] + +Minor fixes to automated workflows and documentation. + +### `Added` + +### `Fixed` +- docker publish workflow +- README image links and updated installation guide + +### `Removed` + +## v0.5.0 - [2025.11.13] Rework of Backsub to not have Palom as a dependency reducing the environment size and making it lightweight, and reducing the output file size, while keeping the time and memory usage efficiency. diff --git a/README.md b/README.md index 0e4fdf7..ff089d4 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ Backsub performs pixel-by-pixel background subtraction between marker and backgr Example of pixel-wise autofluorescence subtraction with Backsub:

- Background subtraction example + Background subtraction example

## Introduction @@ -19,47 +19,69 @@ The primary use case is autofluorescence subtraction for multichannel and multic Background subtraction is performed using the following formula: -$Marker_{corrected} = Marker_{raw} - Background \times \frac{Exposure_{Marker}}{Exposure_{Background}}$ +Marker_corrected = Marker_raw − Background × (Exposure_Marker / Exposure_Background) ## Installation -Backsub can be run either in a preconfigured Docker container or in a local conda environment. +Backsub can be installed directly from PyPI, or run in a preconfigured Docker container. For development or container builds, a fixed-version Conda environment is provided. -### Option 1: Docker +### Option 1: Install from PyPI -Pull the latest container from the GitHub Container Registry: +Backsub is available from [PyPI](https://pypi.org/project/backsub/) +```bash +pip install backsub +``` +After installation, you can run the tool directly in the command line +```bash +backsub --help +``` +Example: +```bash +backsub \ + -r /path/to/input_image.tif \ + -o /path/to/corrected_image.ome.tif \ + -m /path/to/markers.csv \ + -mo /path/to/markers_corrected.csv ``` + +### Option 2: Docker + +Pull the latest container from the GitHub Container Registry: +```bash docker pull ghcr.io/schapirolabor/background_subtraction:latest ``` You can then run Backsub directly, mounting your input and output directories: -``` +```bash docker run --rm -v $(pwd):/data ghcr.io/schapirolabor/background_subtraction:latest \ - python background_sub.py \ + backsub \ -r /data/input_image.tif \ -o /data/corrected_image.ome.tif \ -m /data/markers.csv \ -mo /data/markers_corrected.csv ``` -Note that all required dependencies are already included inside the container. If you want to build the container yourself, clone the repository first, then build it from the provided Dockerfile: ``` git clone https://github.com/SchapiroLabor/Background_subtraction.git cd Background_subtraction -docker build -t background_subtraction:latest . +docker build -t backsub:latest . ``` -### Option 2: Conda -Clone the repository and create the Conda environment: -``` +### Option 3: Development / Conda environment + +For development or reproducible research setups: +```bash git clone https://github.com/SchapiroLabor/Background_subtraction.git cd Background_subtraction conda env create -f environment.yml conda activate backsub_env + +pip install -e . ``` -You can now run Backsub locally (note that you need to point to the tool's script): -``` -python backsub/background_sub.py -h + +Run with +```bash +python -m backsub.background_sub --help ``` ## Execution and usage @@ -155,4 +177,6 @@ This project is licensed under the terms of the [MIT License](https://github.com If you use Backsub in your work, please cite it as: -> Bestak, K., Perez, V., & Wuennemann, F. (2025). Backsub: pixel-by-pixel channel subtraction tool for multiplexed immunofluorescence data. +> Bestak, K., Perez, V., & Wuennemann, F. (2025). +> **Backsub: a pixel-by-pixel channel subtraction tool for multiplexed immunofluorescence data.** +> Available at: [https://github.com/SchapiroLabor/Background_subtraction](https://github.com/SchapiroLabor/Background_subtraction) diff --git a/backsub/_version.py b/backsub/_version.py index e987ec7..b4ff479 100644 --- a/backsub/_version.py +++ b/backsub/_version.py @@ -1,2 +1,2 @@ # backsub/_version.py -__version__ = "0.5.0" +__version__ = "0.5.1"