Gene Enrichment and Pathway Analysis

NOT for (use other skills instead):

• Network pharmacology / drug repurposing → Use tooluniverse-network-pharmacology
• Disease characterization → Use tooluniverse-multiomic-disease-characterization
• Single gene function lookup → Use tooluniverse-disease-research
• Spatial omics analysis → Use tooluniverse-spatial-omics-analysis
• Protein-protein interaction analysis only → Use tooluniverse-protein-interactions

Input Parameters

Core Principles

1. Report-first approach - Create report file FIRST, then populate progressively
2. ID disambiguation FIRST - Detect and convert gene IDs before ANY enrichment
3. Multi-source validation - Run enrichment on at least 2 independent tools, cross-validate
4. Exact p-values - Report raw p-values AND adjusted p-values with correction method
5. Multiple testing correction - ALWAYS apply Benjamini-Hochberg unless user specifies otherwise
6. Gene set size filtering - Filter by min/max gene set size to avoid trivial/overly broad terms
7. Evidence grading - Grade enrichment sources T1-T4
8. Negative results documented - "No significant enrichment" is a valid finding
9. Source references - Every enrichment result must cite the tool/database/library used
10. Completeness checklist - Mandatory section at end showing analysis coverage

Decision Tree: ORA vs GSEA

Q: Do you have a ranked gene list (with scores/fold-changes)?
  YES → Use GSEA (gseapy.prerank)
        - Input: Gene-to-score mapping (e.g., log2FC)
        - Statistics: Running enrichment score, permutation test
        - Cutoff: FDR q-val < 0.25 (standard for GSEA)
        - Output: NES (Normalized Enrichment Score), lead genes
        See: references/gsea_workflow.md

  NO  → Use ORA (gseapy.enrichr)
        - Input: Gene list only
        - Statistics: Fisher's exact test, hypergeometric
        - Cutoff: Adjusted P-value < 0.05 (or user specified)
        - Output: P-value, adjusted P-value, overlap, odds ratio
        See: references/ora_workflow.md

Decision Tree: gseapy vs ToolUniverse Tools

Q: Which enrichment method should I use?

Primary Analysis (ALWAYS):
  ├─ gseapy.enrichr (ORA) OR gseapy.prerank (GSEA)
  │  - Most comprehensive (225+ Enrichr libraries)
  │  - GO (BP, MF, CC), KEGG, Reactome, WikiPathways, MSigDB
  │  - All organisms supported
  │  - Returns: P-value, Adjusted P-value, Overlap, Genes
  │  See: references/enrichr_guide.md

Cross-Validation (REQUIRED for publication):
  ├─ PANTHER_enrichment [T1 - curated]
  │  - Curated GO enrichment
  │  - Multiple organisms (taxonomy ID)
  │  - GO BP, MF, CC, PANTHER pathways, Reactome
  │
  ├─ STRING_functional_enrichment [T2 - validated]
  │  - Returns ALL categories in one call
  │  - Filter by category: Process, Function, Component, KEGG, Reactome
  │  - Network-based enrichment
  │
  └─ ReactomeAnalysis_pathway_enrichment [T1 - curated]
     - Reactome curated pathways
     - Cross-species projection
     - Detailed pathway hierarchy

Additional Context (Optional):
  ├─ GO_get_term_by_id, QuickGO_get_term_detail (GO term details)
  ├─ Reactome_get_pathway, Reactome_get_pathway_hierarchy (pathway context)
  ├─ WikiPathways_search, WikiPathways_get_pathway (community pathways)
  └─ STRING_ppi_enrichment (network topology analysis)

Quick Start Workflow

Step 1: Create Report File (IMMEDIATE)

report_path = f"{analysis_name}_enrichment_report.md"
# Write header with placeholder sections
# Update progressively as analysis proceeds

Step 2: ID Conversion and Validation

from tooluniverse import ToolUniverse
tu = ToolUniverse()
tu.load_tools()

# Detect ID type
gene_list = ["TP53", "BRCA1", "EGFR"]
# Auto-detect: ENSG* = Ensembl, numeric = Entrez, pattern = UniProt, else = Symbol

# Convert if needed (Ensembl/Entrez → Symbol)
result = tu.tools.MyGene_batch_query(
    gene_ids=gene_list,
    fields="symbol,entrezgene,ensembl.gene"
)
# Extract symbols from results

# Validate with STRING
mapped = tu.tools.STRING_map_identifiers(
    protein_ids=gene_symbols,
    species=9606  # human
)
# Use preferredName for canonical symbols

See: references/id_conversion.md for complete examples

Step 3: Primary Enrichment with gseapy

For ORA (gene list only):

import gseapy

# GO Biological Process
go_bp = gseapy.enrichr(
    gene_list=gene_symbols,
    gene_sets='GO_Biological_Process_2021',
    organism='human',
    outdir=None,
    no_plot=True,
    background=background_genes  # None = genome-wide
)
go_bp_sig = go_bp.results[go_bp.results['Adjusted P-value'] < 0.05]

For GSEA (ranked gene list):

import pandas as pd

# Ranked by log2FC
ranked_series = pd.Series(gene_to_score).sort_values(ascending=False)

gsea_result = gseapy.prerank(
    rnk=ranked_series,
    gene_sets='GO_Biological_Process_2021',
    outdir=None,
    no_plot=True,
    seed=42,
    min_size=5,
    max_size=500,
    permutation_num=1000
)
gsea_sig = gsea_result.res2d[gsea_result.res2d['FDR q-val'] < 0.25]

See:

• references/ora_workflow.md for complete ORA examples
• references/gsea_workflow.md for complete GSEA examples
• references/enrichr_guide.md for all 225+ libraries

Step 4: Cross-Validation with ToolUniverse

# PANTHER [T1 - curated]
panther_bp = tu.tools.PANTHER_enrichment(
    gene_list=','.join(gene_symbols),  # comma-separated string
    organism=9606,
    annotation_dataset='GO:0008150'  # biological_process
)

# STRING [T2 - validated]
string_result = tu.tools.STRING_functional_enrichment(
    protein_ids=gene_symbols,
    species=9606
)
# Filter by category: Process, Function, Component, KEGG, Reactome

# Reactome [T1 - curated]
reactome_result = tu.tools.ReactomeAnalysis_pathway_enrichment(
    identifiers=' '.join(gene_symbols),  # space-separated
    page_size=50,
    include_disease=True
)

See: references/cross_validation.md for comparison strategies

Step 5: Report Compilation

## Results

### GO Biological Process (Top 10)
| Term | P-value | Adj. P-value | Overlap | Genes | Evidence |
|------|---------|-------------|---------|-------|----------|
| regulation of cell cycle (GO:0051726) | 1.2e-08 | 3.4e-06 | 12/45 | TP53;BRCA1;... | [T2] gseapy |

### Cross-Validation
| GO Term | gseapy FDR | PANTHER FDR | STRING FDR | Consensus |
|---------|-----------|-------------|-----------|-----------|
| GO:0051726 | 3.4e-06 | 2.1e-05 | 1.8e-05 | 3/3 ✓ |

### Completeness Checklist
- [x] ID Conversion (MyGene, STRING) - 95% mapped
- [x] GO BP (gseapy, PANTHER, STRING) - 24 significant terms
- [x] GO MF (gseapy, PANTHER, STRING) - 18 significant terms
- [x] GO CC (gseapy, PANTHER, STRING) - 12 significant terms
- [x] KEGG (gseapy, STRING) - 8 significant pathways
- [x] Reactome (gseapy, ReactomeAPI) - 15 significant pathways
- [x] Cross-validation - 12 consensus terms (2+ sources)

See: scripts/format_enrichment_output.py for automated formatting

Evidence Grading

Supported Organisms

See: references/organism_support.md for organism-specific libraries

Common Patterns

Pattern 1: Standard DEG Enrichment (ORA)

Input: List of differentially expressed gene symbols
Flow: ID validation → gseapy ORA (GO + KEGG + Reactome) →
      PANTHER + STRING cross-validation → Report top enriched terms
Use: When you have unranked gene list from DESeq2/edgeR

Pattern 2: Ranked Gene List (GSEA)

Input: Gene-to-log2FC mapping from differential expression
Flow: Convert to ranked Series → gseapy GSEA (GO + KEGG + MSigDB) →
      Filter by FDR < 0.25 → Report NES and lead genes
Use: When you have fold-changes or other ranking metric

Pattern 3: BixBench Enrichment Question

Input: Specific question about enrichment (e.g., "What is the adjusted p-val for neutrophil activation?")
Flow: Parse question for gene list and library → Run gseapy with exact library →
      Find specific term → Report exact p-value and adjusted p-value
Use: When answering targeted questions about specific terms

Pattern 4: Multi-Organism Enrichment

Input: Gene list from mouse experiment
Flow: Use organism='mouse' for gseapy → organism=10090 for PANTHER/STRING →
      projection=True for Reactome human pathway mapping
Use: When working with non-human organisms

See: references/common_patterns.md for more examples

Troubleshooting

"No significant enrichment found":

• Verify gene symbols are valid (STRING_map_identifiers)
• Try different library versions (2021 vs 2023 vs 2025)
• Try relaxing significance cutoff or use GSEA instead

"Gene not found" errors:

• Check ID type and convert using MyGene_batch_query
• Remove version suffixes from Ensembl IDs (ENSG00000141510.16 → ENSG00000141510)

"STRING returns all categories":

• This is expected; filter by d['category'] == 'Process' after receiving results

See: references/troubleshooting.md for complete guide

Tool Reference

Primary Enrichment Tools

Cross-Validation Tools

ID Conversion Tools

See: references/tool_parameters.md for complete parameter documentation

Detailed Documentation

All detailed examples, code blocks, and advanced topics have been moved to references/:

• references/ora_workflow.md - Complete ORA examples with all databases
• references/gsea_workflow.md - Complete GSEA workflow with ranked lists
• references/enrichr_guide.md - All 225+ Enrichr libraries and usage
• references/cross_validation.md - Multi-source validation strategies
• references/id_conversion.md - Gene ID disambiguation and conversion
• references/tool_parameters.md - Complete tool parameter reference
• references/organism_support.md - Organism-specific configurations
• references/common_patterns.md - Detailed use case examples
• references/troubleshooting.md - Complete troubleshooting guide
• references/multiple_testing.md - Correction methods (BH, Bonferroni, BY)
• references/report_template.md - Standard report format

Helper scripts:

• scripts/format_enrichment_output.py - Format results for reports
• scripts/compare_enrichment_sources.py - Cross-validation analysis
• scripts/filter_by_gene_set_size.py - Filter terms by size

Resources

For network-level analysis: tooluniverse-network-pharmacology For disease characterization: tooluniverse-multiomic-disease-characterization For spatial omics: tooluniverse-spatial-omics-analysis For protein interactions: tooluniverse-protein-interactions

gseapy documentation: https://gseapy.readthedocs.io/ PANTHER API: http://pantherdb.org/services/oai/pantherdb/ STRING API: https://string-db.org/cgi/help?sessionId=&subpage=api Reactome Analysis: https://reactome.org/AnalysisService/