bulkrna-de

name	bulkrna-de
description	Differential expression analysis via PyDESeq2 with Welch's t-test fallback — volcano plots, MA plots, p-value diagnostics.
version	0.3.0
author	OmicsClaw
license	MIT
tags	["bulkrna","differential-expression","DESeq2","volcano","MA-plot","fold-change"]
requires	["numpy","pandas","matplotlib","scipy"]
metadata	{"omicsclaw":{"domain":"bulkrna","emoji":"🔬","trigger_keywords":["differential expression","DE analysis","DESeq2","volcano plot","fold change","DEGs","bulk DE"],"allowed_extra_flags":["--control-prefix","--lfc-cutoff","--method","--padj-cutoff","--treat-prefix"],"legacy_aliases":["bulk-de"],"saves_h5ad":false}}

Bulk RNA-seq Differential Expression

Differential expression analysis for bulk RNA-seq count matrices. Primary engine is PyDESeq2 (Python implementation of the DESeq2 model); falls back to Welch's t-test with log2FC and Benjamini-Hochberg FDR correction when PyDESeq2 is not installed.

Core Capabilities

• Full DESeq2-style negative binomial GLM via PyDESeq2, or Welch's t-test fallback
• Produces columns consistent with DESeq2 output: gene, baseMean, log2FoldChange, lfcSE, stat, pvalue, padj
• Volcano plot with top gene labels and MA plot with threshold lines
• P-value distribution histogram for diagnostic assessment
• Automatic sample group detection from column name prefixes
• Benjamini-Hochberg FDR correction with proper NaN handling

CLI Reference

python omicsclaw.py run bulkrna-de --demo
python omicsclaw.py run bulkrna-de --input <counts.csv> --output <dir>
python bulkrna_de.py --input counts.csv --output results/
python bulkrna_de.py --demo --output /tmp/de_demo
python bulkrna_de.py --input counts.csv --output results/ --method ttest --ctrl-prefix ctrl --treat-prefix treat
python bulkrna_de.py --input counts.csv --output results/ --padj-cutoff 0.01 --lfc-cutoff 1.5

Why This Exists

• Without it: Researchers must install R and DESeq2, write design formulas, handle normalization, shrinkage, and multiple testing correction manually, then create separate visualization scripts.
• With it: A single Python command runs the full DE pipeline — from raw counts to filtered DEG tables, volcano plots, MA plots, and p-value diagnostic histograms.
• Why OmicsClaw: Provides a pure-Python DE workflow via PyDESeq2 with graceful fallback to t-test, integrated into the OmicsClaw reporting framework.

Algorithm / Methodology

PyDESeq2 (Primary)

1. Construct DeseqDataSet from count matrix and sample metadata
2. Estimate size factors (median-of-ratios normalization)
3. Estimate dispersions (Cox-Reid profile-adjusted maximum likelihood)
4. Fit negative binomial GLM and perform Wald test
5. Apply Benjamini-Hochberg FDR correction

Welch's t-test (Fallback)

1. Compute log2 fold change: log2(mean_treat + 1) - log2(mean_ctrl + 1)
2. Estimate standard error via delta method approximation
3. Welch's t-test (unequal variance) per gene
4. Benjamini-Hochberg FDR with NaN-safe handling

Key Parameters