A flexible multiplexed image segmentation pipeline based on pixel classification

Introduction

The pipeline is based on CellProfiler (tested v4.2.1) for segmentation and Ilastik (tested v1.3.3post3) for pixel classification. It is streamlined by using the imcsegpipe python package available via this repository as well as custom CellProfiler modules (ImcPluginsCP, release v4.2.1).

This repository showcases the basis of the workflow with step-by-step instructions. As an alternative and dockerized version of the pipeline, check out steinbock.

This pipeline was developed in the Bodenmiller laboratory at the University of Zurich (www.bodenmillerlab.com) to segment hundreds of highly multiplexed imaging mass cytometry (IMC) images. The concepts applied here to IMC data can also be transfered to data generated by other highly multiplexed imaging modalities.

For a general overview on IMC as technology and data processing tasks, please refer to bodenmillergroup.github.io/IMCWorkflow.

Usage

For the main part of the analysis, you will need to install Ilastik and CellProfiler.

Before being able to pre-process the data, you will need to setup the environment:

1. Install conda

2. Clone the repository:

git clone --recursive https://github.com/BodenmillerGroup/ImcSegmentationPipeline.git

3. Setup the conda environment:

cd ImcSegmentationPipeline
conda env create -f environment.yml

4. Configure CellProfiler to use the plugins by opening the CellProfiler GUI, selecting Preferences and setting the CellProfiler plugins directory to path/to/ImcSegmentationPipeline/resources/ImcPluginsCP/plugins and restart CellProfiler. Alternatively you can clone the ImcPluginsCP repository individually and set the path correctly in CellProfiler.

5. Activate the environment created in 3. and start a jupyter instance

conda activate imcsegpipe
jupyter lab

This will automatically open a jupyter instance at http://localhost:8888/lab in your browser. From there, you can open the scripts/imc_preprocessing.ipynb notebook and start the data pre-processing.

In brief, the main analysis steps include:

1. Pre-processing of the raw images to create .ome.tiffs and .tiff stacks for ilastik training and measurement (python).
2. Ilastik pixel classification based on random crops of the images (CellProfiler, Ilastik).
3. Image segmentation based on the classification probabilities (CellProfiler).
4. Measurement and export of cell-specific features, such as marker expression (CellProfiler).

Example data

To test these pipelines on example data, please run the scripts/download_examples.ipynb script.

Documentation

For a more detailed overview on the individual analysis steps, please visit https://bodenmillergroup.github.io/ImcSegmentationPipeline/.

This pipeline was presented at the 2019 Imaging Mass Cytometry User Group Meeting. The slides can be downloaded here. The slides briefly explain why we chose this approach to image segmentation and provide help to run the pipeline.

Changelog

For changes in specific releases, please refer to the CHANGELOG.

License

We freely share this pipeline in the hope that it will be useful for others to perform high quality image segmentation and serve as a basis to develop more complicated open source IMC image processing workflows. In return we would like you to be considerate and give us and others feedback if you find a bug/issue and raise a GitHub Issue on the affected projects or on this page.

Contributing

To contribute to this work, please fork the repository, make changes to it and open a pull request.

Contributors

Creator: Vito Zanotelli

Contributor: Jonas Windhager, Nils Eling, Milad Adibi

Maintainer: Milad Adibi

Citation

Please cite the following paper when using this workflow in your research:

Windhager, J., Zanotelli, V.R.T., Schulz, D. et al. An end-to-end workflow for multiplexed image processing and analysis. Nat Protoc (2023). https://doi.org/10.1038/s41596-023-00881-0

@article{Windhager2023,
    author = {Windhager, Jonas and Zanotelli, Vito R.T. and Schulz, Daniel and Meyer, Lasse and Daniel, Michelle and Bodenmiller, Bernd and Eling, Nils},
    title = {An end-to-end workflow for multiplexed image processing and analysis},
    year = {2023},
    doi = {10.1038/s41596-023-00881-0},
    URL = {https://www.nature.com/articles/s41596-023-00881-0},
    journal = {Nature Protocols}
}