Metadata-Version: 2.4
Name: backsub
Version: 0.5.2
Summary: Channel subtraction scaled by exposure times
Author-email: Krešimir Bestak <kbestak@gmail.com>
License: MIT License
        
        Copyright (c) 2022 SchapiroLabor
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/schapirolabor/background_subtraction
Project-URL: Issues, https://github.com/schapirolabor/background_subtraction/issues
Keywords: autofluorescence,imaging,immunofluorescence,subtraction
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: dask
Requires-Dist: dask-image
Requires-Dist: imagecodecs
Requires-Dist: loguru
Requires-Dist: numpy
Requires-Dist: ome_types
Requires-Dist: pandas
Requires-Dist: psutil
Requires-Dist: scikit-image
Requires-Dist: tifffile
Requires-Dist: zarr>=3
Dynamic: license-file

# Backsub - pixel-by-pixel channel subtraction tool for multiplexed immunofluorescence data
[![PyPI](https://img.shields.io/pypi/v/backsub?style=flat-square)](https://pypi.org/project/backsub/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/backsub?style=flat-square)](https://pypi.org/project/backsub/)
[![PyPI - License](https://img.shields.io/pypi/l/backsub?style=flat-square)](https://pypi.org/project/backsub/)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/backsub?style=flat-square)](https://pypi.org/project/backsub/)

Backsub performs pixel-by-pixel background subtraction between marker and background channels scaled by their respective exposure times. The outputs are saved as pyramidal OME-TIFF files. It was originally developed for data produced by the Lunaphore COMET platform and is fully compatible with the [MCMICRO](https://mcmicro.org) pipeline.


Example of pixel-wise autofluorescence subtraction with Backsub:
<p align="left">
  <img src="https://raw.githubusercontent.com/SchapiroLabor/Background_subtraction/main/example/application_example.png" alt="Background subtraction example" width="750">
</p>

## Introduction

In multiplexed immunofluorescence images, autofluorescence and background signals can cause improper cell segmentation, and can affect downstream intensity quantification which is why, if possible, they should be subtracted from raw channel intensities. The most precise way of subtracting background would be on a pixel-to-pixel basis. An alternative would be to subtract the background measurements from the marker measurements for each cell after quantification, however, for visual inspection of images, segmentation, and data presentation, it is preferred to use the corrected values.

The primary use case is autofluorescence subtraction for multichannel and multicycle microscopy images to improve:
* image visualization of tissues with strong autofluorescence
* segmentation accuracy
* quantification quality (if the previous two usecases are not necessary, downstream subtraction of autofluorescence signal is encouraged instead)

Background subtraction is performed using the following formula:

Marker_corrected = Marker_raw − Background × (Exposure_Marker / Exposure_Background)

## Installation

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.  
Backsub requires Python >=3.11

### Option 1: Install from PyPI

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 \
    backsub \
    -r /data/input_image.tif \
    -o /data/corrected_image.ome.tif \
    -m /data/markers.csv \
    -mo /data/markers_corrected.csv
```

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 backsub:latest .
```

### 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 .
```

Run with
```bash
python -m backsub.background_sub --help
```

## Execution and usage

### Inputs

A `TIFF` or `OME-TIFF` file containing multiplexed immunofluorescence data.

A `markers.csv` file should be provided to describe the channels of the image. Needs to contain the following columns:

| Column      	| Description                                                                                                                                                                                                                                    	| Required 	|
|-------------	|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------	|----------	|
| marker_name 	| Contains the channel names, all values **must** be unique.                                                                                                                                                                                     	| yes      	|
| background  	| Specifies the channel that should be subtracted from the specified channel. The `background` value, if present, **must** match the `marker_name` value of the background channel. If no subtraction is necessary, the field can be left empty. 	| yes      	|
| exposure    	| Contains the exposure time used for channel acquisition in ms.                                                                                                                                                                                 	| yes      	|
| remove      	| Optional column that allows the user to exclude certain channels from the output file by setting that channel's `remove` value to `TRUE`.                                                                                                       	| no       	|

An exemplary [markers.csv](https://github.com/SchapiroLabor/Background_subtraction/blob/main/example/markers.csv) file is provided.

### Command Line Interface

| Argument 	| Long form          	| Description                                                                                                                                                                                                                                                         	| Specification                                                	| Default 	| Required 	|
|----------	|--------------------	|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------	|--------------------------------------------------------------	|---------	|----------	|
| -in      	| --input            	| File path to the input image file.                                                                                                                                                                                                                                  	| string, ends with `.tif`, `.tiff`, `.ome.tif` or `.ome.tiff` 	|         	| yes      	|
| -o       	| --output           	| File path where the output pyramidal OME-TIFF will be saved.                                                                                                                                                                                                        	| string, ends with `.ome.tif` or `.ome.tiff`                  	|         	| yes      	|
| -m       	| --markers          	| File path to the markers (CSV) file containing the list of marker names and their respective background channels.                                                                                                                                                   	| string, ends with `.csv`                                     	|         	| yes      	|
| -mo      	| --marker-output        	| File path where the output marker (CSV) file matching the output image will be saved.                                                                                                                                                                               	| string, ends with `.csv`                                     	|         	| yes      	|
| -mpp     	| --pixel-size       	| Pixel size provided in microns (microns per pixel). If not provided, image metadata will be checked. If that is not successful, the value will be set to 1.                                                                                                         	| float                                                        	| None    	| no       	|
| -sr      	| --save-ram         	| Optional flag to approximately cut RAM usage in half. Note that the dimensions of the reduced resolution levels (sub-levels) of the output pyramidal image will slightly differ whether or not the argument is used.                                                	| boolean flag                                                 	| false   	| no       	|
| -comp    	| --compression      	| The output pyramidal OME-TIFF will be compressed using the specified compression. Set to "none" for no compression.                                                                                                                                                 	| string, either "lzw", "zlib", or "none"                      	| "zlib"   	| no       	|
| -ts      	| --tile-size        	| Tile size used for writing pyramidal outputs. Note that the file size is smaller for smaller tile size values.                                                                                                                                                      	| integer, multiple of 16                                      	| 256     	| no       	|
| -dsf     	| --downscale-factor 	| Downscale factor for pyramid layer creation. This value will only be used if the input image is NOT pyramidal. If the input image is pyramidal, the number of levels in the output image will be the same as in the input so the downscale factor won't be applied. 	| integer, larger than 1                                       	| 2       	| no       	|
| -v       	| --version          	| Prints Backsub version.                                                                                                                                                                                                                                             	|                                                              	|         	|          	|

Example of a full command (note to provide full paths where applicable):
```
python Background_subtraction/backsub/background_sub.py \
    --input /data/input_image.tif \
    --output /data/corrected_image.ome.tif \
    --markers /data/markers.csv \
    --marker-output /data/markers_corrected.csv \
    --pixel-size 0.65 \
    --tile-size 256 \
    --downscale-factor 2 \
    --compression zlib
```

### Outputs

The output image file will be a pyramidal `OME-TIFF` file containing the processed channels. The channels tagged for removal will be excluded from the final image.

The output markers file will be a `CSV` file containing the following columns: "marker_name", "background", "exposure". The "marker_name" column will contain the marker names of the processed channels. The "background" column will contain the marker names of the channels used for subtraction. The "exposure" column will contain the exposure times of the processed channels. 

## Features

* Pixel-wise channel subtraction scaled by exposure time.
* Autofluroescence correction for multiplexed immunofluroescence images.
* Pyramidal OME-TIFF output compatible with the MCMICRO pipeline.
* Optional image compression to not bloat data size of large projects.
* Low-memory mode for local processing of large datasets.
* Automatic metadata extraction for Lunaphore COMET data.

## Contributing

Contributions are welcome! If you would like to contribute, please:
1. Fork the repository
2. Create a feature branch:
```
git checkout -b feature/my-feature
```
3. Commit your changes and open a pull request

For questions of issues, please open a GitHub issue.

## Contributors

Author and maintainer:
* [Krešimir Beštak](@kbestak)

Contributors: 
* [Victor Perez](@VictorDidier)
* [Florian Wünnemann](@FloWuenne).

## Changelog

See the [CHANGELOG](https://github.com/SchapiroLabor/Background_subtraction/blob/main/CHANGELOG.md) file for deatils about new features, bug fixes, and version history.

## License

This project is licensed under the terms of the [MIT License](https://github.com/SchapiroLabor/Background_subtraction/blob/main/LICENSE).

## Citation

If you use Backsub in your work, please cite it as:

> 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)
