MCMICRO - End to End Microscopy Image Processing


A user has two options for starting an analysis using MCMICRO:

  1. Create a project and upload raw image files (.tiff, .tif, .ome.tiff are currently the only supported formats), navigate to the “Public Apps Gallery” and search for MCMICRO then copy it to your project.
  2. Navigate to the Public Projects Gallery, find “MCMICRO” and copy the project to your own workspace. From there, navigate to “tasks”, then “re-run” to reproduce any of the already-completed analyses.

Please note: Users will soon also be able to interact with the MCMICRO pipeline via Galaxy instance running on the CGC.


At the minimum, the pipeline expects two inputs

  1. markers.csv
  2. Raw images


The file markers.csv must be in a comma-delimited format and contain a column titled marker_name that defines marker names of every channel:

Example markers file:


All other columns are optional but can be used to specify additional metadata (e.g., known mapping to cell types) to be used by individual modules.

Raw images

The exemplar raw files are in the open standard OME-TIFF format, but in practice your input files will be in whatever format your microscope produces. The pipeline supports all Bio-Formats-compatible image formats, but additional parameters may be required.

(Optional) Illumination corrected images

Pre-computed flat-field and dark-field illumination profiles can be uploaded to your project. If no pre-computed profiles are available, MCMICRO can compute these using BaSiC.

An example of the typical inputs for a MCMICRO run are depicted below:


MCMICRO uses default values for any settings not specified as a parameter setting. MCMICRO will resolve conflicting parameter values with a priority list.

Parameters can be supplied on the CGC by defining the “App Settings” on the Task Run page.


An example task with set parameters may look as follows:

To learn more about each of these modules and settings, go to “MODULE OPTIONS”.


Stitching and registration

ASHLAR is the default first step of the pipeline. ASHLAR will aggregate individual image tiles from raw/ along with the corresponding illumination profiles to produce a stitched and registered mosaic image.

This mosaic image will be published to the files/Examplar1 subdirectory:

├── illumination/ 
    └── exemplar-001-cycle-08.ome-ffp.tif 
    └── exemplar-001-cycle-08.ome-dfp.tif 
    └── exemplar-001-cycle-07.ome-ffp.tif 
    └── exemplar-001-cycle-07.ome-dfp.tif 
    └── exemplar-001-cycle-06.ome-ffp.tif 
    └── exemplar-001-cycle-06.ome-dfp.tif 
├── quantification/ 
├── segmentation/ 
├── viz/ 
├── downstream/ 

The output filename will be generated based on the name of the project directory.

(Optional) TMA dearray

When working with Tissue Microarrays (TMA), Coreograph is used for TMA dearraying. The viz/ folder will contain an image of the entire TMA. Turn on the tma setting on the task page to have MCMICRO identify and isolate individual cores.

Each core will be written out into a standalone file in the viz/ subdirectory along with the mask specifying where in the original image the core appeared:

├── illumination/ 
├── quantification/ 
├── segmentation/ 
├── viz/ 
    └── Exemplar1_reg.ome/ 
     └── index.html 
├── downstream/ 

All cores will then be processed in parallel by all subsequent steps.


Cell segmentation is carried out in two steps. First, the pipeline generates probability maps that annotate each pixel with the probability that it belongs to a given subcellular component (nucleus, cytoplasm, cell boundary) using UnMICST (default) or Ilastik. The second step applies standard watershed segmentation to produce the final cell/nucleus/cytoplasm/etc. masks using S3segmenter.

The two steps will appear in downstream/scimap*/ and segmentation directories, respectively. When there are multiple modules for a given pipeline step, their results will be subdivided into additional subdirectories:

├── illumination/ 
├── quantification/ 
├── segmentation/ 
├── viz/ 
├── downstream/ 
  └── scimap_Exemplar1_reg__Ilastik_cell/ 
    └── plots/ 


The final step, MCQuant, combines information in segmentation masks, the original stitched image and markers.csv to produce Spatial Feature Tables that summarize the expression of every marker on a per-cell basis, alongside additional morphological features (cell shape, size, etc.).

Spatial Feature Tables will be published to the quantification/directory:

├── ... 
├── segmentation/ 
└── quantification/ 
    ├── Exemplar1_reg__Ilastik_cell.csv  
    └── Exemplar1_reg__Ilastik_nuclei.csv 

Each .csv file will contain the following columns:

  • CellID - cell index that is extracted from the segmentation mask
  • All columns with names matching those in markers.csv - average intensity of that channel in the cell/nuclei area
  • All other columns will contain morphological features.


Upon the full successful completion of a pipeline run on the CGC, the directory structure will follow Fig. 1A in the MCMICRO manuscript:

Note:This directory should correspond directly to the CWL workflow. For the Nextflow or Galaxy workflow, the intermediaries and output files should be identical, but the organization of the files within directories and the filenames will be different.


Directory Structure

├── illumination/ 
├── quantification/ 
├── segmentation/ 
├── viz/ 
├── downstream/ 

The name of the parent directory (e.g., Exemplar1) can be specified by the user on the task run page. Otherwise, it is assumed by the pipeline to be the sample name.


Parameters under the Task Run page regulate the function of individual modules in the pipeline. Parameters are matched to the appropriate module.

Core Modules

All modules in MCMICRO are available as standalone executable Docker containers. When running modules within MCMICRO, the inputs and outputs will be handled by the pipeline and do not need to be specified explicitly.


Illumination correction


The module implements the BaSiC method for correcting uneven illumination, developed externally by (Peng et al., 2017). The module doesn’t have any additional parameters.


By default, MCMICRO skips this step as it requires manual inspection of the outputs to ensure that illumination correction does not introduce artifacts for downstream processing.


Stitching and registration


The module performs simultaneous stitching of tiles and registration across channels. Check the ASHLAR website for the most up-to-date documentation.


MCMICRO runs ASHLAR by default.

Maximum allowed per-tile corrective shift in microns (default: 15), can be altered on the Task Run page.

Running outside of MCMICRO: ASHLAR website.


TMA core detection and dearraying


The modules use the popular UNet deep learning architecture to identify cores within a tissue microarray (TMA). After identifying the cores, it extracts each one into a separate image to enable parallel downstream processing of all cores.


By default, MCMICRO assumes that the input is a whole-slide image.

Set Is TMA: true on the Task Run page to indicate that the input is a TMA instead.

Running outside of MCMICRO: Instructions.


Image segmentation - probability map generation

There are several options for image segmentation on the CGC MCMICRO workflow.

Set any of the following segmentations algorithms to True on the Task Run page to run the segmentation.

Run Cellpose Segmentation 
Run Cypository Segmentation 
Run Ilastik Segmentation 
Run Mesmer Segmentation 
Run UnMICST Segmentation

For information on the aforementioned segmentation algorithms, read on.



Cellpose is a deep learning segmentation algorithm able to segment the nuclear or cytoplasmic compartments of the cell. Publications of this algorithm can be found in 1 and 2. A thorough documentation of the script and CLI can be found here.


To use this segmentation method set Run Cellpose Segmentation: True in the App Settings of the Task Run page.

Running outside of MCMICRO: Github, Instructions.



Cypository is used to segment the cytoplasm of cells. Check the GitHub repository for the most up-to-date documentation.


To use this segmentation method set Run Cypository Segmentation: True in the App Settings of the Task Run page.



The module provides a command-line interface to the popular ilastik toolkit and serves as another method for generating probability maps that can be used as an alternative to UnMICST. Check the GitHub for the most up-to-date documentation.


To use this segmentation method set Run Ilastik Segmentation: True in the App Settings of the Task Run page. Specify numbers of channels to use. If specific channels are not given, channels in range(0,num_channels) are used in ilastik.

Optional arguments

NameDescriptionDefault Value
\--number of channelsThe numerical index of the channel(s) from nuclear-image to select.0



The Mesmer module provides an alternative segmentation approach to UnMicst and ilastik. It is implemented and maintained by an external group. Check their GitHub repository for the most up-to-date information.


To use this segmentation method set Run Mesmer Segmentation: True in the App Settings of the Task Run page.

Additional Mesmer parameters can be provided in the App Settings of the Task Run page.

Running outside of MCMICRO: Instructions.

Optional arguments

NameDescriptionDefault Value
\--nuclear-channelThe numerical index of the channel(s) from nuclear-image to select. If multiple values are passed, the channels will be summed.0
\--image-mppThe resolution of the image in microns-per-pixel. A value of 0.5 corresponds to 20x zoom.0.5



UnMICST uses a convolutional neural network to annotate each pixel with the probability that it belongs to a given subcellular component (nucleus, cytoplasm, cell boundary). Check the UnMICST website for the most up-to-date documentation.


MCMICRO applies UnMicst to all input images by default. To use this segmentation method set Run UnMICST Segmentation: True in the App Settings of the Task Run page.


Spatial analysis


SCIMAP is a suite of tools that enables spatial single-cell analyses. Check the SCIMAP website for the most up-to-date documentation.


MCMICRO allows users to automatically apply SCIMAP’s clustering algorithms to the cell-by-feature table produced by MCQuant. The clustering results can be subsequently used for manual assignment of cell states. Since MCMICRO stops at MCQuant by default, users will need to explicitly request that the pipeline continues to the clustering step. MCMICRO’s usage of SCIMAP doesn’t have any parameters, and users are encouraged to check the SCIMAP website for more sophisticated human-in-the-loop analyses.


  1. A table of cluster assignments for each cell by the different clustering algorithms implemented within SCIMAP. These tables will be generated in .csv and .h5ad formats.
  2. A set of UMAP plots for the different clustering algorithms, with individual plots written to the plots/ subdirectory in .pdf format.



MCMICRO integrates three methods for clustering single-cell data. These are FastPG (Fast C++ implementation of the popular Phenograph method), Leiden community detection via scanpy, and FlowSOM.


MCMICRO applies these methods to the workflow by default.

Running outside of MCMICRO:


All methods output a .csv file annotating individual cells with their cluster index. Nextflow will write these files to the plots/ subfolder within the project directory.