Introduction

WEHI-SODA-Hub/spatialvpt is a bioinformatics pipeline that performs cell segmentation and creates a QC report for MERSCOPE data using the vizgen-postprocessing tool.

The pipeline runs the following steps:

• tiffsegmentationvpt -- nf-core subworkflow that performs segmentation that uses the vizgen post-processing tool, which runs the following modules:
  • vizgenpostprocessing/preparesegmentation
  • vizgenpostprocessing/runsegmentationontile
  • vizgenpostprocessing/compiletilesegmentation
• vpt convert-geometry (optionally, to convert existing segmentation geometries)
• vptupdatemeta subworkflow, which runs:
  • vpt derive-entity-metadata
  • vpt partition-transcripts
  • vpt update-vzg (optional)
• vpt generate-segmentation-metrics
• Pipeline information - Report metrics generated during the workflow execution

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 parameters file with your input data that looks as follows:

params.yml:

yaml sample: "sample_name" outdir: "/path/to/results" algorithm_json: "/path/to/algorithm.json" images_dir: "/path/to/images" images_regex: "mosaic_(?P<stain>[\\w|-]+)_z(?P<z>[0-9]+).tif" um_to_mosaic_file: "/path/to/micron_to_mosaic_pixel_transform.csv" detected_transcripts: "/path/to/detected_transcripts.csv" update_vzg: true input_vzg: "/path/to/sample.vzg" tile_size: 4096 tile_overlap: 400

Note that the algorithm_json file is temperamental. Check the Vizgen documentation on the requirements.

To run cell segmentation via VPT, you can run the pipeline using:

bash nextflow run WEHI-SODA-Hub/spatialvpt \ -profile <docker/singularity/.../institute> \ -params-file params.yml \ --outdir <OUTDIR>

If you are running with Apptainer or Singularity, you will have to set the following environmental variable before running the pipeline:

Apptainer:

bash export NXF_APPTAINER_HOME_MOUNT=true nextflow run WEHI-SODA-Hub/spatialvpt \ -profile apptainer \ -params-file params.yml \ --outdir <OUTDIR>

Singularity:

bash export NXF_SINGULARITY_HOME_MOUNT=true nextflow run WEHI-SODA-Hub/spatialvpt \ -profile singularity \ -params-file params.yml \ --outdir <OUTDIR>

Custom weights

You can use a custom weights file by specifying the full path in your parameters file:

yaml custom_weights: "/path/to/custom_weights_file"

Now you need to add the file name only to your algorithm JSON file, e.g:

json "segmentation_properties": { "model": "cyto2", "model_dimensions": "2D", "custom_weights": "custom_weights_file", "channel_map": { "red": "Cellbound1", "green": "Cellbound3", "blue": "DAPI" } },

Report options

You can also set extra options for naming channels and filtering by volume and transcript thresholds when generating reports. See the VPT documentation for more details.

For example:

yaml red_stain_name: "Cellbound1" green_stain_name: "Cellbound2" blue_stain_name: "DAPI" transcript_count_threshold: 100 volume_filter_threshold: 200 z_index: 2

Report-only mode

If you would like to only generate a QC report, and you already have your metadata, cellbygene and boundary files, you can specify those files in parameters in your params file:

yaml report_only: true metadata: "/path/to/entity_metadata.csv" entity_by_gene: "/path/to/entity_by_gene.csv" boundaries: "/path/to/segmentation.parquet"

bash nextflow run WEHI-SODA-Hub/spatialvpt \ -profile <docker/singularity/.../institute> \ -params-file params.yml \ --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.

Credits

WEHI-SODA-Hub/spatialvpt was originally written by Marek Cmero.

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

• Raymond Yip
• Pradeep Rajasekhar (@pr4deepr)
• All members of the WEHI SODA Hub

Contributions and Support

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

Citations

If you use WEHI-SODA-Hub/spatialvpt for your analysis, please cite it using the following doi: 10.5281/zenodo.16973286

This pipeline uses test MERSCOPE data from nf-core/test-datasets.

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

This pipeline uses code and infrastructure developed and maintained by the nf-core community, reused here under the MIT license.

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.