COMPUTE, DON'T DESCRIBE

LOOK UP DON'T GUESS: adjusted p-values, gene set overlap counts, and which genes from your input list drive each enriched term. Always retrieve the inputGenes field from enrichment results — do not assume which genes caused a term to be significant. When a term looks surprising, verify by checking which genes overlap.

When to Use This Skill

Apply when users:

• Ask about gene enrichment analysis (GO, KEGG, Reactome, etc.)
• Have a gene list from differential expression, clustering, or any experiment
• Want to know which biological processes, molecular functions, or cellular components are enriched
• Need KEGG or Reactome pathway enrichment analysis
• Ask about GSEA (Gene Set Enrichment Analysis) with ranked gene lists
• Want over-representation analysis (ORA) with Fisher's exact test
• Need multiple testing correction (Benjamini-Hochberg, Bonferroni)
• Ask about enrichGO, gseapy, clusterProfiler-style analyses

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

1. Create report file immediately; populate progressively.
2. Convert IDs: Use MyGene_batch_query (fields: symbol,entrezgene,ensembl.gene) then STRING_map_identifiers to get canonical symbols. Auto-detect: ENSG* = Ensembl, numeric = Entrez, else = Symbol.
3. Primary enrichment: gseapy.enrichr() for ORA (gene list), gseapy.prerank() for GSEA (ranked list with scores). Use background=background_genes — do not leave as genome-wide default if your experiment has a specific expressed gene set.
4. Cross-validate: Run PANTHER_enrichment (param: comma-sep gene_list, annotation_dataset='GO:0008150') and ReactomeAnalysis_pathway_enrichment (param: space-sep identifiers). STRING_functional_enrichment returns all categories — filter by category field.
5. Report: Include raw p-value, adjusted p-value, overlap ratio, and inputGenes for each significant term. Note consensus terms (significant in 2+ sources).

See: references/ for complete code examples (ora_workflow.md, gsea_workflow.md, cross_validation.md)

Evidence Grading

Supported Organisms

Core organisms: human (9606), mouse (10090), rat (10116), fly (7227), worm (6239), yeast (4932). gseapy has full human/mouse support; other organisms are limited — use PANTHER or STRING for non-human enrichment.

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/