modulescorecalculator

Purpose: Calculate module/pathway/gene signature scores per cell using Seurat's AddModuleScore or CellCycleScoring functions.

When to Use

• To score cells for specific gene programs (exhaustion, cytotoxicity, proliferation)
• For pathway activity analysis using curated gene sets
• To quantify functional states (activation, differentiation, memory)
• To add diffusion map components for trajectory analysis
• For cell cycle scoring to identify S and G2M phase cells

Configuration Structure

Process Enablement

[ModuleScoreCalculator]
cache = true

Input Specification

[ModuleScoreCalculator.in]
# Input: Seurat object from SeuratClustering
srtobj = ["SeuratClustering"]

Environment Variables

[ModuleScoreCalculator.envs]
# Default parameters inherited by all modules
defaults = { nbin = 24, ctrl = 100, seed = 8525, agg = "mean" }

# Module definitions (key = module name, value = gene set parameters)
modules = {}

# Post-scoring metadata transformations
post_mutaters = {}

External References

Seurat AddModuleScore Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | features | string/list | Required | Gene names or cc.genes/cc.genes.updated.2019 for cell cycle | | nbin | int | 24 | Number of bins for aggregate expression levels of all analyzed features | | ctrl | int | 100 | Number of control features selected from same bin per analyzed feature | | k | boolean | false | Use feature clusters from DoKMeans instead of random selection | | assay | string | NULL | The assay to use (defaults to active assay) | | seed | int | 8525 | Random seed for reproducibility | | search | boolean | false | Search for symbol synonyms if features don't match | | keep | boolean | false | Keep individual feature scores (non-cell cycle only) | | agg | string | "mean" | Aggregation function: mean, median, sum, max, min, var, sd |

Reference: https://satijalab.org/seurat/reference/addmodulescore

CellCycleScoring Parameters

When using features = "cc.genes" or "cc.genes.updated.2019", adds:

• S.Score - S phase score per cell
• G2M.Score - G2M phase score per cell
• Phase - Cell cycle phase assignment (G1, S, G2M)

Reference: https://satijalab.org/seurat/reference/cellcyclescoring

Diffusion Map Parameters

{"DC": {"features": 2, "kind": "diffmap"}}

Adds first N diffusion components as metadata columns (DC_1, DC_2, ...).

Reference: https://www.rdocumentation.org/packages/destiny/versions/2.0.4/topics/DiffusionMap

Configuration Examples

Minimal Configuration

[ModuleScoreCalculator]
[ModuleScoreCalculator.in]
srtobj = ["SeuratClustering"]

Cell Cycle Scoring

[ModuleScoreCalculator.envs.modules]
CellCycle = { features = "cc.genes.updated.2019" }

Output columns: S.Score, G2M.Score, Phase

Exhaustion Score (T Cells)

[ModuleScoreCalculator.envs.modules.Exhaustion]
features = "HAVCR2,ENTPD1,LAYN,LAG3,TIGIT,PDCD1,TOX"

Cytotoxicity Score (CD8+ T Cells, NK Cells)

[ModuleScoreCalculator.envs.modules.Cytotoxicity]
features = "GZMB,PRF1,NKG7,GNLY,CTSW"

Proliferation Score

[ModuleScoreCalculator.envs.modules.Proliferation]
features = "MKI67,STMN1,TUBB,PCNA,TOP2A"

Activation Score

[ModuleScoreCalculator.envs.modules.Activation]
features = "IFNG,TNF,CD69,CD25"

Multiple Gene Sets (Functional States)

[ModuleScoreCalculator.envs.modules]
[ModuleScoreCalculator.envs.modules.CellCycle]
features = "cc.genes.updated.2019"

[ModuleScoreCalculator.envs.modules.Exhaustion]
features = "HAVCR2,ENTPD1,LAYN,LAG3,TIGIT,PDCD1"

[ModuleScoreCalculator.envs.modules.Activation]
features = "IFNG,TNF,CD69,CD25"

[ModuleScoreCalculator.envs.modules.Proliferation]
features = "MKI67,STMN1,TUBB,PCNA"

Diffusion Map Components

[ModuleScoreCalculator.envs.modules]
DC = { features = 2, kind = "diffmap" }

Use with: env.dimplots in SeuratClusterStats with reduction = "DC"

Post-Metadata Transformation

[ModuleScoreCalculator.envs.post_mutaters]
# Calculate combined exhaustion-activation ratio
Exh_Act_Ratio = "Exhaustion1 / Activation1"

# Classify high vs low exhaustion
Exhaustion_Level = "ifelse(Exhaustion1 > median(Exhaustion1, na.rm = TRUE), 'High', 'Low')"

Common Patterns

Pattern 1: T Cell Functional States

[ModuleScoreCalculator.envs.modules]
# Exhaustion markers (checkpoint genes)
Exhaustion = {
    features = "HAVCR2,ENTPD1,LAYN,LAG3,TIGIT,PDCD1,TOX,CTLA4"
}

# Activation markers
Activation = {
    features = "IFNG,TNF,CD69,CD25,IL2RA"
}

# Memory markers
Memory = {
    features = "IL7R,CCR7,SELL,S100A4"
}

# Terminal differentiation
Terminal_Diff = {
    features = "TIGIT,PDCD1,CD274,CD244,CD160"
}

Pattern 2: NK Cell Functional States

[ModuleScoreCalculator.envs.modules]
# Cytotoxicity
Cytotoxicity = {
    features = "GZMB,PRF1,NKG7,GNLY,CTSW"
}

# Activation
NK_Activation = {
    features = "NCAM1,KLRD1,FCGR3A"
}

# Exhaustion
NK_Exhaustion = {
    features = "HAVCR2,LAG3,PDCD1,TIGIT"
}

Pattern 3: Cell Cycle with Custom Parameters

[ModuleScoreCalculator.envs.defaults]
nbin = 24
ctrl = 100
seed = 8525

[ModuleScoreCalculator.envs.modules]
CellCycle = {
    features = "cc.genes.updated.2019"
}

Pattern 4: Metabolic Pathway Scores

[ModuleScoreCalculator.envs.modules]
# Glycolysis (Warburg effect)
Glycolysis = {
    features = "HK2,PKM,LDHA,PFKL,ENO1"
}

# Oxidative phosphorylation
OXPHOS = {
    features = "ND1,ND2,ND3,COX1,COX2,ATP5A1"
}

# Fatty acid oxidation
FAO = {
    features = "CPT1A,ACOX1,HADHA"
}

Pattern 5: B Cell Functionality

[ModuleScoreCalculator.envs.modules]
# Plasma cell differentiation
Plasma = {
    features = "MZB1,SSR4,SDC1,XBP1,PRDM1"
}

# Germinal center
Germinal_Center = {
    features = "BCL6,AICDA,MEF2B"
}

# Naive vs memory
Naive = {
    features = "IL7R,CCR7,IGHD"
}
Memory = {
    features = "CD27,IGG1,IGHG1"
}

Gene Set Resources

MSigDB (Molecular Signatures Database)

• URL: https://www.gsea-msigdb.org/
• Hallmark Collection: 50 curated gene sets for biological processes
  • HALLMARK_INTERFERON_GAMMA_RESPONSE
  • HALLMARK_TNFA_SIGNALING_VIA_NFKB
  • HALLMARK_INFLAMMATORY_RESPONSE
  • HALLMARK_HYPOXIA
  • HALLMARK_APOPTOSIS
• Immunologic Signatures (C7): Gene sets from immunology studies
• Download: Available in GMT format for direct use

CellMarker Database

• URL: http://bioinfo.life.hust.edu.cn/CellMarker/
• Cell type-specific markers for human and mouse

Literature-Derived Signatures

T Cell Exhaustion Markers:

• Primary: HAVCR2 (TIM-3), PDCD1 (PD-1), LAG3, TIGIT, CTLA4
• Transcription factors: TOX, NR4A1, EOMES

T Cell Activation Markers:

• Cytokines: IFNG, TNF, IL2
• Surface: CD69, CD25 (IL2RA), CD38

Cytotoxicity Markers:

• Granzymes: GZMB, GZMA, GZMH
• Perforin: PRF1
• NK receptors: NKG7, GNLY, CTSW

Proliferation Markers:

• Ki-67: MKI67
• Tubulin: STMN1, TUBB
• PCNA: PCNA, TOP2A

Cell Cycle Genes (Seurat built-in):

• cc.genes - Original Tirosh et al. 2016 gene set
• cc.genes.updated.2019 - Updated with 2019 gene symbols

Dependencies

Upstream Processes

• Required: SeuratClustering - Provides the Seurat object
• Optional: TOrBCellSelection - If working with T/B cell subsets

Downstream Processes

• SeuratClusterStats - Visualize module scores across clusters
• CellCellCommunication - Correlate scores with cell interactions
• ScFGSEA - Validate module activity with enrichment analysis

Validation Rules

Gene Set Format Validation

• Comma-separated strings: "GENE1,GENE2,GENE3" ✓
• Cell cycle keywords: "cc.genes" or "cc.genes.updated.2019" ✓
• Diffusion map: {"features": N, "kind": "diffmap"} ✓

Gene Name Matching

• Human genes: Uppercase (MKI67, IFNG) ✓
• Mouse genes: Title case (Mki67, Ifng) ✓
• Search mode: Set search = true to automatically find synonyms
• Keep mode: Set keep = true to retain unmatched features

Parameter Constraints

• nbin: Typically 10-50 (default 24)
• ctrl: Typically 10-500 (default 100)
• Minimum genes: ≥5 genes recommended for robust scoring
• Maximum genes: No hard limit, but performance may degrade >1000 genes

Troubleshooting

Issue: Genes Not Found in Object

Symptom: Warning "XX% of features not found in object"

Solutions:

1. Check gene name format (uppercase for human, title case for mouse)
2. Enable search = true to find symbol synonyms
3. Verify gene symbols match your Seurat object's row names
4. Use search = true + keep = true to debug missing genes

Issue: Too Few Genes in Set

Symptom: Module score is NA or unreliable

Solutions:

1. Ensure ≥5 genes in gene set for robust scoring
2. Add alternative markers to expand gene set
3. Check if genes are expressed in your dataset
4. Use keep = true to see how many genes matched

Issue: Cell Cycle Score All G1

Symptom: Most cells classified as G1 phase

Solutions:

1. Check if cells are truly non-proliferating (e.g., memory T cells)
2. Verify data quality (low UMI counts may obscure cell cycle)
3. Consider using cc.genes instead of cc.genes.updated.2019
4. Check S.Score and G2M.Score values directly

Issue: Module Scores All Similar

Symptom: No variation in scores across cells

Solutions:

1. Genes may be uniformly expressed or not detected
2. Try adjusting nbin and ctrl parameters
3. Verify assay selection (assay = "RNA" vs "SCT")
4. Check if cells express the expected markers

Issue: Diffusion Map Components Not Added

Symptom: DC_1, DC_2 columns missing

Solutions:

1. Ensure destiny R package is installed
2. Verify SingleCellExperiment package is available
3. Use correct format: {"DC": {"features": 2, "kind": "diffmap"}}
4. Requires R packages: SingleCellExperiment, destiny

Best Practices

Gene Set Selection

• Use literature-validated signatures when possible
• Combine complementary markers (e.g., exhaustion: HAVCR2 + PDCD1 + LAG3)
• Consider species-specific marker expression patterns
• Test gene sets on a subset before full pipeline run

Parameter Tuning

• nbin = 24: Default works well for most datasets
• ctrl = 100: Increase if many genes have similar expression levels
• seed = 8525: Keep fixed for reproducibility across runs
• agg = "mean": Use median for outlier-resistant aggregation

Visualization

• Use SeuratClusterStats.envs.dimplots to visualize scores
• Add to SeuratClusterStats.envs.violins for distribution plots
• Correlate scores with clusters or annotations
• Consider post_mutaters for custom score transformations

Performance

• Module scoring is computationally cheap (<5 min for typical datasets)
• Larger gene sets (>1000 genes) may take longer
• Diffusion map computation scales with cell number (O(n²))

Integration Example

# Complete workflow with multiple scores
[ModuleScoreCalculator.envs.defaults]
nbin = 24
ctrl = 100
seed = 8525

[ModuleScoreCalculator.envs.modules]
# Cell cycle
CellCycle = { features = "cc.genes.updated.2019" }

# T cell function
Exhaustion = { features = "HAVCR2,ENTPD1,LAYN,LAG3,TIGIT,PDCD1,TOX,CTLA4" }
Activation = { features = "IFNG,TNF,CD69,CD25" }
Memory = { features = "IL7R,CCR7,SELL,S100A4" }

# Cytotoxicity
Cytotoxicity = { features = "GZMB,PRF1,NKG7,GNLY" }

# Metabolism
Glycolysis = { features = "HK2,PKM,LDHA,PFKL,ENO1" }

[ModuleScoreCalculator.envs.post_mutaters]
# Classify T cell states
Tcell_State = """
case_when(
    Exhaustion1 > median(Exhaustion1, na.rm = TRUE) ~ 'Exhausted',
    Activation1 > median(Activation1, na.rm = TRUE) ~ 'Activated',
    Memory1 > median(Memory1, na.rm = TRUE) ~ 'Memory',
    TRUE ~ 'Naive'
)
"""

# Combined functional score
Functionality = "(Activation1 + Cytotoxicity1) / (Exhaustion1 + 1)"

Notes

• Process is optional: Only runs when [ModuleScoreCalculator] section exists in config
• Multiple modules: Define any number of modules in modules dictionary
• Column naming: Scores stored as ModuleName1, ModuleName2, etc.
• Cell cycle special case: Uses CellCycleScoring() which adds S.Score, G2M.Score, Phase
• Diffusion map: Special module type for trajectory analysis
• Post-processing: Use post_mutaters for custom metadata calculations
• Visualization: Scores available in SeuratClusterStats for plotting

Quick Reference

Gene Set Formats:

# Comma-separated
features = "GENE1,GENE2,GENE3"

# Cell cycle (built-in)
features = "cc.genes.updated.2019"

# Diffusion map (special)
features = 2
kind = "diffmap"

Common Gene Sets:

Exhaustion = "HAVCR2,PDCD1,LAG3,TIGIT,CTLA4,TOX"
Cytotoxicity = "GZMB,PRF1,NKG7,GNLY"
Proliferation = "MKI67,STMN1,PCNA,TOP2A"
Activation = "IFNG,TNF,CD69,CD25"
Memory = "IL7R,CCR7,SELL"

Process Location: /immunopipe/processes.py (line 455) Documentation: /docs/processes/ModuleScoreCalculator.md Function: Seurat::AddModuleScore(), Seurat::CellCycleScoring()