/bulkrna-de

name: bulkrna-de
description: Load when comparing gene expression between two conditions in bulk RNA-seq count data. Skip
  when the data is single-cell (use sc-de); spatial (use spatial-de); you need exon-level alternative
  splicing (use bulkrna-splicing).
trigger: differential expression, DE analysis, DESeq2, volcano plot, fold change, DEGs, bulk DE
tags:
- bulkrna
- differential-expression
- DESeq2
- volcano
- MA-plot
- fold-change

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`