omics.co.in logo omics.co.in

Chapter 4: Space Ranger Output Anatomy, Web Summary & Hands-On Loupe Browser

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 • Loupe Browser & QC Track 21 • 10 Modular Chapters Visium HD • Seurat v5 • Space Ranger

Chapter 4: Space Ranger Output Anatomy, Web Summary & Hands-On Loupe Browser

Deconstructing the Space Ranger directory: web_summary.html, cloupe files, filtered matrices, and spatial coordinate tables; hands-on Loupe Browser 8.0: fiducial alignment, H&E overlay, region selection, and custom binning.

⏱️ 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

  • Dissect the full directory anatomy of the Space Ranger outs/ folder.
  • Interpret key web summary diagnostic metrics: Sequencing Saturation, Fraction of Reads in Tissue, and Median Genes/UMIs per bin.
  • Perform interactive tissue inspection using 10x Genomics Loupe Browser 8.0.
  • Execute histology-guided ROI lasso selection, manual tissue annotation, and coordinate export for R integration.

1. Anatomy of the Space Ranger Output Directory

Upon pipeline completion, the outs/ directory contains hierarchical spatial and matrix files:

outs/
├── web_summary.html # Executive QA dashboard with interactive summary plots
├── cloupe.cloupe # Interactive container file for 10x Loupe Browser
├── binned_outputs/
│ ├── square_002um/
│ │ ├── filtered_feature_bc_matrix.h5 # Filtered matrix at 2 µm resolution
│ │ └── spatial/ # Parquet coordinate positions and scale factors
│ ├── square_008um/
│ │ ├── filtered_feature_bc_matrix.h5 # Cellular-scale matrix (recommended for general analysis)
│ │ └── spatial/
│ └── square_016um/
│ ├── filtered_feature_bc_matrix.h5 # Micro-neighborhood matrix (high sensitivity)
│ └── spatial/
└── spatial/
├── tissue_positions.parquet # Exact microscope pixel-to-bin coordinate lookup
└── scalefactors_json.json # Image scaling transformations (spot, fiducial, hires)

2. Interpreting the Web Summary QC Dashboard

Sequencing Saturation (≥ 60% – 80%)

Calculated as $1 - ( ext{Unique UMIs} / ext{Total Reads})$. Indicates whether additional sequencing sequencing depth would yield new unique transcripts. A saturation above 70% confirms near-complete capture of library diversity.

Fraction of Reads in Tissue (≥ 70%)

The percentage of valid reads falling on tissue-covered bins vs glass background. Values below 60% indicate optical fiducial misalignment, background probe leakage, or excessive tissue detachment during washing.

Median Genes / UMIs per Bin

At 8 µm resolution in FFPE clinical samples, expected median detected genes range between 300 and 1,200 genes/bin, and UMIs between 500 and 3,000 UMIs/bin depending on tissue cellularity and RNA degradation.

3. Hands-On Exploration with Loupe Browser 8.0

Loupe Browser provides pathologists and computational biologists with a zero-code interactive visual interface. In this session:

  1. Load the .cloupe file into Loupe Browser 8.0.
  2. Overlay the high-resolution H&E histology image and toggle the transparency slider to verify fiducial alignment.
  3. Use the Lasso Selection Tool to manually segment anatomical regions: Invasive Carcinoma, Necrotic Center, Stroma, and Tertiary Lymphoid Structures.
  4. Export the custom manual annotation assignments as a metadata_clusters.csv table for downstream R modeling.

⚠️ 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 ↗