cellranger-fgcz

CellRanger FGCZ Skill

Overview

Process 10x Genomics single-cell sequencing data using CellRanger pipelines on FGCZ compute infrastructure. This skill provides:

• Multi config CSV guidance - The #1 source of CellRanger errors
• FGCZ-specific paths - Reference genomes, storage, modules
• Demultiplexing workflows - HTO and OCM configuration
• Feature reference creation - Antibody/HTO barcode files
• Validation tools - Check configs before running
• SBATCH templates - Job submission for SLURM cluster

When to Use

Use this skill for:

• Processing 10x single-cell data (GEX, ATAC, VDJ, multiome)
• Demultiplexing with HTO (hashtag antibodies) or OCM (on-chip multiplexing)
• Complex workflows: HTO+BCR without GEX, CITE-seq, multi-modal experiments
• Creating CellRanger multi config CSV files
• Validating configs and feature references
• Workflows NOT supported by SUSHI requiring manual execution

Quick Decision Tree

What do you need to process?

├─ Single GEX library, no multiplexing
│  └─ Use: cellranger count (simple workflow)
│
├─ GEX + HTO demultiplexing
│  └─ Use: cellranger multi with [feature] and [samples] sections
│
├─ GEX + HTO + VDJ (TCR/BCR)
│  └─ Use: cellranger multi with [gene-expression], [feature], [vdj], [samples]
│
├─ HTO + VDJ without GEX (special case)
│  └─ Use: cellranger multi with [feature], [vdj], [samples] only
│  └─ Note: Not supported by SUSHI - run manually
│
├─ On-chip multiplexing (GEM-X 4-plex)
│  └─ Use: cellranger multi with ocm_barcode_ids (no feature reference needed)
│
├─ GEX + ATAC (multiome)
│  └─ Use: cellranger-arc count
│
└─ Pure ATAC-seq
   └─ Use: cellranger-atac count

Core Workflows

1. Simple GEX (cellranger count)

For single libraries without multiplexing:

/usr/local/ngseq/bin/cellranger count \
    --id=sample1 \
    --transcriptome=/srv/GT/reference/Homo_sapiens/GENCODE/GRCh38.p13/Annotation/Release_42-2023-01-30/Genes/genes_10XGEX_SC_Mt_rRNA-Mt_tRNA-protein_coding-rRNA-tRNA_Index/ \
    --fastqs=/srv/GT/analysis/p12345/fastqs/ \
    --sample=sample1 \
    --localcores=16 \
    --localmem=128

2. Multi Config Workflows (cellranger multi)

For multiplexing, VDJ, or feature barcoding, use cellranger multi:

Step 1: Create multi config CSV

• See assets/example_configs/ for working examples
• Refer to references/multi_config_reference.md for complete format specs

Step 2: Validate config

python scripts/validate_config.py config.csv

Step 3: Run CellRanger

/usr/local/ngseq/bin/cellranger multi --id=sample1 --csv=config.csv

Common multi workflows:

• GEX + HTO: See assets/example_configs/gex_hto_human.csv
• GEX + HTO + VDJ: See assets/example_configs/gex_hto_vdj_mouse.csv
• HTO + BCR only: See assets/example_configs/hto_bcr_only_mouse.csv
• OCM demux: See assets/example_configs/gex_ocm_human.csv
• CITE-seq: See assets/example_configs/gex_cite_hto_human.csv

3. Feature Reference Creation

For HTO or antibody capture experiments, create a feature reference CSV:

Option A: Use existing template

cp assets/feature_references/totalseq_c_hto_4plex.csv /srv/GT/analysis/p12345/references/feature_reference.csv

Option B: Create custom reference See references/feature_reference_guide.md for complete instructions.

Critical: Always verify barcode sequences match your actual reagents!

Validate:

python scripts/validate_config.py --feature-ref feature_reference.csv

4. SBATCH Job Submission

For long-running jobs, submit to SLURM cluster:

Step 1: Copy and modify template

cp scripts/sbatch_cellranger.sh /srv/GT/analysis/p12345/
nano /srv/GT/analysis/p12345/sbatch_cellranger.sh
# Update: PROJECT_ID, SAMPLE_ID, CONFIG_FILE paths

Step 2: Create log directory

mkdir -p /srv/GT/analysis/p12345/logs

Step 3: Submit job

sbatch /srv/GT/analysis/p12345/sbatch_cellranger.sh

Step 4: Monitor

squeue -u $USER
# Check logs: tail -f /srv/GT/analysis/p12345/logs/cellranger_JOBID.out

FGCZ Infrastructure

Module System

# Always load R module first
module load Dev/R/4.5.0

# CellRanger available without module
/usr/local/ngseq/bin/cellranger --version

Storage Paths

Path	Purpose	Access
/srv/GT/analysis/pXXXXX/	Working directory	Read/Write
/srv/gstore/projects/pXXXXX/	Long-term storage	Read-only (use g-req)
/srv/GT/reference/	Reference genomes	Read-only

Standard analysis layout:

/srv/GT/analysis/pXXXXX/
├── fastqs/                 # Input FASTQs
├── references/             # Feature references
├── configs/                # Multi config CSVs
├── cellranger_outputs/     # Results
└── logs/                   # SBATCH logs

Reference Genomes

Human (GRCh38.p13):

• GEX: /srv/GT/reference/Homo_sapiens/GENCODE/GRCh38.p13/Annotation/Release_42-2023-01-30/Genes/genes_10XGEX_SC_Mt_rRNA-Mt_tRNA-protein_coding-rRNA-tRNA_Index/
• VDJ: /srv/GT/reference/Homo_sapiens/GENCODE/GRCh38.p13/Annotation/Release_42-2023-01-30/Genes/genes_10XVDJ_Index

Mouse (GRCm39):

• GEX: /srv/GT/reference/Mus_musculus/GENCODE/GRCm39/Annotation/Release_M37-2025-07-03/Genes/genes_10XGEX_SC_Mt_rRNA-Mt_tRNA-protein_coding-rRNA-tRNA_Index
• VDJ: /srv/GT/reference/Mus_musculus/GENCODE/GRCm39/Annotation/Release_M37-2025-07-03/Genes/genes_10XVDJ_Index

Complete list: See references/fgcz_references.md

Data Management (g-req)

Copy results to gstore:

# After CellRanger completes
g-req -w copy /srv/GT/analysis/p12345/cellranger_outputs/sample1/outs/ /srv/gstore/projects/p12345/CellRanger_Results/

# Check status
gstore-list

Critical: Multi Config Format

The multi config CSV is the #1 source of errors. Common mistakes:

Most Common Errors

1. Wrong feature type for HTO

   • ❌ Antibody Capture (old)
   • ✅ Multiplexing Capture (Cell Ranger ≥ 6.0)

2. FASTQ path doesn't exist

   • Cannot access /srv/gstore/ directly
   • Copy to /srv/GT/analysis/ first

3. fastq_id doesn't match FASTQ filenames

   • If files: GEX_sample1_S1_L001_R1_001.fastq.gz
   • Then fastq_id must be: GEX_sample1

4. Wrong demux column name

   • HTO: use hashtag_ids
   • OCM: use ocm_barcode_ids

5. Missing [samples] section

   • Required for all demultiplexing workflows

Complete format reference: references/multi_config_reference.md

Example Workflows

Example 1: GEX + HTO (4 samples)

1. Create feature reference:

# feature_reference.csv
id,name,read,pattern,sequence,feature_type
HTO1,Sample1,R2,5PNNNNNNNNNN(BC),GCACCTCATTCCTAC,Multiplexing Capture
HTO2,Sample2,R2,5PNNNNNNNNNN(BC),TCAGTATTCTGGGAC,Multiplexing Capture
HTO3,Sample3,R2,5PNNNNNNNNNN(BC),GGTTGTCATAAGAAC,Multiplexing Capture
HTO4,Sample4,R2,5PNNNNNNNNNN(BC),ACTCTCACCCATTCC,Multiplexing Capture

2. Create multi config:

[gene-expression]
reference,/srv/GT/reference/Homo_sapiens/GENCODE/GRCh38.p13/Annotation/Release_42-2023-01-30/Genes/genes_10XGEX_SC_Mt_rRNA-Mt_tRNA-protein_coding-rRNA-tRNA_Index/
create-bam,true

[feature]
reference,/srv/GT/analysis/p12345/references/feature_reference.csv

[libraries]
fastq_id,fastqs,feature_types
Pool1_GEX,/srv/GT/analysis/p12345/fastqs/GEX,Gene Expression
Pool1_HTO,/srv/GT/analysis/p12345/fastqs/HTO,Multiplexing Capture

[samples]
sample_id,hashtag_ids
Sample1,HTO1
Sample2,HTO2
Sample3,HTO3
Sample4,HTO4

3. Validate and run:

python scripts/validate_config.py config.csv --feature-ref feature_reference.csv
cellranger multi --id=pool1 --csv=config.csv

Example 2: OCM Demultiplexing (GEM-X 4-plex)

Multi config:

[gene-expression]
reference,/srv/GT/reference/Homo_sapiens/GENCODE/GRCh38.p13/Annotation/Release_42-2023-01-30/Genes/genes_10XGEX_SC_Mt_rRNA-Mt_tRNA-protein_coding-rRNA-tRNA_Index/
create-bam,false

[libraries]
fastq_id,fastqs,feature_types
pool1_GEX,/srv/GT/analysis/p12345/fastqs/pool1,Gene Expression

[samples]
sample_id,ocm_barcode_ids
Control,OB1
Treatment_1,OB2
Treatment_2,OB3
Treatment_3,OB4

Note: No feature reference needed for OCM!

Validation Tools

Validate Multi Config

python scripts/validate_config.py config.csv

Checks:

• File format and sections
• Reference paths exist
• FASTQ paths exist
• Valid feature types
• Correct demux column names

Validate Feature Reference

python scripts/validate_config.py --feature-ref feature_reference.csv

Checks:

• Header format
• Unique IDs and sequences
• Valid patterns and feature types
• Sequence format (ACGT only)
• Duplicate detection

Validate Both

python scripts/validate_config.py config.csv --feature-ref feature_reference.csv

Resources

Bundled Files

Directory	Contents	Purpose
references/	Multi config reference, FGCZ paths, feature reference guide	Detailed documentation - load when creating configs
assets/example_configs/	Working config examples for common workflows	Copy and modify for your project
assets/feature_references/	Feature reference templates (HTO, CITE-seq)	Ready-to-use barcode files
scripts/	validate_config.py, sbatch_cellranger.sh	Validation and job submission tools

Using Resources

Load detailed documentation:

• Creating multi config? → Load references/multi_config_reference.md
• Need FGCZ paths? → Load references/fgcz_references.md
• Creating feature reference? → Load references/feature_reference_guide.md

Copy working examples:

# Copy config template
cp assets/example_configs/gex_hto_human.csv /srv/GT/analysis/p12345/config.csv

# Copy feature reference
cp assets/feature_references/totalseq_c_hto_4plex.csv /srv/GT/analysis/p12345/feature_reference.csv

Troubleshooting

Config Validation Failures

Error: "Invalid header"

• Ensure CSV header exactly matches required format
• No spaces, correct column names

Error: "Reference not found"

• Check path exists: ls /srv/GT/reference/...
• Verify species (human vs mouse)
• See references/fgcz_references.md for correct paths

Error: "FASTQ path not found"

• Verify path: ls /srv/GT/analysis/p12345/fastqs/
• Cannot access gstore directly - copy FASTQs to /srv/GT/analysis/ first

CellRanger Failures

Error: "Feature barcode not found"

• Check feature reference barcode sequences
• Verify sequences match actual antibodies used

Error: "No cells detected"

• Check FASTQ quality and depth
• Verify chemistry detection
• Try --expect-cells parameter

Job killed / out of memory

• Increase --mem-per-cpu in SBATCH script
• Typical: 16-32G per CPU for multi

Getting Help

• Multi config format: Load references/multi_config_reference.md
• FGCZ paths: Load references/fgcz_references.md
• Feature references: Load references/feature_reference_guide.md
• 10x Documentation: https://www.10xgenomics.com/support/software/cell-ranger
• FGCZ SUSHI: https://fgcz-sushi.uzh.ch

Quick Reference

Essential Commands

# Load modules
module load Dev/R/4.5.0

# CellRanger count (simple)
/usr/local/ngseq/bin/cellranger count --id=sample1 --transcriptome=REF --fastqs=FASTQS

# CellRanger multi (demux, VDJ, etc.)
/usr/local/ngseq/bin/cellranger multi --id=sample1 --csv=config.csv

# Validate
python scripts/validate_config.py config.csv --feature-ref feature_reference.csv

# Submit job
sbatch scripts/sbatch_cellranger.sh

# Monitor
squeue -u $USER

# Copy to gstore
g-req -w copy /srv/GT/analysis/p12345/outputs/ /srv/gstore/projects/p12345/

Essential Paths (Quick Copy)

# Human GEX
/srv/GT/reference/Homo_sapiens/GENCODE/GRCh38.p13/Annotation/Release_42-2023-01-30/Genes/genes_10XGEX_SC_Mt_rRNA-Mt_tRNA-protein_coding-rRNA-tRNA_Index/

# Human VDJ
/srv/GT/reference/Homo_sapiens/GENCODE/GRCh38.p13/Annotation/Release_42-2023-01-30/Genes/genes_10XVDJ_Index

# Mouse GEX
/srv/GT/reference/Mus_musculus/GENCODE/GRCm39/Annotation/Release_M37-2025-07-03/Genes/genes_10XGEX_SC_Mt_rRNA-Mt_tRNA-protein_coding-rRNA-tRNA_Index

# Mouse VDJ
/srv/GT/reference/Mus_musculus/GENCODE/GRCm39/Annotation/Release_M37-2025-07-03/Genes/genes_10XVDJ_Index