Introduction

qbic-pipelines/spatial-lattice is a bioinformatics pipeline for the processing of multiplexed imaging data generated by the MACSima Imaging Cyclic Immunofluorescence (MACSima) platform, optionally register with corresponding H&E stained tissue sections.

The pipeline takes raw MACSima ROI cycle folders or a complete study (and, optionally, H&E images), stages, converts and optionally performs inetnsity correction of the raw acquisition data with macsima2mc, registers the individual tiles into whole-slide images with ASHLAR, and performs optional background subtraction, cell/nuclei segmentation with Cellpose 3, Cellpose 4 and/or Mesmer, and H&E tissue segmentation. It can process either a single ROI at a time or an entire MACSima project folder in batch, automatically extracting the experimental metadata (experiment, rack, well, ROI) from the directory structure. The final output is a set of registered, and optionally segmented whole-slide images together with a MultiQC report summarising the run.

The pipeline consists of the following default steps:

1. Load raw MACSima ROI cycle folders (and optional H&E images) from the samplesheet or project folder.
2. Stage, convert, and correct the raw MACSima acquisition data with macsima2mc, producing per-acquisition-group ome.tif images and marker sheets.
3. Register the individual tiles into whole-slide images with ASHLAR.
4. Perform background subtraction with BACKSUB (optional, enabled by default).
5. Segment the MACSima images with one or more tools selected via --segmentation (MACSIMA_SEGMENTATION): Cellpose 3, Cellpose 4 / Cellpose-SAM (default) and Mesmer.
6. Perform H&E tissue segmentation with STAINSEGMY (optional, disabled by default).
7. Collate software versions and generate a MultiQC report.

Usage

Note

If you are new to Nextflow and nf-core, please refer to this page on how to set-up Nextflow. Make sure to test your setup with -profile test before running the workflow on actual data.

First, prepare a samplesheet with your input data that looks as follows:

project_samplesheet.csv (used when --project is enabled, the default):

project,MACSima_project_folder,HnE_folder
PROJECT_1,/path/to/macsima/project/folder,/path/to/hne/folder

Each row represents a MACSima project. When --project is set, the pipeline walks the project directory structure and automatically extracts the experiment, rack, well, and ROI metadata from the folder hierarchy, so no per-ROI information is required in the samplesheet.

samplesheet.csv (used when --project is disabled):

experiment,rack,well,roi,raw_images_ROI,HnE_ROI
EXP_1,R1,A1,ROI1,/path/to/raw/roi/folder,/path/to/hne/roi/file

Each row represents a single ROI to be processed. The raw_images_ROI column points to the parent folder of the raw MACSima tiles, which contains one or more cycle folders.

Now, you can run the pipeline using:

nextflow run nf-core/spatiallattice \
   -profile <docker/singularity/.../institute> \
   --input samplesheet.csv \
   --outdir <OUTDIR>

Warning

Please provide pipeline parameters via the CLI or Nextflow -params-file option. Custom config files including those provided by the -c Nextflow option can be used to provide any configuration except for parameters; see docs.

For more details and further functionality, please refer to the usage documentation and the parameter documentation.

Pipeline output

To see the results of an example test run with a full size dataset refer to the results tab on the nf-core website pipeline page. For more details about the output files and reports, please refer to the output documentation.

Credits

qbic-pipelines/spatial-lattice was originally written by Carolin Schwitalla in collaboration with Maximilian Wirth, Victor Perez, Luis Kuhn Cuellar, and Nadya Panagides.

We thank the following people for their extensive assistance in the development of this pipeline:

Thusheera Kumarasekara

Contributions and Support

If you would like to contribute to this pipeline, please see the contributing guidelines.

For further information or help, don't hesitate to get in touch or open issues.

Citations

An extensive list of references for the tools used by the pipeline can be found in the CITATIONS.md file.

You can cite the nf-core publication as follows:

The nf-core framework for community-curated bioinformatics pipelines.

Philip Ewels, Alexander Peltzer, Sven Fillinger, Harshil Patel, Johannes Alneberg, Andreas Wilm, Maxime Ulysse Garcia, Paolo Di Tommaso & Sven Nahnsen.

Nat Biotechnol. 2020 Feb 13. doi: 10.1038/s41587-020-0439-x.