tiangzlab/omicsclaw/bulkrna-de

Bulk differential expression

Purpose

Compare two prefix-selected groups in a raw count matrix. The default backend is R DESeq2; --method ttest selects Welch tests. The R bridge applies apeglm or ashr shrinkage when installed, otherwise raw estimates. This is not a single-cell or splicing analysis.

Inputs & Outputs

CLI input is a gene-first CSV. The library takes a gene-indexed DataFrame. Both require nonnegative integer counts. Outputs include tables/de_results.csv, tables/de_significant.csv, four diagnostic figures, report.md and result.json; DESeq2 intermediate tables are backend-dependent.

API

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

differential_expression(counts, *, method='deseq2', control_prefix='ctrl', treat_prefix='treat', padj_cutoff=0.05, lfc_cutoff=1.0, min_count=10)

Compare treatment against control without changing the count matrix.

:param counts: Gene-indexed DataFrame of nonnegative integer raw counts. :param method: CLI default deseq2 (R); ttest selects Welch tests. :param control_prefix: CLI default ctrl selects control columns. :param treat_prefix: CLI default treat selects treatment columns. :param padj_cutoff: CLI default 0.05; significance requires a smaller adjusted p. :param lfc_cutoff: CLI default 1.0; absolute log2 effect must exceed it. :param min_count: Legacy filtering default 10 for total counts across selected samples. :returns: DE DataFrame with effect estimates, p values and run diagnostics in attrs. :raises ValueError: Counts, method, groups or thresholds are invalid. :raises ImportError: R DESeq2 is missing; use install_skill_deps for DESeq2.

run_info(result, *, keep=True)

Read filtering, group and executed-method diagnostics.

:param result: DataFrame returned by differential_expression. :param keep: Default True; False removes diagnostics from attrs. :returns: Diagnostic dictionary, empty after removal.

volcano_figure(result)

Plot reported log2 effects and adjusted significance.

:param result: DE DataFrame with log2FoldChange and padj. :returns: A matplotlib Figure without saving files. :raises KeyError: Required columns are absent.

<!-- api:end -->

Key CLI

python skills/bulkrna/bulkrna-de/bulkrna_de.py --demo --output /tmp/bulkrna-de
python skills/bulkrna/bulkrna-de/bulkrna_de.py --input counts.csv --output results/de --method ttest

Gotchas

• run_info(result)['method_used'] identifies the executed method. Missing DESeq2 raises an installation hint; a failed R fit can fall back to Welch with a warning and fallback_reason.
• run_info(result)['lfc_note'] distinguishes Welch effects from the R bridge's package-dependent shrinkage. Welch tests are not a substitute for biological replication.
• run_info(result)['n_tested'] counts genes after the default total-count filter of 10. Unmatched sample prefixes do not enter the comparison.

Dependencies

numpy, pandas, scipy, matplotlib, DESeq2