topexpressinggenesofallcells

name	topexpressinggenesofallcells
description	Identifies and visualizes the top expressing genes per cluster across ALL cells (before T/B cell selection), followed by pathway enrichment analysis. Provides initial overview of all cell populations by highlighting the most highly expressed genes and their biological functions.

TopExpressingGenesOfAllCells Process Configuration

Purpose

Identifies and visualizes the top expressing genes per cluster across ALL cells (before T/B cell selection), followed by pathway enrichment analysis. Provides initial overview of all cell populations by highlighting the most highly expressed genes and their biological functions.

When to Use

• After: SeuratClusteringOfAllCells process
• Before: TOrBCellSelection (this is a pre-selection analysis)
• Use cases:
  • Quick overview of ALL cell populations before separation
  • Initial assessment of broad cell type signatures
  • Understanding overall cell composition before T/B selection
  • Pathway enrichment on cell type markers before detailed analysis
  • Quality check for unexpected cell types
  • Complementary to ClusterMarkersOfAllCells for complete pre-selection profiling
• Optional process: Enable only when pre-selection analysis is needed

Configuration Structure

Process Enablement

[TopExpressingGenesOfAllCells]
cache = true

Input Specification

[TopExpressingGenesOfAllCells.in]
srtobj = ["SeuratClusteringOfAllCells"]

Note: srtobj accepts the output from SeuratClusteringOfAllCells.

Environment Variables

Core Parameters

[TopExpressingGenesOfAllCells.envs]
# Number of top expressing genes to identify per cluster
n = 250

# Enrichment style
enrich_style = "enrichr"  # Options: "enrichr", "clusterprofiler"

# Enrichment databases
dbs = ["KEGG_2021_Human", "MSigDB_Hallmark_2020"]

Enrichment Plot Settings

[TopExpressingGenesOfAllCells.envs.enrich_plots_defaults]
# Plot type for enrichment results
plot_type = "bar"  # Options: "bar", "dot", "lollipop", "network", "enrichmap", "wordcloud"

# Device parameters
devpars = {res = 100, width = 800, height = 600}

# Additional output formats
more_formats = []

# Save R code to reproduce plots
save_code = false

# Top terms to display
top_term = 10  # Number of top enriched pathways to show
ncol = 1  # Number of columns in multi-panel plots

Cell Subsetting

[TopExpressingGenesOfAllCells.envs]
# Subset cells before analysis (optional)
subset = ""

Cache Control

[TopExpressingGenesOfAllCells.envs]
# Cache intermediate results
cache = "/tmp"  # true, false, or directory path

Configuration Examples

Minimal Configuration

[TopExpressingGenesOfAllCells]

[TopExpressingGenesOfAllCells.in]
srtobj = ["SeuratClusteringOfAllCells"]

Top 10 Genes for Broad Cell Type ID

[TopExpressingGenesOfAllCells]

[TopExpressingGenesOfAllCells.in]
srtobj = ["SeuratClusteringOfAllCells"]

[TopExpressingGenesOfAllCells.envs]
n = 10
dbs = ["MSigDB_Hallmark_2020"]

Multiple Databases for Comprehensive Overview

[TopExpressingGenesOfAllCells]

[TopExpressingGenesOfAllCells.in]
srtobj = ["SeuratClusteringOfAllCells"]

[TopExpressingGenesOfAllCells.envs]
n = 100
dbs = [
  "KEGG_2021_Human",
  "MSigDB_Hallmark_2020",
  "GO_Biological_Process_2025"
]

Common Patterns

Pattern 1: Quick All-Cell Overview (Pre-Selection)

[TopExpressingGenesOfAllCells]

[TopExpressingGenesOfAllCells.in]
srtobj = ["SeuratClusteringOfAllCells"]

[TopExpressingGenesOfAllCells.envs]
n = 10
dbs = ["MSigDB_Hallmark_2020"]

[TopExpressingGenesOfAllCells.envs.enrich_plots_defaults]
plot_type = "bar"
top_term = 10

What to expect: Top 10 genes per cluster showing broad cell type markers (CD3 for T cells, CD19 for B cells, CD14 for monocytes, etc.)

Pattern 2: Broad Cell Type Signature Identification

[TopExpressingGenesOfAllCells]

[TopExpressingGenesOfAllCells.in]
srtobj = ["SeuratClusteringOfAllCells"]

[TopExpressingGenesOfAllCells.envs]
n = 50

[TopExpressingGenesOfAllCells.envs.enrich_plots]
"T Cell Pathways" = {plot_type = "bar", dbs = ["KEGG_2021_Human"]}
"B Cell Pathways" = {plot_type = "bar", dbs = ["KEGG_2021_Human"]}
"Myeloid Pathways" = {plot_type = "bar", dbs = ["KEGG_2021_Human"]}

What to expect: Identification of T cell (CD3E, CD3D), B cell (CD19, MS4A1), and myeloid (CD14, LYZ) signatures across clusters

Pattern 3: Quality Check for Unexpected Cell Types

[TopExpressingGenesOfAllCells]

[TopExpressingGenesOfAllCells.in]
srtobj = ["SeuratClusteringOfAllCells"]

[TopExpressingGenesOfAllCells.envs]
n = 20
dbs = [
  "GO_Biological_Process_2025",
  "GO_Cellular_Component_2025"
]

[TopExpressingGenesOfAllCells.envs.enrich_plots_defaults]
plot_type = "dot"
top_term = 15

What to expect: Detection of contamination (e.g., EPCAM for epithelial, COL1A1 for fibroblasts, RBC markers)

Difference from TopExpressingGenes

TopExpressingGenesOfAllCells vs TopExpressingGenes:

Aspect	TopExpressingGenesOfAllCells	TopExpressingGenes
When it runs	BEFORE TOrBCellSelection	AFTER TOrBCellSelection
Input data	All cells (unfiltered)	Only selected T or B cells
Upstream process	SeuratClusteringOfAllCells	SeuratClustering + TOrBCellSelection
Use case	Initial assessment, quality check	Detailed T/B cell analysis
Cell types	ALL cell types present	Only T OR B cells
Typical markers	CD3, CD19, CD14, etc.	Specific T/B cell subtypes
Position in workflow	Pre-selection overview	Post-selection deep dive

Workflow context:

RNA Input → SeuratPreparing → SeuratClusteringOfAllCells
                                              ↓
                                      TopExpressingGenesOfAllCells  ← Runs here
                                              ↓
                                      TOrBCellSelection (separates T/B)
                                              ↓
                                      SeuratClustering (on selected cells)
                                              ↓
                                      TopExpressingGenes  ← Runs here

Recommendation:

• Use TopExpressingGenesOfAllCells to assess overall data quality and cell type composition
• Use TopExpressingGenes for detailed analysis of T or B cell subtypes
• Enable both for comprehensive analysis: pre-selection overview + post-selection deep dive

Dependencies

• Upstream: SeuratClusteringOfAllCells
• Downstream: TOrBCellSelection (optional - this process provides pre-selection context)
• Data: Seurat object with cluster assignments for ALL cells

Validation Rules

• n parameter: Must be positive integer (typically 10-500)
• dbs: Must be valid enrichit/Enrichr database names or local GMT file paths
• enrich_style: Must be "enrichr" or "clusterprofiler"
• plot_type: Must be valid scplotter plot type
• Workflow requirement: Only runs when SeuratClusteringOfAllCells is enabled

Troubleshooting

Process Not Running

Issue: TopExpressingGenesOfAllCells not executed despite being in config

Causes:

• SeuratClusteringOfAllCells not enabled
• Missing dependency in workflow
• Process disabled via validation warning

Solutions:

1. Ensure SeuratClusteringOfAllCells is enabled in config
2. Check validation warnings: python -m immunopipe.validate_config config.toml
3. Verify both processes in config:

   [SeuratClusteringOfAllCells]
   [TopExpressingGenesOfAllCells]
   

Mixed Cell Types in Results

Issue: Clusters show multiple cell type markers (CD3 + CD19)

Causes:

• Overlapping clusters (resolution too low)
• Doublets/multiplets not filtered
• Contamination in data

Solutions:

1. Adjust clustering resolution in SeuratClusteringOfAllCells
2. Filter doublets in SeuratPreparing step
3. Use TOrBCellSelection after assessment to clean data

No Clear Cell Type Signatures

Issue: Top genes list lacks expected markers (CD3, CD19, CD14)

Causes:

• Data quality issues (low counts, high mitochondrial)
• Wrong organism (human vs mouse gene symbols)
• Incomplete clustering

Solutions:

1. Check QC metrics in SeuratClusterStatsOfAllCells
2. Verify organism (uppercase=human, titlecase=mouse)
3. Review clustering results from SeuratClusteringOfAllCells

Ribosomal/Mitochondrial Gene Dominance

Issue: Top genes list dominated by housekeeping genes (RPS, RPL, MT-)

Solutions:

1. Increase n parameter to see beyond housekeeping genes
2. Filter out ribosomal/mitochondrial genes in SeuratPreparing step
3. Use ClusterMarkersOfAllCells for differential expression

Empty Enrichment Results

Issue: No pathways enriched despite top genes identified

Causes:

• Gene identifiers don't match database
• n too small for meaningful enrichment
• Database not appropriate for cell type

Solutions:

1. Increase n to 100-500 genes
2. Verify species match (check gene symbols)
3. Try different databases (e.g., GO_Biological_Process_2025)

Plot Rendering Errors

Issue: Enrichment plots fail to render

Causes:

• Network plots with too many terms
• Missing dependencies in R environment

Solutions:

1. Reduce top_term parameter
2. Use simpler plot types (bar, dot)
3. Verify R packages installed: enrichit, scplotter

Output Structure

<srtobj_stem>.top_expressing_genes/
├── <cluster_name>/              # One subdirectory per cluster (ALL cells)
│   ├── top_genes.tsv            # Top N genes with expression metrics
│   └── enrich/                 # Enrichment results
│       ├── <db_name>/          # One subdirectory per database
│       │   ├── *.Bar-Plot.png  # Enrichment plots
│       │   ├── *.enrich.tsv    # Enrichment tables
│       │   └── ...

External References

Enrichment Databases (enrichit)

Full reference

Built-in databases:

• KEGG_2021_Human - KEGG pathways (human)
• MSigDB_Hallmark_2020 - MSigDB Hallmark gene sets
• GO_Biological_Process_2025 - GO Biological Process terms
• GO_Cellular_Component_2025 - GO Cellular Component terms
• GO_Molecular_Function_2025 - GO Molecular Function terms
• Reactome_Pathways_2024 - Reactome pathways
• WikiPathways_2024_Human - WikiPathways (human)

Enrichr libraries: See https://maayanlab.cloud/Enrichr/#libraries

Enrichment Plot Types (scplotter)

Full reference

• bar - Bar chart of enriched terms
• dot - Dot plot (bubble chart)
• lollipop - Lollipop plot
• network - Network visualization of term relationships
• enrichmap - Enrichment map (similar to Cytoscape)
• wordcloud - Word cloud visualization

Enrichment Styles

• enrichr - Fisher's exact test (Enrichr-style)
• clusterprofiler - Hypergeometric test (clusterProfiler-style)

See Also

• TopExpressingGenes - Top genes for selected T/B cells after selection
• ClusterMarkersOfAllCells - Differential expression for all cells before selection
• SeuratClusteringOfAllCells - Clustering on all cells before T/B selection
• TOrBCellSelection - T/B cell separation process