Space Ranger 4.0.1 User Guide

Overview

Space Ranger is a set of analysis pipelines from 10x Genomics that processes spatially resolved gene expression data from the Visium platform. It performs image processing, tissue detection, fiducial alignment, spatial barcode assignment, gene counting, and integration of spatial and expression data.

Version: 4.0.1 Category: Bioinformatics / Spatial Transcriptomics Official Documentation: https://www.10xgenomics.com/support/software/space-ranger

Loading the Module

module load spaceranger/4.0.1

Check loaded environment:

module list
which spaceranger
spaceranger --version

Main Commands

spaceranger count

Process Visium spatial gene expression data.

Basic usage:

spaceranger count --id=sample_id \
                  --transcriptome=/path/to/refdata \
                  --fastqs=/path/to/fastqs \
                  --sample=sample_name \
                  --image=/path/to/image.tif \
                  --slide=slide_serial \
                  --area=capture_area

Required arguments: - --id: Unique run ID (output directory name) - --transcriptome: Path to Space Ranger reference transcriptome - --fastqs: Path to directory containing FASTQ files - --sample: Sample name(s) from FASTQ filenames - --image: Path to brightfield tissue image (TIFF or JPEG) - --slide: Visium slide serial number (e.g., V10A01-123) - --area: Capture area identifier (A1, B1, C1, D1)

Optional arguments: - --loupe-alignment: Loupe alignment file (JSON) from manual fiducial alignment - --reorient-images: Automatically reorient images (true/false) - --darkimage: Dark background image for fluorescence data - --colorizedimage: Colorized image for visualization - --cytaimage: H&E or IF image for Loupe Browser - --localcores: Number of cores to use - --localmem: GB of memory to use

spaceranger aggr

Aggregate data from multiple Space Ranger runs.

Usage:

spaceranger aggr --id=aggregated \
                 --csv=aggregation.csv

aggregation.csv format:

library_id,molecule_h5
sample1,/path/to/sample1/outs/molecule_info.h5
sample2,/path/to/sample2/outs/molecule_info.h5

Options: - --normalize: Normalization mode (mapped, none)

spaceranger reanalyze

Re-run secondary analysis with different parameters.

Usage:

spaceranger reanalyze --id=reanalysis \
                      --matrix=/path/to/filtered_feature_bc_matrix.h5 \
                      --params=params.csv

params.csv example:

num_principal_comps,50
max_clusters,10

spaceranger mkref

Build a Space Ranger-compatible reference from FASTA and GTF files.

Usage:

spaceranger mkref --genome=genome_name \
                  --fasta=/path/to/genome.fa \
                  --genes=/path/to/genes.gtf

spaceranger mkgtf

Filter a GTF file for Space Ranger compatibility.

Usage:

spaceranger mkgtf input.gtf output.gtf \
                  --attribute=gene_biotype:protein_coding

spaceranger testrun

Test Space Ranger installation with small dataset.

Usage:

spaceranger testrun --id=test_run

spaceranger mat2csv

Convert Space Ranger matrix to CSV format.

Usage:

spaceranger mat2csv /path/to/filtered_feature_bc_matrix \
                    output_folder

Running on the Cluster

Interactive Job (Testing/Small Datasets)

srun --nodes=1 --cpus-per-task=16 --mem=64G --time=4:00:00 --pty bash

module load spaceranger/4.0.1

spaceranger count --id=test_spatial \
                  --transcriptome=/sw/spaceranger/refdata-gex-GRCh38-2024-A \
                  --fastqs=/path/to/fastqs \
                  --sample=test_sample \
                  --image=/path/to/tissue_image.tif \
                  --slide=V10A01-123 \
                  --area=A1 \
                  --localcores=16 \
                  --localmem=60

Batch Job (Production Runs)

Create a Slurm submission script spaceranger_count.sh:

#!/bin/bash
#SBATCH --job-name=spaceranger
#SBATCH --output=spaceranger_%j.out
#SBATCH --error=spaceranger_%j.err
#SBATCH --nodes=1
#SBATCH --cpus-per-task=32
#SBATCH --mem=128G
#SBATCH --time=24:00:00

module purge
module load spaceranger/4.0.1

SAMPLE_ID="spatial_001"
TRANSCRIPTOME="/sw/spaceranger/refdata-gex-GRCh38-2024-A"
FASTQ_DIR="/path/to/fastqs"
IMAGE="/path/to/tissue_image.tif"
SLIDE="V10A01-123"
AREA="A1"

spaceranger count --id=${SAMPLE_ID} \
                  --transcriptome=${TRANSCRIPTOME} \
                  --fastqs=${FASTQ_DIR} \
                  --sample=${SAMPLE_ID} \
                  --image=${IMAGE} \
                  --slide=${SLIDE} \
                  --area=${AREA} \
                  --localcores=${SLURM_CPUS_PER_TASK} \
                  --localmem=120

echo "Space Ranger count completed for ${SAMPLE_ID}"

Submit the job:

sbatch spaceranger_count.sh

Processing with Manual Alignment

If automatic fiducial detection fails, use Loupe Browser for manual alignment:

1. Run Space Ranger once (it will fail at alignment)
2. Open web_summary.html and download alignment file
3. Load image in Loupe Browser and manually align fiducials
4. Export alignment JSON file
5. Re-run with --loupe-alignment flag:

spaceranger count --id=${SAMPLE_ID} \
                  --transcriptome=${TRANSCRIPTOME} \
                  --fastqs=${FASTQ_DIR} \
                  --sample=${SAMPLE_ID} \
                  --image=${IMAGE} \
                  --slide=${SLIDE} \
                  --area=${AREA} \
                  --loupe-alignment=manual_alignment.json \
                  --localcores=${SLURM_CPUS_PER_TASK} \
                  --localmem=120

Reference Genomes

Space Ranger requires pre-built reference transcriptomes. Common references should be stored in:

/sw/spaceranger/references/

Available References

Check with your system administrator for available references, or download from: https://www.10xgenomics.com/support/software/space-ranger/downloads

Common references: - refdata-gex-GRCh38-2024-A - Human (GRCh38/hg38) - refdata-gex-GRCm39-2024-A - Mouse (GRCm39/mm39)

Building Custom References

spaceranger mkref --genome=custom_genome \
                  --fasta=genome.fa \
                  --genes=genes.gtf \
                  --nthreads=16

Output Structure

After running spaceranger count, outputs are in the --id directory:

sample_id/
├── outs/
│   ├── web_summary.html                    # QC metrics and spatial visualization
│   ├── metrics_summary.csv                 # Key metrics in CSV
│   ├── spatial/
│   │   ├── tissue_positions.csv            # Barcode spatial coordinates
│   │   ├── tissue_lowres_image.png         # Low-res tissue image
│   │   ├── tissue_hires_image.png          # High-res tissue image
│   │   ├── detected_tissue_image.jpg       # Tissue detection visualization
│   │   ├── aligned_fiducials.jpg           # Fiducial alignment visualization
│   │   ├── scalefactors_json.json          # Image scale factors
│   │   └── tissue_positions_list.csv       # Deprecated format (for compatibility)
│   ├── filtered_feature_bc_matrix/         # Filtered count matrix (tissue spots)
│   │   ├── barcodes.tsv.gz
│   │   ├── features.tsv.gz
│   │   └── matrix.mtx.gz
│   ├── filtered_feature_bc_matrix.h5       # HDF5 format count matrix
│   ├── raw_feature_bc_matrix/              # Unfiltered matrix (all barcodes)
│   ├── analysis/                           # Secondary analysis results
│   │   ├── clustering/
│   │   ├── diffexp/
│   │   ├── pca/
│   │   ├── tsne/
│   │   └── umap/
│   ├── molecule_info.h5                    # Per-molecule information
│   ├── possorted_genome_bam.bam            # Aligned reads
│   ├── possorted_genome_bam.bam.bai
│   └── cloupe.cloupe                       # Loupe Browser file
└── SC_RNA_COUNTER_CS/                      # Pipeline internal files

Key QC Metrics

Important metrics to check in web_summary.html:

Sequencing Metrics

1. Number of Reads: Should be ~50,000-100,000 per spot
2. Valid Barcodes: Should be >75%
3. Q30 Bases in Barcode/UMI/Read: Should be >80%
4. Sequencing Saturation: >80% is good

Mapping Metrics

1. Reads Mapped to Genome: Should be >70%
2. Reads Mapped to Transcriptome: Should be >60%
3. Reads Mapped Confidently to Transcriptome: Should be >50%

Spatial Metrics

1. Spots Under Tissue: Number of barcodes assigned to tissue (typically 2,000-5,000 for Visium)
2. Median Genes per Spot: Higher is better (varies by tissue, typically 2,000-5,000)
3. Median UMI Counts per Spot: Typically 5,000-20,000

Image Alignment

1. Fiducial Detection: All fiducials should be detected (check alignment visualization)
2. Tissue Detection: Tissue boundary should be accurately identified

Visium Slide Information

Slide Format

• Slide dimensions: 4 capture areas per slide (A1, B1, C1, D1)
• Spots per area: ~5,000 spots (6.5mm x 6.5mm)
• Spot diameter: 55 µm
• Center-to-center distance: 100 µm
• Spatial resolution: 1-10 cells per spot

Slide Serial Number Format

• Format: V10X##-### (e.g., V10A01-123, V11D13-456)
• Found on slide packaging and slide itself

Downstream Analysis

Seurat (R) - Spatial Analysis

library(Seurat)

# Load data
data <- Load10X_Spatial(
  data.dir = "sample_id/outs",
  filename = "filtered_feature_bc_matrix.h5"
)

# Spatial visualization
SpatialFeaturePlot(data, features = "Nkx2-1")
SpatialDimPlot(data, label = TRUE, label.size = 3)

Scanpy (Python) - Spatial Analysis

import scanpy as sc
import squidpy as sq

# Load data
adata = sc.read_visium("sample_id/outs")

# Add spatial coordinates
adata.obsm["spatial"] = adata.obsm["spatial"] * adata.uns["spatial"]["scalefactors"]["tissue_hires_scalef"]

# Spatial plot
sq.pl.spatial_scatter(adata, color="cluster", size=1.5)

Loupe Browser

Open cloupe.cloupe file with 10x Genomics Loupe Browser for interactive spatial visualization.

Resource Requirements

Typical Requirements by Dataset Size

Sample Type	Spots	Reads	Cores	Memory	Time
Small (partial tissue)	1-2K	100M	8	32 GB	3-5h
Medium (half slide)	2-3K	200M	16	64 GB	5-8h
Large (full capture area)	4-5K	500M	32	128 GB	8-16h
Very Large (HD/11mm)	10K+	1B+	32+	256 GB	24h+

Note: Space Ranger is I/O intensive due to image processing. Fast storage is beneficial.

Troubleshooting

"No input FASTQs were found"

• Check FASTQ path is correct
• Ensure --sample matches FASTQ filenames exactly
• FASTQ files must follow Illumina naming: SampleName_S1_L001_R1_001.fastq.gz

Fiducial Alignment Failed

• Check image quality and focus
• Ensure correct slide serial number
• Try manual alignment in Loupe Browser
• Verify image orientation with --reorient-images

Low spots under tissue

• Check tissue detection visualization in web_summary.html
• Tissue may be damaged or poorly stained
• Image quality may be insufficient for detection

Image format errors

• Convert images to TIFF or JPEG format
• Ensure images are not corrupted
• Use uncompressed or LZW-compressed TIFF for best results
• Recommended: brightfield microscopy at 10x magnification

Out of memory errors

• Increase --localmem (must be less than physical RAM)
• Request more memory in Slurm script (#SBATCH --mem=)
• Reduce image resolution if extremely large

Pipeline failures

Check detailed logs:

cat sample_id/_log

Best Practices

1. Image Quality: Use high-quality brightfield images at 10x magnification
2. Image Format: TIFF format preferred, JPEG acceptable
3. Slide Information: Always verify slide serial number and capture area
4. Fiducial Alignment: Check alignment visualization before proceeding with analysis
5. Tissue Detection: Verify tissue boundaries in web_summary.html
6. Sequencing Depth: Aim for 50,000-100,000 reads per spot for optimal results
7. Save Alignment Files: Keep loupe-alignment JSON for reproducibility
8. Spatial Coordinates: Always preserve spatial/ directory for downstream analysis
9. Multiple Sections: Use spaceranger aggr for proper normalization across sections
10. Documentation: Record tissue orientation and anatomical landmarks

Visium Assay Types

Space Ranger supports multiple Visium assay types:

• Visium Gene Expression: Standard spatial transcriptomics
• Visium HD: Higher resolution (2 µm bins)
• Visium with Immunofluorescence: Combined IF and gene expression
• CytAssist: FFPE-enabled spatial analysis

Check documentation for assay-specific parameters.

Support and Documentation

• Official Documentation: https://www.10xgenomics.com/support/software/space-ranger
• Release Notes: https://www.10xgenomics.com/support/software/space-ranger/downloads
• Community Forum: https://www.10xgenomics.com/support/community
• Loupe Browser: https://www.10xgenomics.com/support/software/loupe-browser
• Local Support: Contact your cluster system administrators

Version History

• 4.0.1 (Current): Latest version with enhanced image processing and HD support
• 3.1.2 (Previous): Legacy version on old cluster
• See release notes for detailed changes: https://www.10xgenomics.com/support/software/space-ranger/latest/release-notes

Additional Resources

• Visium Spatial Gene Expression User Guide: https://www.10xgenomics.com/support/spatial-gene-expression
• Sample Datasets: https://www.10xgenomics.com/resources/datasets
• Video Tutorials: https://www.10xgenomics.com/support/spatial-gene-expression/documentation

---

Installation Location: /sw/spaceranger/spaceranger-4.0.1 Module File: /opt/modulefiles/spaceranger/4.0.1.lua Last Updated: 2025-10-12