SeuratPreparing Process Configuration

Purpose

Load, prepare, and apply quality control (QC) to single-cell RNA-seq data using Seurat. Performs data loading, QC filtering, normalization, and multi-sample integration. This is a core preprocessing process that prepares Seurat objects for downstream clustering and analysis.

When to Use

• Essential process for all RNA-based immunopipe analyses (TCR and non-TCR routes)
• Required unless loading from already-prepared Seurat objects (see LoadingRNAFromSeurat process)
• Multi-sample datasets requiring batch correction and integration
• Data requiring doublet detection and removal
• Raw scRNA-seq data needing QC, normalization, and integration

Data Requirements

• Input data paths specified in SampleInfo metafile (RNAData column)
• Supported formats: 10x Genomics output (matrix.mtx, barcodes.tsv, features.tsv), h5 files, loom files, or pre-loaded Seurat objects (RDS/qs2)
• Each sample loaded individually and merged into one Seurat object

Dependencies

• Upstream: SampleInfo (provides metadata) OR LoadingRNAFromSeurat (provides prepared Seurat object)
• Downstream: SeuratClustering, SeuratClusteringOfAllCells, TOrBCellSelection

Configuration Structure

Process Enablement

[SeuratPreparing]
cache = true  # Enable caching to speed up re-runs

Input Specification

[SeuratPreparing.in]
# metafile is required unless LoadingRNAFromSeurat is used
metafile = ["path/to/sample_info.txt"]

metafile format (tab-delimited):

• Sample: Unique sample identifier (required)
• RNAData: Path to scRNA-seq data (required)
  • Directory containing matrix.mtx, barcodes.tsv, features.tsv (10x format)
  • Path to h5 file readable by Seurat::Read10X_h5()
  • Path to loom file readable by SeuratDisk::LoadLoom()
  • Path to RDS/qs2 file containing Seurat object
• Additional columns: Treated as sample metadata (optional)

Environment Variables

[SeuratPreparing.envs]
# Core processing parameters
ncores = 1                           # Parallelization cores
mutaters = {}                          # Add custom metadata columns
min_cells = 0                           # Minimum cells per gene (CreateSeuratObject)
min_features = 0                         # Minimum features per cell (CreateSeuratObject)

# Quality control
cell_qc = ""                           # Cell filtering expression (R syntax)
gene_qc = { min_cells = 0 }            # Gene filtering options

# QC plots generation
qc_plots = {}                           # Visualization configuration

# Normalization method selection
use_sct = false                         # Use SCTransform instead of NormalizeData pipeline
no_integration = false                    # Skip sample integration

# Doublet detection
doublet_detector = "none"                # Options: none, DoubletFinder, scDblFinder

# Caching
cache = "/tmp"                          # Cache intermediate results

External References

Seurat Normalization Functions

Standard Workflow (use_sct = false):

1. NormalizeData - Log-normalization of UMI counts

   [SeuratPreparing.envs.NormalizeData]
   normalization-method = "LogNormalize"  # Options: LogNormalize, CLR, RC
   scale-factor = 10000                   # Normalization scaling factor
   margin = 1                             # Normalize across features (1) or cells (2)
   verbose = true
   

   • Reference: https://satijalab.org/seurat/reference/normalizedata
   • LogNormalize: Count / scale_factor * 10,000 (default)
   • CLR: Centered log-ratio transformation
   • RC: Relative count normalization

2. FindVariableFeatures - Identify highly variable genes

   [SeuratPreparing.envs.FindVariableFeatures]
   selection-method = "vst"             # Options: vst, mean.var.plot, disp
   nfeatures = 2000                      # Number of variable features to select
   verbose = true
   

   • Reference: https://satijalab.org/seurat/reference/findvariablefeatures
   • vst: Variance-stabilizing transformation (recommended)
   • mean.var.plot: Mean-variance relationship
   • disp: Dispersion-based selection

3. ScaleData - Center and scale gene expression

   [SeuratPreparing.envs.ScaleData]
   vars.to.regress = []                   # Variables to regress out (e.g., ["percent.mt"])
   model.use = "linear"                    # Regression model
   verbose = true
   

   • Reference: https://satijalab.org/seurat/reference/scaledata
   • Regresses unwanted variation (mitochondrial, ribosomal, cell cycle)
   • Centers data at mean = 0, SD = 1

4. RunPCA - Principal component analysis

   [SeuratPreparing.envs.RunPCA]
   npcs = 50                             # Number of principal components
   verbose = true
   rev.pca = false                        # Reverse PCA direction
   weight.by.var = true                     # Weight by variance
   

   • Reference: https://satijalab.org/seurat/reference/runpca
   • npcs limited by: number of columns - 1 per sample

SCTransform Workflow (use_sct = true): 5. SCTransform - Variance-stabilizing transformation (replaces standard pipeline)

[SeuratPreparing.envs.SCTransform]
assay = "RNA"                         # Input assay
new.assay.name = "SCT"                # Output assay name
return-only-var-genes = true            # Keep only variable genes
min_cells = 3                           # Minimum cells per gene (hidden param)
variable.features.n = 3000               # Number of variable features
variable.features.rv.th = 1.3            # Residual variance threshold
vars.to.regress = []                   # Variables to regress out
do.correct.umi = true                   # Correct for UMI counts
ncells = 5000                         # Subsample for model fitting
do.scale = false                        # Scale after transformation
do.center = true                         # Center after transformation
clip.range = [-10, 10]                  # Clip residual values
vst.flavor = "v2"                     # VST algorithm version
conserve.memory = false                  # Memory-efficient mode
seed.use = 1448145                     # Random seed
verbose = true

• Reference: https://satijalab.org/seurat/reference/sctransform
• Advantages: Better normalization, handles technical noise, integrates well with Seurat v5
• Output: New assay named "SCT" with corrected counts, log1p data, Pearson residuals
• To keep all genes: Set min_cells = 0 and return-only-var-genes = false
• See: https://github.com/satijalab/seurat/issues/3598#issuecomment-715505537

Integration Methods

IntegrateLayers - Multi-sample batch correction

[SeuratPreparing.envs.IntegrateLayers]
method = "harmony"                      # Integration method
orig.reduction = "pca"                  # Base reduction for correction
assay = null                             # Assay to integrate (auto-detected)
features = null                           # Features for integration
layers = null                             # Layers to integrate
scale.layer = "scale.data"                 # Scaled layer name

• Reference: https://satijalab.org/seurat/reference/integratelayers
• Method options:
  • CCAIntegration / CCA / cca: Canonical correlation analysis
    • Best for: Strong expression differences across conditions/species
    • Can overcorrect with non-overlapping cell types
    • Slower than RPCA
  • RPCAIntegration / RPCA / rpca: Reciprocal PCA
    • Best for: Same platform, large datasets, non-overlapping cells
    • Faster, more conservative
    • Recommended for multi-batch 10x data
    • Reference: https://satijalab.org/seurat/articles/integration_rpca
  • HarmonyIntegration / Harmony / harmony: Harmony algorithm
    • Fast, iterative integration
    • Good for complex batch structures
    • Default method in immunopipe
  • FastMNNIntegration / FastMNN / fastmnn: Fast mutual nearest neighbors
    • Good for large datasets
    • From batchelor package
  • scVIIntegration / scVI / scvi: Variational inference
    • Deep learning-based
    • Requires scVI package

Doublet Detection

DoubletFinder - Simulation-based doublet detection

[SeuratPreparing.envs.DoubletFinder]
PCs = 10                                 # Number of PCs to use
doublets = 0.075                          # Expected doublet rate (7.5%)
pN = 0.25                                  # Doublet simulation proportion (25%)
ncores = 1                                  # Cores for paramSweep (null = use envs.ncores)
pK = 0.005                                 # Expected doublet rate parameter
reduction = "pca"                           # Reduction to use

• Reference: https://github.com/chris-mcginnis-ucsf/DoubletFinder
• Documentation: https://demultiplexing-doublet-detecting-docs.readthedocs.io
• Workflow: pK sweep → classify doublets → filter
• Tip: Set ncores smaller than envs.ncores if memory issues occur

scDblFinder - Machine learning-based doublet detection

[SeuratPreparing.envs.scDblFinder]
dbr = 0.075                               # Expected doublet rate (7.5%)
ncores = 1                                  # Cores for scDblFinder (null = use envs.ncores)
dbr.per1k = 0.8                            # Doublets per 1000 cells
verbose = true

• Reference: https://rdrr.io/bioc/scDblFinder/man/scDblFinder.html
• Documentation: https://www.bioconductor.org/packages/release/bioc/vignettes/scDblFinder/inst/doc/scDblFinder.html
• Advantages: Faster, more accurate, includes doublet origin predictions
• Modes: Cluster-based (clear structure) or random (complex datasets)
• Default dbr: Updated to 0.8% per 1000 cells in recent versions

Configuration Examples

Minimal Configuration (Single Sample, No Integration)

[SeuratPreparing]
[SeuratPreparing.in]
metafile = ["sample_info.txt"]

[SeuratPreparing.envs]
cell_qc = "nFeature_RNA > 200 & percent.mt < 5"
gene_qc = { min_cells = 3 }

Standard SCTransform with Harmony Integration

[SeuratPreparing]
[SeuratPreparing.in]
metafile = ["sample_info.txt"]

[SeuratPreparing.envs]
ncores = 4
use_sct = true

# QC filtering
cell_qc = "nFeature_RNA > 200 & percent.mt < 5"
gene_qc = { min_cells = 3 }

# SCTransform parameters
[SeuratPreparing.envs.SCTransform]
vars.to.regress = ["percent.mt", "percent.ribo"]
variable.features.n = 3000

# Harmony integration
[SeuratPreparing.envs.IntegrateLayers]
method = "harmony"

Multi-sample RPCA Integration

[SeuratPreparing]
[SeuratPreparing.in]
metafile = ["sample_info.txt"]

[SeuratPreparing.envs]
use_sct = false
ncores = 8

# Standard normalization workflow
[SeuratPreparing.envs.NormalizeData]
normalization-method = "LogNormalize"
scale-factor = 10000

[SeuratPreparing.envs.FindVariableFeatures]
selection-method = "vst"
nfeatures = 3000

[SeuratPreparing.envs.ScaleData]
vars.to.regress = ["percent.mt", "S.Score", "G2M.Score"]

# RPCA integration (faster, conservative)
[SeuratPreparing.envs.IntegrateLayers]
method = "rpca"
orig.reduction = "pca"

With DoubletFinder

[SeuratPreparing]
[SeuratPreparing.in]
metafile = ["sample_info.txt"]

[SeuratPreparing.envs]
use_sct = true
doublet_detector = "DoubletFinder"

[SeuratPreparing.envs.DoubletFinder]
PCs = 30
doublets = 0.05
pN = 0.25
ncores = 4

With scDblFinder

[SeuratPreparing]
[SeuratPreparing.in]
metafile = ["sample_info.txt"]

[SeuratPreparing.envs]
use_sct = true
doublet_detector = "scDblFinder"

[SeuratPreparing.envs.scDblFinder]
dbr = 0.05
ncores = 4

Per-Sample Cell QC

[SeuratPreparing.envs]
cell_qc = { DEFAULT = "nFeature_RNA > 200 & percent.mt < 5",
              Sample1 = "nFeature_RNA > 300 & percent.mt < 10",
              Sample2 = "nFeature_RNA > 150 & percent.mt < 5" }

Custom QC Plots

[SeuratPreparing.envs.qc_plots]
# Violin plots for QC metrics
[SeuratPreparing.envs.qc_plots."QC Violin Plots"]
kind = "cell"
plot_type = "violin"
devpars = { res = 100, height = 600, width = 1200 }

# Scatter plots
[SeuratPreparing.envs.qc_plots."QC Scatter Plots"]
kind = "cell"
plot_type = "scatter"
devpars = { res = 100, height = 800, width = 1200 }

# Gene expression distribution
[SeuratPreparing.envs.qc_plots."Gene Expression Distribution"]
kind = "gene"
plot_type = "histogram"
devpars = { res = 100, height = 1200, width = 1200 }

Common Patterns

Pattern 1: Single Sample (No Integration)

# Use when analyzing one sample or already batch-corrected data
[SeuratPreparing]
[SeuratPreparing.in]
metafile = ["single_sample_info.txt"]

[SeuratPreparing.envs]
no_integration = true  # Skip integration step
use_sct = true
cell_qc = "nFeature_RNA > 200 & percent.mt < 5"
gene_qc = { min_cells = 3 }

Pattern 2: Multiple Samples with Harmony Integration

# Use for multi-batch data with complex batch structures
[SeuratPreparing]
[SeuratPreparing.in]
metafile = ["multi_sample_info.txt"]

[SeuratPreparing.envs]
use_sct = true
ncores = 8

# Cell QC
cell_qc = "nFeature_RNA > 200 & nCount_RNA > 500 & percent.mt < 10"
gene_qc = { min_cells = 3, excludes = ["MALAT1", "MT-ND3"] }

# SCTransform with regression
[SeuratPreparing.envs.SCTransform]
vars.to.regress = ["percent.mt", "percent.ribo", "S.Score", "G2M.Score"]
variable.features.n = 3000

# Harmony integration
[SeuratPreparing.envs.IntegrateLayers]
method = "harmony"

Pattern 3: Batch Correction with RPCA (Large Datasets)

# Use for large datasets (>100k cells) or same-platform multi-batch
[SeuratPreparing]
[SeuratPreparing.in]
metafile = ["large_dataset_info.txt"]

[SeuratPreparing.envs]
use_sct = false  # RPCA works better with standard workflow
ncores = 16

# Standard workflow
[SeuratPreparing.envs.NormalizeData]
normalization-method = "LogNormalize"
scale-factor = 10000

[SeuratPreparing.envs.FindVariableFeatures]
selection-method = "vst"
nfeatures = 3000

[SeuratPreparing.envs.ScaleData]
vars.to.regress = ["percent.mt", "percent.ribo"]

[SeuratPreparing.envs.RunPCA]
npcs = 100

# RPCA integration (faster for large data)
[SeuratPreparing.envs.IntegrateLayers]
method = "rpca"
orig.reduction = "pca"

Pattern 4: Doublet Detection + Integration

# Use for datasets with high doublet rates (>5%)
[SeuratPreparing]
[SeuratPreparing.in]
metafile = ["high_doublet_info.txt"]

[SeuratPreparing.envs]
use_sct = true
doublet_detector = "scDblFinder"  # or "DoubletFinder"

[SeuratPreparing.envs.scDblFinder]
dbr = 0.08  # Higher expected doublet rate
ncores = 4

[SeuratPreparing.envs.SCTransform]
vars.to.regress = ["percent.mt", "percent.ribo"]

[SeuratPreparing.envs.IntegrateLayers]
method = "harmony"

Pattern 5: Keep All Genes (Not Just Variable Genes)

# Use when you need to analyze non-variable genes later
[SeuratPreparing]
[SeuratPreparing.in]
metafile = ["sample_info.txt"]

[SeuratPreparing.envs]
use_sct = true

[SeuratPreparing.envs.SCTransform]
min_cells = 0                    # Don't filter by expression
return-only-var-genes = false   # Keep all genes in RNA assay

Dependencies

Upstream Processes

• SampleInfo: Provides metadata and RNA data paths (required unless LoadingRNAFromSeurat used)
• LoadingRNAFromSeurat: Alternative input for pre-loaded Seurat objects

Downstream Processes

• SeuratClustering: Clustering on selected cells (T/B or all)
• SeuratClusteringOfAllCells: Clustering on all cells before T/B selection
• TOrBCellSelection: T cell or B cell subset selection
• SeuratClusterStats: Cluster statistics and visualizations

Assay Output

• SCT assay: Default assay when use_sct = true
• RNA assay: Default assay when use_sct = false
• integrated assay: Default assay when using CCA/RPCA integration

Validation Rules

Required Parameters

• [SeuratPreparing.in.metafile] is required unless LoadingRNAFromSeurat is in config
• Cell IDs in output are prefixed with sample names (metadata column: Sample)

Normalization Method Constraints

• SCTransform: Sets default assay to "SCT"
  • Incompatible with: NormalizeData, FindVariableFeatures, ScaleData, RunPCA (when use_sct = true)
  • Compatible with: All integration methods
• Standard workflow: Sets default assay to "RNA"
  • Required when: use_sct = false
  • Sequence: NormalizeData → FindVariableFeatures → ScaleData → RunPCA

Integration Method Constraints

• SCTransform + Integration: When use_sct = true, IntegrateLayers.normalization-method defaults to "SCT"
• No integration: Set no_integration = true for single sample or pre-integrated data
• Integration required: Automatic for multi-sample data unless no_integration = true

Doublet Detection Constraints

• DoubletFinder vs scDblFinder: Choose one, not both
• SCTransform compatibility: Both detectors work with SCTransform
• Memory: DoubletFinder may require lower ncores than other processes

Cache Configuration

• cache = "/tmp": Default, uses system temp directory
• cache = true: Caches in job output directory (not cleaned on re-run)
• cache = false: Disables caching (re-runs entire process)
• Force re-run: Delete <signature>.<kind>.RDS files or set cache = false

Troubleshooting

Issue: Too many cells filtered by QC

Symptoms: Low cell count after SeuratPreparing Solutions:

• Relax cell_qc thresholds: "nFeature_RNA > 100 & percent.mt < 20"
• Check percent.mt calculation: Ensure mitochondrial genes are prefixed correctly (human: MT-, mouse: mt-)
• Review nFeature_RNA and nCount_RNA distributions in QC plots
• Consider per-sample QC if batches differ significantly

Issue: Integration overcorrects biological variation

Symptoms: Clusters mix distinct cell types after integration Solutions:

• Switch from CCA to RPCA: method = "rpca"
• Switch from CCA/RPCA to Harmony: method = "harmony"
• Reduce integration strength: Adjust method-specific parameters
• Try no integration if batches are minimal: no_integration = true

Issue: High doublet rate detected (>15%)

Symptoms: More doublets than expected Solutions:

• Check doublets or dbr parameter matches actual loading
• Adjust expected doublet rate to match data loading
• Review cell loading: High UMI loading increases doublets
• Consider re-running cellranger with adjusted parameters

Issue: SCTransform returns too few genes

Symptoms: Low number of genes in SCT assay Solutions:

• Increase min_cells: [SeuratPreparing.envs.SCTransform.min_cells = 0
• Disable var-gene-only: return-only-var-genes = false
• Check variable.features.n: Increase to 5000 or higher
• Review variable.features.rv.th: Lower threshold (e.g., 1.2)

Issue: Memory errors during processing

Symptoms: Process killed or out-of-memory errors Solutions:

• Reduce ncores: Parallelization uses more memory
• Reduce ncells in SCTransform: Subsample for model fitting
• Use conserve.memory = true in SCTransform
• Switch to RPCA integration: Faster and less memory-intensive than CCA
• Reduce DoubletFinder ncores: Set to 1-2 cores

Issue: Slow processing for large datasets

Symptoms: Process takes >24 hours Solutions:

• Increase ncores (with sufficient memory)
• Use RPCA instead of CCA: method = "rpca"
• Use scDblFinder instead of DoubletFinder: Faster doublet detection
• Reduce ncells in SCTransform: Faster model fitting
• Enable caching: cache = true for faster re-runs

Issue: Batch effects remain after integration

Symptoms: Cells cluster by sample rather than cell type Solutions:

• Try different integration method: CCA for strong differences, RPCA/Harmony for subtle differences
• Regress batch variables: vars.to.regress = ["batch_var"]
• Check if biological differences are real: Batch vs condition effects
• Increase integration parameters: More PCs, longer Harmony iterations

Issue: Seurat v5 compatibility errors

Symptoms: Assay layer errors, deprecated function warnings Solutions:

• Ensure Seurat v5.0.0+ is installed: install.packages("Seurat")
• Update workflow: Use IntegrateLayers instead of FindIntegrationAnchors
• Check assay structure: object[["RNA"]] vs object@assays$RNA
• Review Seurat v5 migration guide: https://satijalab.org/seurat/articles/seurat5_integration

Quick Reference

Default Parameter Values

ncores = 1
min_cells = 0
min_features = 0
cell_qc = ""
gene_qc = { min_cells = 0 }
use_sct = false
no_integration = false
doublet_detector = "none"
cache = "/tmp"

# NormalizeData
normalization-method = "LogNormalize"
scale-factor = 10000

# FindVariableFeatures
selection-method = "vst"
nfeatures = 2000

# SCTransform
variable.features.n = 3000
variable.features.rv.th = 1.3
min_cells = 3
return-only-var-genes = true

# IntegrateLayers
method = "harmony"

# DoubletFinder
PCs = 10
doublets = 0.075
pN = 0.25

# scDblFinder
dbr = 0.075

QC Metric Keys (Available in cell_qc expressions)

• nFeature_RNA: Number of genes detected per cell
• nCount_RNA: Total UMI counts per cell
• percent.mt: Percentage of mitochondrial gene expression
• percent.ribo: Percentage of ribosomal gene expression
• percent.hb: Percentage of hemoglobin gene expression
• percent.plat: Percentage of platelet gene expression

Integration Method Selection Guide

| Situation | Recommended Method | Reason | |-----------|-------------------|---------| | Strong biological differences | CCA | Captures shared biology despite expression shifts | | Same platform, large data | RPCA | Faster, conservative, less overcorrection | | Complex batch structure | Harmony | Handles multiple batch variables | | Very large datasets (>200k) | RPCA or scVI | Scales well computationally | | Cross-modality integration | CCA or FastMNN | Designed for different data types | | Preliminary analysis | Harmony | Fast, good default performance |

Seurat Assay Information After Processing

• use_sct = false: Default assay = RNA (normalized, scaled)
• use_sct = true: Default assay = SCT (variance-stabilized)
• CCA/RPCA integration: Default assay = integrated
• Harmony integration: Default assay = SCT (if use_sct = true) or RNA (if use_sct = false)