Overview

OphiST is a Snakemake pipeline for the analysis of image-based spatial transcriptomics (iST) data in a segmentation-free manner.

The accurate assignment of transcripts to cells presents a major bottleneck in conventional analysis of iST data. Issues such as transcript bleed from adjacent cells, cells overlapping in the z-plane, and segmentation failures on irregularly-shaped cells can all lead to complications in downstream analyses. OphiST applies several tools from the Bioinformatics and Cellular Genomics Lab at SVI designed to operate directly on the raw, individual transcript data output by iST platforms, with no cell segmentation required. Namely, SpatialRNA applies graph neural network (GNN) to embed each individual transcript in a latent space reflecting its local molecular context, and DuetiST then derives both fine-grained molecular niches and broader spatial domains from the transcript-embedding data. These tools both operate downstream of sensible preprocessing steps such as demultiplexing, QC filtering (if possible), and tissue-detection. Further along the pipeline, basic downstream analyses such as domain-wise (and condition-wise, if contrasts are supplied) differential gene expression and gene-set enrichment analysis are performed. Everything is summarised in a self-contained HTML report output by the final step of the pipeline.

Documentation

See the following sub-pages for further details about the pipeline:

• Configuration explains every parameter in the config should you wish to tweak the defaults.
• Outputs details the outputs of the pipeline.
• Containers contains information about the Apptainer containers and Conda environments used for running the pipeline, including instructions on building them yourself.
• Command line describes the ophist command: run, init, examples and profile.

Installation

OphiST needs Python 3.11 or later. Install it with pip, including the SLURM plugin if you run on a SLURM cluster:

pip install "ophist[slurm]"

This installs the ophist command, the workflow and Snakemake. The latest development version installs straight from the repository: pip install "ophist[slurm] @ git+https://gitlab.svi.edu.au/biocellgen-public/ophist.git". On a cluster, install into an environment on a shared filesystem, because the compute nodes run the workflow's scripts from there.

To work on the workflow itself, clone the repository. An editable install then makes ophist run the clone:

git clone https://gitlab.svi.edu.au/biocellgen-public/ophist.git
pip install -e "./ophist[slurm]"

A clone also runs without pip, through Snakemake directly; see docs/cli.md.

Requirements

• Apptainer. Each step runs in a prebuilt image, pulled on first use. Conda works too; see docs/containers.md.
• An NVIDIA GPU for step 3 (spatialRNA training and embedding).
• To run on a SLURM cluster, the SLURM executor plugin, installed by the slurm extra above.

Quick start

1. Start a run directory from the example closest to your data (ophist examples lists them):

   ophist init my_run --example xenium_tma
   

2. List your samples in my_run/config/samples.tsv. Adjust my_run/config/config.yml as needed. A config only needs the settings it changes; see docs/config.md.

3. Once, write a Snakemake profile, and fill in your account, partition and the data paths to bind into the images:

   ophist profile slurm        # writes profiles/slurm/config.yaml
   

   On a single GPU machine, use ophist profile local instead, or no profile at all.

4. Run. Output goes to my_run/; add -n first for a dry run.

   ophist run my_run/config/config.yml --profile profiles/slurm
   

   A long run is best launched from a batch job of its own. That head job needs about 1 CPU and 8 GB.

Examples

examples/ holds configs for three data types:

Overview of the pipeline

Each rule file's scripts are in scripts/<rule file name>/. Helpers shared between steps are in scripts/utils/.

Credits

• Patrick Crock: Lead engineer of the pipeline.
• Anne Pan: Current maintainer of the spatialrna package. Designed rules 03 and 10.
• Ruqian Lyu: Original author of the spatialrna package.
• Smoothing and the Potts model both use duetist.

Citation

A manuscript is in preparation.

License

BSD 3-Clause; see LICENSE.