Skip to content
Research Agent Skillsby Kalaris Labs
Install
Life Sciencesv1.1AdaptedMIT

pathway-enrichment

Run pathway and gene-set enrichment analysis on gene lists or ranked gene data, then interpret the results. Use whenever the user has a set of genes (differentially expressed genes from PyDESeq2/Scanpy, CRISPR-screen hits, cluster marker genes, proteomics hits) and wants to know which biological pathways, GO terms, or gene sets are over-represented or enriched. Covers over-representation analysis (ORA / Enrichr / Fisher / hypergeometric), ranked Gene Set Enrichment Analysis (GSEA / preranked), single-sample scoring (ssGSEA/GSVA), and functional profiling via gseapy, g:Profiler, Enrichr libraries, MSigDB, GO, KEGG, Reactome, and WikiPathways — plus gene-ID mapping, choosing the right background universe, multiple-testing correction, redundancy reduction, dotplots/enrichment maps, and publication-ready tables. Use this for "pathway analysis", "enrichment analysis", "GO enrichment", "KEGG/Reactome pathways", "GSEA", "over-representation", "functional annotation", or "what pathways are my genes in".

Install this skill

Works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, and 70+ other harnesses.

skills.sh CLI (Recommended)
npx skills add KalarisLabs/research-agent-skills --skill pathway-enrichment
uvx (Python tool runner)
uvx research-agent-skills install pathway-enrichment

Documentation & Instructions

Pathway Enrichment

Overview

Enrichment analysis answers "what biology is over-represented in my genes?" It is the standard last step after differential expression, a screen, or clustering. There are two core methods, and choosing correctly is the single most important decision:

  • ORA (over-representation analysis) — take a thresholded gene list (e.g., padj < 0.05) and test which gene sets it overlaps more than chance, using Fisher's exact / hypergeometric tests. Tools: Enrichr, g:Profiler.
  • GSEA (gene set enrichment analysis) — take the whole ranked list of genes (no threshold) and test whether each gene set is concentrated toward the top or bottom. Preranked GSEA uses a per-gene score (e.g., the DESeq2 stat). Better when effects are broad and subtle.

This skill orchestrates these analyses, the gene-set databases behind them, and the interpretation pitfalls that make results wrong or unpublishable.

When to Use This Skill

Use this skill when the user wants to:

  • Find enriched GO terms / KEGG / Reactome / WikiPathways / MSigDB Hallmark sets in a gene list.
  • Run GSEA / preranked GSEA on DESeq2, edgeR, limma, or Scanpy rank_genes_groups output.
  • Score pathway activity per sample/cell (ssGSEA, GSVA).
  • Interpret, deduplicate, and visualize enrichment results, or build a publication table/figure.
  • Decide between ORA and GSEA, pick gene-set libraries, choose a background, or fix gene-ID problems.

For quick one-off Enrichr lookups the gget skill (gget enrichr) is lighter weight; for raw pathway/interaction APIs (Reactome, KEGG, STRING) see the database-lookup skill. Use this skill for full, defensible enrichment workflows.

Choosing the Right Method

Situation Method Tool / entry point
You have a discrete hit list (DE genes, screen hits, cluster markers) ORA gp.enrichr(...) or g:Profiler
You have a full ranked list (every tested gene + a score) Preranked GSEA gp.prerank(...)
You have an expression matrix + class labels GSEA gp.gsea(...)
You want a pathway score per sample/cell ssGSEA / GSVA gp.ssgsea(...), gp.gsva(...)
You need a custom background or 500+ organisms ORA with custom domain g:Profiler (domain_scope='custom')
You want TF / signaling activity (PROGENy, DoRothEA) activity inference see references/databases-and-gene-sets.md (decoupler)

When in doubt: a thresholded list → ORA; a ranked table with scores → GSEA. Never threshold a list and then feed it to GSEA — that discards the ranking GSEA depends on.

Setup

uv pip install gseapy gprofiler-official
# gseapy pulls pandas, numpy, scipy, matplotlib. Network access is needed for
# Enrichr, g:Profiler, and MSigDB downloads. For fully offline ORA, use a local
# GMT file with gp.enrich() (see references/gseapy.md).

Verify and list available gene-set libraries (names change over time — never hardcode blindly):

import gseapy as gp
names = gp.get_library_name(organism="human")   # 200+ Enrichr libraries
print([n for n in names if "Reactome" in n or "KEGG" in n or "Hallmark" in n])

Quick Start

ORA on a hit list (gseapy + Enrichr)

import gseapy as gp

# Enrichr libraries expect HGNC gene SYMBOLS (human: UPPERCASE). Map IDs first if needed.
genes = [g.strip() for g in open("deg_symbols.txt") if g.strip()]

enr = gp.enrichr(
    gene_list=genes,
    gene_sets=["MSigDB_Hallmark_2020", "GO_Biological_Process_2023",
               "KEGG_2021_Human", "Reactome_2022"],
    organism="human",
    outdir=None,            # in-memory; set a path to also write tables/plots
)
res = enr.results
sig = res[res["Adjusted P-value"] < 0.05].sort_values("Adjusted P-value")
print(sig[["Gene_set", "Term", "Overlap", "Adjusted P-value", "Combined Score", "Genes"]].head(20))

Preranked GSEA from DESeq2 results

import gseapy as gp
import pandas as pd

res = pd.read_csv("deseq2_results.csv", index_col=0)   # index = gene symbols
# Rank by the test statistic (sign = direction, magnitude = evidence). This is
# more stable than ranking by log2FoldChange, which is noisy for low-count genes.
rnk = res["stat"].dropna().sort_values(ascending=False)
rnk.index = rnk.index.str.upper()
rnk = rnk[~rnk.index.duplicated(keep="first")]

pre = gp.prerank(
    rnk=rnk,
    gene_sets=["MSigDB_Hallmark_2020", "GO_Biological_Process_2023"],
    min_size=15, max_size=500,        # drop tiny/huge sets (noisy or generic)
    permutation_num=1000, seed=123,   # seed = reproducible p-values
    threads=4, outdir=None,
)
out = pre.res2d.sort_values("FDR q-val")
print(out[["Term", "ES", "NES", "NOM p-val", "FDR q-val", "Lead_genes"]].head(20))

If you have no stat column, build the rank from sign(log2FoldChange) * -log10(pvalue).

Core Workflow

For a defensible analysis, work through these steps. The middle steps (ID type, background) are where results most often silently go wrong.

Step 1 — Pin down inputs and pick the method

Confirm: which genes, what organism, is there a per-gene score (→ GSEA) or just a list (→ ORA), and what comparison they represent (direction matters for interpretation).

Step 2 — Get gene IDs into the right namespace

Enrichr/MSigDB libraries are keyed by gene symbols (human UPPERCASE, mouse Title-case). If you have Ensembl/Entrez IDs, convert first. See references/databases-and-gene-sets.md for gp.Biomart, g:Profiler g:Convert, and mygene. A silent ID mismatch is the #1 cause of "nothing is significant".

Step 3 — Choose gene-set libraries to match the question

Hallmark (broad themes) → GO:BP (mechanism) → KEGG/Reactome/WikiPathways (curated pathways) → C7 (immune), etc. Don't run 50 libraries; pick 2–4 that fit the biology. Catalog and selection guidance: references/databases-and-gene-sets.md.

Step 4 — Set the background universe (ORA only)

The background must be the genes that could have been detected in your assay (e.g., all expressed/tested genes), not the whole genome. The wrong background inflates significance. Enrichr uses a fixed background; when background matters, use g:Profiler with domain_scope='custom' + your background, or gp.enrich() with an explicit background. Rationale in references/interpretation.md.

Step 5 — Run the analysis

Use the Quick Start patterns or the bundled scripts/run_enrichment.py. For GSEA always set a seed and report permutation_num.

Step 6 — Filter on adjusted p-values

Use Adjusted P-value (ORA, Benjamini–Hochberg) or FDR q-val (GSEA), not raw p-values. Typical cutoff 0.05; also check the overlap/gene count so a "hit" isn't 1 gene out of a 2000-gene set.

Step 7 — Visualize

Dotplots, bar plots, enrichment maps, and GSEA running-score plots are built into gseapy (gp.dotplot, gp.barplot, gp.enrichment_map, gp.gseaplot). See references/gseapy.md.

Step 8 — Reduce redundancy and interpret

GO especially returns many near-duplicate terms. Collapse with an enrichment map (term–term similarity), leading-edge overlap, or parent terms, and report representative terms. Interpretation framework and a publication-table format are in references/interpretation.md.

Helper Script

scripts/run_enrichment.py runs ORA or GSEA end-to-end and writes a results table plus a dotplot, handling the boilerplate (symbol cleanup, dedup, NA removal, rank construction from a DESeq2 table, per-library FDR filtering).

# ORA from a hit list (one gene symbol per line)
python scripts/run_enrichment.py ora \
  --genes deg_symbols.txt \
  --libraries MSigDB_Hallmark_2020 GO_Biological_Process_2023 KEGG_2021_Human \
  --organism human --outdir results/

# Preranked GSEA from a DESeq2 results CSV (auto-builds the rank from `stat`)
python scripts/run_enrichment.py gsea \
  --deseq2 deseq2_results.csv \
  --libraries MSigDB_Hallmark_2020 GO_Biological_Process_2023 \
  --organism human --outdir results/ --seed 123

# Preranked GSEA from an explicit 2-column rank file (gene,score)
python scripts/run_enrichment.py gsea --rnk ranked_genes.csv --outdir results/

Run python scripts/run_enrichment.py --help for all options (background file, FDR cutoff, min/max set size, permutations).

Common Pitfalls

These cause most wrong or irreproducible results:

  1. Gene-ID / organism mismatch — symbols vs Ensembl, human vs mouse casing. Map IDs and set organism correctly, or matches silently drop to ~zero.
  2. Wrong background (ORA) — using the whole genome instead of the tested/expressed gene set inflates p-values. Set a custom background when it matters.
  3. Thresholding before GSEA — GSEA needs the full ranked list; only ORA uses a cut list.
  4. Ranking GSEA by log2FoldChange alone — unstable for low-count genes; prefer stat or sign(LFC) * -log10(p).
  5. Multiple-testing across libraries — FDR is computed within a library; running many libraries multiplies tests. Report per-library FDR and stay conservative.
  6. Redundant GO terms — don't report 40 variants of the same term; collapse and show representatives.
  7. Significance ≠ relevance — check the overlap count and gene-set size; tiny sets reach significance trivially.
  8. List too short/long for ORA — <10 genes is underpowered; >2000 loses specificity (consider GSEA instead).
  9. No reproducibility metadata — Enrichr/GO libraries are versioned and drift over time. Record library names+date and set a GSEA seed.

Integration with Other Skills

  • Upstream (where genes come from): pydeseq2 (DE genes + stat for GSEA), scanpy (rank_genes_groups markers / scores), depmap/pytdc (screen hits), proteomics skills (pyopenms, matchms).
  • Databases / IDs: database-lookup (Reactome, KEGG, STRING, Gene Ontology APIs), gget (gget enrichr quick path, gget info for ID mapping), bioservices.
  • Downstream: scientific-visualization (custom figures), networkx (enrichment-map graphs), scientific-writing / literature-review (interpret and cite), statistical-analysis (multiple-testing details).

Reference Files

Read the relevant file when you need depth:

  • references/gseapy.md — full gseapy API: enrichr, offline enrich, prerank, gsea, ssgsea, gsva, Msigdb, Biomart, get_library_name/read_gmt, every plot, result-column meanings, GMT/offline usage, and troubleshooting (rate limits, empty results).
  • references/databases-and-gene-sets.md — GO, KEGG, Reactome, WikiPathways, MSigDB collections, Enrichr library naming, g:Profiler sources, organism handling, gene-ID conversion, library selection by question, and pointers to Reactome/STRING APIs and decoupler activity inference.
  • references/interpretation.md — ORA vs GSEA statistics, background-universe choice, multiple-testing methods (BH vs g:SCS vs Bonferroni), leading-edge genes, redundancy reduction, effect vs significance, a publication-table template, and reproducibility checklist.

Resources

Related skills

  • bulk-rnaseq: End-to-end bulk RNA-seq orchestrator — takes raw FASTQ reads through QC and trimming (FastQC, fastp/Trim Galore), alignment and quantificat…
  • bioservices: Unified Python interface to 40+ bioinformatics services.
  • gget: Queries 20+ bioinformatics databases and analysis services through the gget CLI and Python package, covering Ensembl gene search, info and…

Trigger Prompts & Evaluation Corpus

These evaluation prompts test that the agent correctly selects pathway-enrichment for relevant tasks and leaves it out for near misses.

Should trigger (3)

  • should trigger

    “what pathways are enriched in my 214 upregulated genes? mouse, treated vs control”

    expects Chooses ORA on the thresholded list, notes mouse gene symbols (Title-case) and sets organism correctly. Asks for or uses a tested/expressed-gene background, runs gseapy Enrichr or g:Profiler with 2-4 fitting libraries, and filters by adjusted p-value while checking overlap counts.

  • should trigger

    “I ran PyDESeq2 on my patient-derived organoid RNA-seq (res_df.csv, index = Ensembl IDs, columns baseMean, log2FoldChange, stat, pvalue, padj). I want GSEA against MSigDB Hallmark and Reactome, and gp.prerank gives me 'Warning: no genes overlap' with an empty result table. How do I fix this and get a figure for the paper?”

    expects Diagnoses the Ensembl-ID versus gene-symbol mismatch and converts IDs (Biomart, mygene or g:Convert), then removes NA and duplicate genes. Builds the rank from the full table using `stat` (not a padj-thresholded list), runs gp.prerank with a seed and a stated permutation count, reports FDR q-values per library, and produces a dotplot or a publication table with redundancy reduction.

  • should trigger

    “I have a CRISPR knockout screen with about 18,000 genes scored by MAGeCK. The top 150 hits are essential genes. Can you help me work out what biological processes these hits point to and whether they're just general housekeeping machinery?”

    expects Recognizes this as a functional-enrichment goal on screen hits. Uses ORA on the hit list with the screened genes as the custom background, or preranked GSEA on the full MAGeCK scores. Collapses redundant GO terms and cautions that core-essential genes will enrich for ribosome/proteasome/spliceosome terms. Interprets results with gene counts and set sizes in mind.

Near misses (2)

  • near miss

    “I have raw FASTQ files from 12 bulk RNA-seq samples. Can you take me from QC and trimming through alignment and quantification to a counts matrix, then run differential expression?”

    expects Should use the bulk-rnaseq orchestrator skill for the end-to-end pipeline (FastQC, fastp, STAR/Salmon, featureCounts, pydeseq2). Enrichment is only a possible later hand-off, not the main task.

  • near miss

    “Look up the Ensembl ID, chromosome location and description for the gene BRCA2, and fetch its sequence.”

    expects Should use the gget skill for Ensembl search, info and sequence lookups. No enrichment analysis is needed.