MapMet - Image Processing Pipeline

This repository is currently under development.

This code supplements the publication (in preparation) by Lazic et al. Therein, we use 3-plex immmunofluorescence (IF) microscopy and 41-plex imaging mass cytometry (IMC) to spatially and temporally map primary and metastatic neuroblastoma. The image processing pipeline can be largely divided into the following steps:

1. Segmentation based on nuclear IF (DAPI) image using cellpose [1] model finetuned on our own data - individual models were trained for primary tumor (CP_TU) and metastatic bone marrow samples (CP_BM)
2. Registration between IF and IMC images/masks via scale-invariant feature transformation (SIFT) [2]
3. Spillover compensation of IMC images according to [3]
4. DIMR hot pixel removal according to [4]
5. Background correction and normalization using background/foreground classifiers trained in Ilastik [5] - individual models were trained for each marker and tissue type (primary tumor/bone marrow)
6. Feature Extraction: extraction of marker intensity and morphological features

Download data

Download cellpose models, spillover measurements and ilastik classifiers

In order to be able to use the segmentation, spillover compensation and background correction within MapMetIP, the fine-tuned cellpose models, spillover measurements and ilastik-trained background/foreground classifiers have to be downloaded from zenodo.

Replace path/to/extract/directory with the absolute path to the directory, where the data should be stored.

wget -P <path/to/extract/directory> https://zenodo.org/records/13220635/files/MapMetIP_models.zip
unzip <path/to/extract/directory>/MapMetIP_models.zip -d <path/to/extract/directory>
rm <path/to/extract/directory>/MapMetIP_models.zip

Download test dataset

We prepared a small test dataset with one representative primary tumor and bone marrow sample to be used in the notebooks for demonstration purposes. Replace path/to/extract/directory with the absolute path to the directory, where the data should be stored.

wget -P <path/to/extract/directory> https://zenodo.org/records/13220635/files/MapMetIP_TestDataset.zip
unzip <path/to/extract/directory>/MapMetIP_TestDataset.zip -d <path/to/extract/directory>
rm <path/to/extract/directory>/MapMetIP_TestDataset.zip

Download full dataset

The entire dataset containing all IF and IMC images from Lazic et al. has a size of ~69 GB (even after h5 compression with compression level 7). For download, replace path/to/extract/directory with the absolute path to the directory, where the data should be stored.

wget -P <path/to/extract/directory> https://zenodo.org/records/13220635/files/MapMetIP_FullDataset.zip
unzip <path/to/extract/directory>/MapMetIP_FullDataset.zip -d <path/to/extract/directory>
rm <path/to/extract/directory>/MapMetIP_FullDataset.zip

Installation

Once models and data have been downloaded, the pipeline can be run either in a Docker container or in your local development environment.

Docker

Follow the instructions provided in this section to set up and run the pipeline within a Docker container. First, clone the repository.

git clone https://github.com/TaschnerMandlGroup/MapMetIP.git

Build the docker image.

cd MapMetIP
docker build -t mapmet_ip .

The docker-based implementation assumes that the R-based docker image for spillover compensation was pulled from docker hub.

docker image pull lazdaria/spillovercomp

Then start the mapmet_ip container, mounting

• the Docker daemon socket (-v /var/run/docker.sock:/var/run/docker.sock) to ensure that the the R-based docker container for spillover compensation can be started from within
• the MapMetIP project directory (-v "$(pwd)":/usr/src/app/MapMetIP) and
• the path to the downloaded data (-v <path/to/extract/directory>:/data)

and allowing access to GPUs on host (--gpus all).

The R-based docker container is launched by the host's Docker daemon, therefore make sure to provide the absolute path to the downloaded data (-e "DOODPATH=<path/to/extract/directory>").

docker run -p 8888:8888 -v /var/run/docker.sock:/var/run/docker.sock -v "$(pwd)":/usr/src/app/MapMetIP  -v <path/to/extract/directory>:/data --gpus all -e "DOODPATH=<path/to/extract/directory>" -it mapmet_ip

A Jupyter Notebook server session can then be accessed via your browser at localhost:8888. The stdout of the started container will provide a token, which has to be copied for login.

Local Development Environment

Follow the instructions provided in this section to run the pipeline in your local development environment. First clone the repository:

git clone https://github.com/TaschnerMandlGroup/MapMetIP.git

It is recommended to install MapMetIP into a conda environment together with other necessary packages. If you are new to conda, please refer to these instructions first.

cd MapMetIP
conda env create -f env.yml

You can then activate the environment:

conda activate mapmet_ip

And install MapMetIP

pip install -e .

Then pull R-based image for spillover compensation:

docker image pull lazdaria/spillovercomp

To be able to use DIMR hot-poxel removal, clone the IMC-Denoise github repository to the parent directory of MapMetIP.

cd ..
git clone --branch v1.0.0 https://github.com/PENGLU-WashU/IMC_Denoise.git

In case problems with Tensorflow versions, occur, add the path to the IMC_Denoise parent directory to your ~/.bashrc:

export PYTHONPATH="${PYTHONPATH}:$(pwd)"

Usage

Notebooks for demonstration

Notebooks, demonstrating each step of the pipeline on the primary tumor sample are provided:

• Demonstration of pipeline on one representative tumor sample (tests/process_TU_sample.ipynb)
• Demonstration of pipeline on one representative bone marrow sample(tests/process_BM_sample.ipynb)

Process multiple samples from CL

First, make sure the conda environment is activated.

conda activate mapmet_ip

To run the complete image processing pipeline on a defined sample, use the command below.

cd MapMetIP
python3 run_all.py -s <sample_name> --data_path <path/to>/MapMetIP_TestDataset --model_path <path/to>/MapMetIP_models --save_dir <path/to/save/results> --log_path <path/to/save/logs>

To run the complete image processing pipeline on a list of samples, use the command below.

cd MapMetIP
python3 run_all.py -s <sample_name1> <sample_name2> <sample_name3> --data_path <path/to>/MapMetIP_TestDataset --model_path <path/to>/MapMetIP_models --save_dir <path/to/save/results> --log_path <path/to/save/logs>

Contributors

Daria Lazic

Simon Gutwein

Citation

Please cite the following paper (in preparation) when using MapMetIP:

Lazic, D., et al. TEMPORAL AND SPATIAL DYNAMICS OF METASTASIS AND THERAPY RESISTANCE IN NEUROBLASTOMA. Journal (2024). https://doi.org/DOI

@article{Lazic2024,
    author = {Lazic, Daria, et al.},
    title = {TEMPORAL AND SPATIAL DYNAMICS OF METASTASIS AND THERAPY RESISTANCE IN NEUROBLASTOMA},
    year = {2024},
    doi = {DOI},
    URL = {URL},
    journal = {Journal}
}

References

• [1] Pachitariu et al. (2022), Nature Methods.
• [2] Mahesh et al. (2012), ICCCNT'12.
• [3] Chevrier et al. (2018), Cell Systems.
• [4] Lu et al. (2023), Nature Communications.
• [5] Berg et al. (2019), Nature Methods.

Funding

This work was funded by the Austrian Science Fund (FWF#I4162 and FWF#35841), the Vienna Science and Technology Fund (WWTF; LS18-111), the Swiss Government Excellence Scholarship and the St. Anna Kinderkrebsforschung e.V.