tiangzlab/omicsclaw/bulkrna-enrichment

Bulk pathway enrichment

Purpose

Test differential-expression results against explicit pathway gene sets. ORA uses the union of those sets as its background; GSEA ranks all input genes. Gene identifiers must use the same namespace. R adapters are not implemented.

Inputs & Outputs

CLI input is a CSV with gene, log2FoldChange, pvalue, padj; --gene-set-file is a JSON mapping from pathway names to gene lists. The library accepts the table and mapping directly. CLI writes tables/enrichment_results.csv, tables/enrichment_significant.csv, report/result files and method-dependent figures.

API

<!-- api:begin generated from _api.py; regenerate with run.py api <skill dir> --write -->

enrich(de_results, *, gene_sets, method='ora', padj_cutoff=0.05, lfc_cutoff=1.0, random_state=42)

Test pathway enrichment without choosing a reference database.

:param de_results: DataFrame with gene, log2FoldChange, pvalue and padj. :param gene_sets: Nonempty mapping from pathway names to unique gene lists. :param method: CLI default ora; gsea runs GSEApy prerank. :param padj_cutoff: CLI significance threshold, default 0.05. :param lfc_cutoff: Strict absolute fold-change threshold, default 1.0. :param random_state: Local permutation seed, legacy default 42. :returns: Enrichment DataFrame with execution diagnostics in attrs. :raises ValueError: Missing reference, invalid values or unsupported method.

run_info(result, *, keep=True)

Read tested terms, pathway universe and requested/executed methods.

:param result: DataFrame returned by enrich. :param keep: Default True; False removes diagnostic attrs. :returns: Diagnostic dictionary; empty after removal.

enrichment_figure(result)

Plot pathway adjusted significance without saving it.

:param result: Enrichment DataFrame with term and padj columns. :returns: matplotlib Figure. :raises KeyError: Required columns are missing.

<!-- api:end -->

Key CLI

python skills/bulkrna/bulkrna-enrichment/bulkrna_enrichment.py --demo --output /tmp/bulkrna-enrichment
python skills/bulkrna/bulkrna-enrichment/bulkrna_enrichment.py --input de.csv --gene-set-file pathways.json --output results/enrichment --method ora

Gotchas

• run_info(result)['background_genes'] is the pathway-union background, not all measured genes. Choose reference sets accordingly.
• run_info(result)['executed_method'] and fallback_reason disclose fallback calculations. The built-in GSEA fallback is a mean-rank permutation test, not GSEA; fallback emits a warning.
• tables/enrichment_results.csv may be empty when no terms overlap. Demo pathways are available only with --demo; real input requires an explicit reference.
• run_info(result)['method_used'] distinguishes GSEApy and built-in calculations. The legacy ora_r and gsea_r flags now reject an unimplemented backend rather than silently changing it.

Dependencies

numpy, pandas, scipy, matplotlib, gseapy