bulkrna-enrichment

name	bulkrna-enrichment
description	Load when running pathway / GO term enrichment on a bulk RNA-seq DE result list. Skip if the input is single-cell (use sc-enrichment), spatial (use spatial-enrichment), or for metabolite pathways (use metabolomics-pathway-enrichment).
version	0.3.0
author	OmicsClaw
license	MIT
tags	["bulkrna","enrichment","GSEA","ORA","GO","KEGG","Reactome","pathway"]

bulkrna-enrichment

When to use

Run after bulkrna-de to ask "which biological pathways are enriched in the DEG list?". Two modes: ORA (over-representation analysis on a significance-filtered gene list) and pre-ranked GSEA (full ranked list, no threshold needed). Backed by GSEApy with R clusterProfiler and a built-in hypergeometric implementation as fallbacks.

Inputs & Outputs

Input	Format	Required
DE results	.csv (gene + log2FoldChange + padj cols)	yes (or --demo)
Custom gene set	--gene-set-file GMT/JSON	optional

Output	Path	Notes
Enrichment table	tables/enrichment_results.csv	per-term padj, NES, leading-edge genes
Top terms barplot	figures/enrichment_barplot.png	top N by padj
Dotplot	figures/enrichment_dotplot.png	size = gene count, colour = padj
Report	report.md + result.json	always

Flow

1. Load DE table; pick a ranking metric (log2FoldChange, signed -log10 padj, etc.). Falls back to log2FoldChange with a warning at bulkrna_enrichment.py:67 if the heuristic finds no preferred metric.
2. Resolve --method: ORA, GSEA, or auto. Hard-fails at :370 for unknown methods.
3. Try R clusterProfiler first; on import failure, fall back to GSEApy (:379).
4. On GSEApy failure, fall back to the built-in hypergeometric implementation (:436 ORA path, :479 GSEA path).
5. Render barplot + dotplot; emit enrichment table + report.

Gotchas

• Three-tier silent fallback chain. R clusterProfiler → GSEApy → built-in. Each fall is logger.warning-only (bulkrna_enrichment.py:379, :436, :479); the chosen backend is in result.json["method_used"]. Built-in is the least feature-rich (no permutation-based GSEA p-values) — verify which engine actually ran before claiming a particular method.
• Ranking-metric auto-pick is heuristic and not surfaced in result.json. :67 warns when it falls back to log2FoldChange, but if your DE table uses a non-standard column name (e.g. lfc instead of log2FoldChange), the heuristic may pick the wrong column without complaint. The chosen metric is logged at INFO (:450) but does NOT make it into the summary dict (which carries only n_input_genes, n_significant, method_used, n_terms_tested, n_enriched_terms, enrichment_df). Grep the run's stderr for "Using gseapy for pre-ranked GSEA (metric: ...)" to confirm.
• --padj-cutoff and --lfc-cutoff only apply to ORA. Pre-ranked GSEA uses the full ranked list and ignores both flags — passing them on a GSEA run silently does nothing. This is correct GSEA behaviour, but easy to mistake for a bug.
• No DEGs above thresholds → silent empty plots. :516 and :525 warn ("No enrichment results to plot" / "No terms with valid padj") and skip plotting; the run still exits 0 with empty figures and an empty tables/enrichment_results.csv. Loosen thresholds or pre-filter the input if your DE list is sparse.

Key CLI

python omicsclaw.py run bulkrna-enrichment --demo
python omicsclaw.py run bulkrna-enrichment \
  --input de_results.csv --output results/ --method ora
python omicsclaw.py run bulkrna-enrichment \
  --input de_results.csv --output results/ --method gsea \
  --gene-set-file hallmark.gmt

See also

• references/parameters.md — every CLI flag and tuning hint
• references/methodology.md — ORA vs GSEA, three-tier engine fallback, ranking-metric selection
• references/output_contract.md — exact output directory layout
• Adjacent skills: bulkrna-de (upstream — DE table input), bulkrna-ppi-network (parallel: same DEG list → STRING network), sc-enrichment / spatial-enrichment (single-cell / spatial siblings), metabolomics-pathway-enrichment (metabolite-side sibling)