omics.co.in logo omics.co.in

Chapter 3: The Space Ranger Pipeline: Probe Sets, Reference Genomes & Alignment

1 min read • Verified October 2026 • Peer-Reviewed Learning Resource
Tested Stacks: GATK 4.6.1 Samtools 1.21 Nextflow 24.10 Seurat v5.1 Python 3.12
Prerequisites: Basic Linux CLI & Sequencing Formats
Day 2 • Space Ranger Pipeline Track 21 • 10 Modular Chapters Visium HD • Seurat v5 • Space Ranger

Chapter 3: The Space Ranger Pipeline: Probe Sets, Reference Genomes & Alignment

The 10x Genomics spaceranger count workflow: input FASTQs, reference transcriptome generation, whole-transcriptome probe sets, CytAssist fiducial registration, slide coordinates, and execution optimization.

⏱️ Estimated Time: 55 min 💻 Environment: R 4.4+ • Seurat v5 • Space Ranger 3.0+ 📁 Dataset: 10x Genomics Visium HD Colorectal Cancer (FFPE)

Key Learning Deliverables & Competencies

  • Understand the whole-transcriptome probe hybridization chemistry utilized in Visium HD FFPE assays.
  • Configure the 10x Genomics Space Ranger command-line environment and pipeline prerequisites.
  • Execute spaceranger count with appropriate slide serial numbers, capture areas, and CytAssist image inputs.
  • Optimize compute parameters: multi-threading, memory allocation, and SLURM workload manager integration.

1. Probe Ligation Chemistry (RHS Probe Sets)

Visium HD on FFPE human specimens relies on a whole-transcriptome probe set (Human RHS v2/v3). Rather than attempting reverse transcription across heavily crosslinked and degraded RNA fragments, paired DNA probes hybridize to targeted 50-nucleotide mRNA sequences. When both half-probes (Left and Right) hybridize contiguously, DNA ligase joins them into a full-length amplifiable probe containing the gene ID sequence.

2. Space Ranger Pipeline Execution Command

Below is the production-grade bash invocation script for executing spaceranger count on a high-performance compute cluster (HPC):

#!/usr/bin/env bash
#SBATCH --job-name=spaceranger_visium_hd
#SBATCH --nodes=1
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=32
#SBATCH --mem=128G
#SBATCH --time=12:00:00
#SBATCH --output=spaceranger_%j.log

set -euo pipefail

# Define Software and Reference Paths
SPACERANGER_BIN="/opt/spaceranger-3.1.0/spaceranger"
TRANSCRIPTOME_REF="/ref/GRCh38-2024-A"
PROBE_SET="/ref/Visium_Human_Transcriptome_Probe_Set_v2.0_GRCh38-2024-A.csv"

# Sample Metadata and Imaging Coordinates
SAMPLE_ID="Visium_HD_Colorectal_Cancer_TME"
FASTQ_DIR="/data/fastqs/visium_hd_run1"
CYTASSIST_IMAGE="/data/images/CRC_Slide_V13B24-001_CytAssist.tif"
HISTOLOGY_IMAGE="/data/images/CRC_Slide_V13B24-001_HE_HighRes.tif"
SLIDE_ID="V13B24-001"
CAPTURE_AREA="A1"

echo "=== Starting Space Ranger Visium HD Pipeline: ${SAMPLE_ID} ==="

${SPACERANGER_BIN} count     --id="${SAMPLE_ID}"     --transcriptome="${TRANSCRIPTOME_REF}"     --probe-set="${PROBE_SET}"     --fastqs="${FASTQ_DIR}"     --sample="${SAMPLE_ID}"     --cytaimage="${CYTASSIST_IMAGE}"     --image="${HISTOLOGY_IMAGE}"     --slide="${SLIDE_ID}"     --area="${CAPTURE_AREA}"     --localcores=32     --localmem=120

echo "=== Pipeline Completed Successfully: Outputs saved to ${SAMPLE_ID}/outs/ ==="

3. Compute Architecture & Memory Considerations

Because Visium HD generates outputs across 2 µm, 8 µm, and 16 µm square bins simultaneously, the demultiplexing, alignment, and coordinate translation routines are computationally intensive. Allocate a minimum of 128 GB RAM and 24–32 CPU cores to prevent Out-Of-Memory (OOM) failures during the spatial coordinate binning stage.

⚠️ Common Pitfalls & Troubleshooting in Spatial Genomics

  • Out-Of-Memory (OOM) Crashes on 2 µm/8 µm Grids: Never run default FindVariableFeatures() or dense Euclidean distance matrices across raw unsketched 2 µm arrays. Always leverage Seurat v5's SketchData() with on-disk BPCells streaming.
  • Tissue Detachment & Optical Misalignment: Inspect fiducial edge coordinates in Loupe Browser before downstream R processing. If tissue folds or lifts during CytAssist transfer, manually flag and filter affected spatial barcodes.
  • Over-Filtering Low-Cellularity Stromal Bins: Dense desmoplastic collagen or mucinous lakes naturally possess low transcript abundance. Setting an overly aggressive $nFeature$ threshold risks completely discarding critical acellular microenvironments.
⚠️

Common Pitfalls & Troubleshooting Checklist

  • Java Heap Exhaustion (GATK / Picard): If processes terminate with java.lang.OutOfMemoryError, set your environment variable explicitly: export _JAVA_OPTIONS="-Xmx16g -Djava.io.tmpdir=/tmp".
  • Index Timestamp Mismatch: If tools complain that a BAM index is missing or out of date, regenerate with samtools index -@ 4 sample.bam.
  • Conda Channel Conflicts: Avoid ABI incompatibilities between bioconda and conda-forge by setting strict priority: conda config --set channel_priority strict.
  • Chromosome Naming Contamination: Always verify whether reference FASTA headers use chr1 or 1; divergent naming causes silent alignment drops.
Was this guide helpful to your research?
Help us maintain 100% accurate, peer-reviewed bioinformatics standards.
📝 Propose Edit on GitHub ↗