Space Ranger¶

Space Ranger is a set of analysis pipelines that process Visium spatial RNA-seq output as well as brightfield and fluorescence microscope images in order to detect tissue, align reads, generate feature-spot matrices, perform clustering and gene expression analysis, and place spots in spatial context on the slide image.

Space Ranger is available as a module on Apocrita.

Usage¶

To run the default installed version of Space Ranger, simply load the spaceranger module:

$ module load spaceranger
$ spaceranger

Process 10x Genomics Spatial Gene Expression data

USAGE:
    spaceranger <SUBCOMMAND>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information
...

For more information regarding each analysis pipeline, pass the --help key after the pipeline sub-command (i.e. spaceranger count --help).

Operating modes¶

Space Ranger can be run in different modes; The most relevant two for us are:

local (default)
sge

Local operating mode¶

The local mode will execute the pipeline on a single machine, usually within a cluster job. To run all executions inside a single job, this is the desired mode.

Cores and Memory Requests

To avoid overloading a node, set the --localcores ${NSLOTS} option to restrict Space Ranger to use the specified number of cores to execute pipeline rather than all cores available.

To prevent your job from being killed by the scheduler for using more memory than requested, set the --localmem option to restrict Space Ranger to use specified amount of memory (in GB) to execute pipeline stages rather than to use 90% of total memory available.

Cluster operating mode (sge)¶

The sge mode will launch each stage of the underlying pipeline framework as a different Apocrita job using the qsub command. As jobs from each stage are queued, launched, and completed, the pipeline framework will track their states using the metadata files that each stage maintains in the pipeline output directory.

Core Requests and Consumption

The number of cores required is determined by the pipeline framework stage.

Memory Requests and Consumption

To specify the memory-per-core resource (h_vmem), pass the --mempercore switch. This value will be used in all pipeline framework stages.

Example jobs¶

Serial job (local)¶

Here is an example job running on 4 cores and 16GB of memory to generate spatial feature counts for a single library using automatic fiducial alignment and tissue detection, in local mode:

#!/bin/bash
#$ -cwd
#$ -j y
#$ -pe smp 4
#$ -l h_rt=1:0:0
#$ -l h_vmem=4G

module load spaceranger

$ spaceranger count --id=1234 \
                    --transcriptome=example_transcriptome \
                    --fastqs=raw_data.fastq \
                    --sample=1234 \
                    --image=sample_1234.tif \
                    --slide=V19J01-123 \
                    --area=A1 \
                    --localcores ${NSLOTS} \
                    --localmem 4

Serial job (multi-job)¶

Here is an example job running on 4 cores and 16GB of memory to generate spatial feature counts for a single library using automatic fiducial alignment and tissue detection. Each stage will be submitted as a different job with the same resources.

#!/bin/bash
#$ -cwd
#$ -j y
#$ -pe smp 1
#$ -l h_rt=1:0:0
#$ -l h_vmem=1G

module load spaceranger

spaceranger count --id 1234 \
                  --transcriptome example_transcriptome \
                  --fastqs raw_data.fastq \
                  --sample 1234 \
                  --disable-ui \
                  --jobmode sge \
                  --mempercore 4

Reference¶

Space Ranger documentation