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:

• tiff_segmentation_vpt -- 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:

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:

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:

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

Singularity:

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:

custom_weights: "/path/to/custom_weights_file"

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

"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:

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, cell_by_gene and boundary files, you can specify those files in parameters in your params file:

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

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.