| 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
- 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.
- Resolve
--method: ORA, GSEA, or auto. Hard-fails at :370 for unknown methods.
- Try R clusterProfiler first; on import failure, fall back to GSEApy (
:379).
- On GSEApy failure, fall back to the built-in hypergeometric implementation (
:436 ORA path, :479 GSEA path).
- 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 hintreferences/methodology.md — ORA vs GSEA, three-tier engine fallback, ranking-metric selectionreferences/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)
