Background_subtraction

Pixel-by-pixel channel subtraction scaled by exposure times, primarily developed for images produced by the COMET platform and to work within the MCMICRO pipeline. Main usecase is autuofluorescence subtraction for multichannel and multicycle images for visualization of images from tissues with high autofluroescence (FFPE), improved segmentation, and quantification (if the previous two usecases aren't necessary, downstream subtraction of autofluorescent signal is encouraged as the script is memory inefficent).

Introduction

If there are background (autofluorescence) channels present in a .tif image, background subtraction should be performed so as not to skew the quantification counts of markers. The most precise way of subtracting background would be on a pixel-to-pixel basis. An alternative would be on a cell basis by just subtracting the background measurements from the marker measurements for each cell, however, for visual inspection of images, as well as future use of images as figures in published work, it is preferred to use this.

Background subtraction is performed using the following formula:

Marker_corrected = Marker_raw - Background / Exposure_Background * Exposure_Marker

Usage

The markers.csv file which gives details about the channels needs to contain the following columns: "marker_name", "background" and "exposure". An exemplary markers.csv file is given. The "marker_name" column should indicate the marker for the acquired channel and all values should be unique. The "background" column should indicate the marker name of the channel which needs to be subtracted. This value must match the "marker_name" value of the background channel. The "exposure" column should contain the exposure time used for channel acquisition, and the measure unit should be consistent across the column. Exposure time is used for scaling the value of the background to be comparable to the processed channel. The "remove" column should contain logical TRUE values for channels which should be excluded in the output image.

Version v0.5.10:

This version, which is a rework of v0.4.1, introduces the following features:

• File-size of output image is reduced by using lossless compression ("LZW").
• Facilitates container creation by prescinding from PALOM and opencv libraries.
• Introduces the hidden argument, -comet, which extracts the metadata on-the-fly for Lunaphore Comet images. When using this argument, the markers.csv file is not required.
• Two RAM-profiles: (1) default mode, uses moderate RAM. (2) Uses approximately half-of the RAM of profile 1 at the cost of a slight loss in precision of the calculation of the downsized dimensions of the pyramidal output image. This means the dimensions of the pyramidal level will differ between profile 1 and 2, the high-resolution level is not affected by this.
• Organizes the tool in five scripts: (1) CLI, (2) ome-schema structure, (3) ome-schema writer, (4) background substraction and writing of output image and (5) extraction of metadata from Lunaphore Comet images.
• Logger has been re-designed.

Versions v0.4.1 and newer:

The script has been rewritten to perform channel subtraction in a RAM-efficient manner - updating is highly recommended. If the output file is much bigger than expected, adjust the --tile-size parameter to a smaller value (e.g 512). Changing the --chunk-size parameter may affect performance (lower values increase execution time, higher values increase RAM usage).

Versions v0.2.0 and older:

The markers.csv file which gives details about the channels needs to contain the following columns: "Filter", "background" and "exposure". An exemplary markers_old.csv file is given. The "Filter" column should specify the Filter used when acquiring images. If different stains are aquired with the same filter, the exact same value needs to be written (including background) as it is used for determining which background channel should be subtracted. The "background" column should contain logical TRUE values for channels which represent autofluorescence. The "exposure" column should contain the exposure time used for channel acquisition, and the measure unit should be consistent across the column. Exposure time is used for scaling the value of the background to be comparable to the processed channel.

CLI

Minimal required arguments:

• the path to the input image given with -r or --root
• the path to the output image given with -o or --output
• the path to the markers.csv file given with -m or --markers
• the path to the markers output file given with -mo or --markerout

Optional arguments:

• -mpp or --pixel-size microns per pixel, i.e. pixel size of the input image in microns. If not specified the script will attempt to extract the pixel size and its units from the metadata, if failed, it will assign a pixel size of 1 with "pixel" as units.
• -pl or --pyramid_levels total number of pyramidal levels of the output image, this number should also include the high-resolution level. Default value is 8, this argument will be only implemented if the input image is not pyramidal. If input image is pyramidal, the output image will have the same levels and this argument will be ignored.
• -sr or --save_ram using this argument will provide the low RAM usage of version 0.4.1.
• --version to print version.

Hidden argument !!!:

• -comet Flag to obtain the markers table on the fly for images acquired with the reference background acquisition implemented in the Lunaphore Comet at the TSPC (https://www.tspc-hd.com/). When this flag is used, the argument -m/--markers is ignored since the markers information will be extracted from the metadata of the input image.

Output

The output image file will be a pyramidal ome.tif 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.

Docker usage

If you want to run the background subtraction directly from a pre-configured container with all the required packages, you can either build the docker container yourself or pull it from the Github container registry.

To build the container run:

git clone https://github.com/SchapiroLabor/Background_subtraction.git
docker build -t background_subtraction:latest .
docker run background_subtraction:latest python background_sub.py

To pull the container from the Github container registry (ghcr.io):

## Login to ghcr.io
docker login ghcr.io

## Pull container
docker pull ghcr.io/schapirolabor/background_subtraction:latest