Staging module for Miltenyi - MACSIMA to MCMICRO

The tool macsima2mc stages MACSima data sets for being registered with ASHLAR in MCMICRO.

After installation the tool is executed via the command macsima2mc, which offers a CLI where the main inputs are path to the cycle folder that contains the tiles generated by the Miltenyi-MACSima platform. The cycle folder generated by the platform follows the nomenclature (N_CycleX),where N is an integer and X is the cycle number. macsima2mc reads the .tif files inside this folder and distributes them into acquisition groups. i.e tiles with common rack, well, ROI and exposure levels will be written into an ome.tiff file with the necessary metadata for registration. To be more precise two such ome.tiff files will be generated per cycle, one corresponds to the background signal and the other to the markers signal.

CLI

After installation you can print the cli arguments in your terminal by running:

macsima2mc --help

Required arguments

Argument	Long name	Type	Description	Default value
-i	string/path	--input	Absolute path to the the parent folder of the raw tiles, i.e. the cycle folder whose name follows the pattern X_Cycle_N,where N represents the cycle number	NA
-o	string/path	--output	Absolute path to the directory in which the outputs will be saved. If the output directory doesn't exist it will be created.	NA

Optional arguments

Argument	Type	Long name	Description	Default value
-rm	string	--reference_marker	Name of the reference marker for registration	'DAPI'
-osd	string	--output_subdir	String specifying the name of the subfolder in which the staged images will be saved.	'raw'
-ic	boolean flag	--illumination_correction	Give this flag to apply illumination correction to all tiles, the illumination profiles are calculated with basicpy	FALSE
-he	boolean flag	--hi_exposure_only	Give this flag to extract only the set of images with the highest exposure time	FALSE
-rr	boolean flag	--remove_reference_marker	mark the removal of the reference marker ,e.g. DAPI, for all cycles except the first one	FALSE
-qc	boolean flag	--qc_metrics	measure features of contrast, intensity and sharpness of each tile in the cycle and appends them to a table	FALSE
-wt	boolean flag	--write_table	writes a table with the acquisition parameters, metadata and,if enabled, qc metrics of each tile. Table will be saved in --output/cycle_info	FALSE

Installation via pip

Windows

BaSicPy(v2.0.0) is a dependency required by macsima2mc(>=v1.3.0). BaSicPy 2.0.0 requires pytorch, which is better handled by conda environments in Windows. Thus, install first pytorch in a fresh conda environment and only afterwards install macsima2mc:

# Create conda environment
conda create -n your_env  python=3.12

# Activate environment
conda activate your_env

# Install PyTorch 2.11.0+cpu via pip (using the official PyTorch index)
pip install torch==2.11.0+cpu --index-url https://download.pytorch.org/whl/cpu

# Install your package
pip install macsima2mc

Linux/macOS

# Install your package
pip install macsima2mc

Check if pip installation was successful by printing the CLI:

macsima2mc --help

Container

Downloading a container to use the tool is also possible. Pull the container file via Docker or Singularity:

• Docker

docker pull ghcr.io/schapirolabor/macsima2mc:v1.3.0

or

• Singularity

singularity pull docker://ghcr.io/schapirolabor/macsima2mc:v1.3.0

Usage example

The example below shows how to run the command macsima2mc via the singularity container in a bash script. The logic of execution and CLI usage is the same for a Docker container or as pypi package.

# Give the absolute path to the container file you pulled
container_file=C:/MyLocalVolume/macsima2mc:v1.3.0.sif
# Give the absolute path to where you want your output files to be written
output_dir=C:/MyLocalVolume/output
# Path to the directory containing all the cycle folders (N_CycleX)
input_dir=C:/MyLocalVolume/ROI_01


# Loop over the absolute path of all the N_CycleX folders
for cycle in $input_dir/*Cycle*;
do
# Extract just the name of the cycle folder
cycle_folder=$(basename "$cycle")
# Execute macsima2mc with singularity using the container file (adapt accordingly if using docker or just the pip installation)
singularity exec --bind $sample:/mnt,$output_dir:/media --no-home $container_file macsima2mc -i /mnt/$cycle_folder -o /media -ic
#IF DOCKER : docker run -v $sample:/mnt -v $output_dir:/media $container_image macsima2mc -i /mnt/$cycle_folder -o /media -ic
# IF PIP PACKAGE:  macsima2mc -i $cycle -o $output_dir -ic
done

macsima2mc and ASHLAR

It is important that when you use ASHLAR to stitch and register the files produced by macsima2mc, you use the argument --flip-y in the ASHLAR CLI. This is just to account for the inverted axis orientation with which the position of the tiles in the MACSima platform are recorded.