bulkrna-batch-correction

name	bulkrna-batch-correction
description	Batch effect correction for multi-cohort bulk RNA-seq data using ComBat, with PCA-based visualization before and after correction.
version	0.3.0
author	OmicsClaw
license	MIT
tags	["bulkrna","batch-correction","ComBat","harmonization","batch-effect"]
requires	["numpy","pandas","matplotlib","scipy"]
metadata	{"omicsclaw":{"domain":"bulkrna","emoji":"🔧","trigger_keywords":["batch correction","ComBat","batch effect","harmonize","multi-cohort","batch removal"],"allowed_extra_flags":["--batch-info","--mode"],"legacy_aliases":["bulk-combat"],"saves_h5ad":false}}

Bulk RNA-seq Batch Effect Correction

Remove batch effects from multi-cohort bulk RNA-seq expression matrices using the ComBat algorithm (parametric and non-parametric modes), with PCA-based visualization and quantitative assessment.

Core Capabilities

• Parametric and non-parametric ComBat batch correction
• Built-in empirical Bayes implementation (no external R dependency)
• PCA visualization before and after correction with batch coloring
• Quantitative batch-effect metrics: silhouette score, kBET-like metric
• Export corrected expression matrices in CSV format
• Automatic batch detection from sample naming conventions

Why This Exists

• Without it: Users must install R, load the sva package, manually create model matrices, run ComBat(), and export corrected data back to Python — a multi-step cross-language workflow.
• With it: A single Python command performs batch correction on CSV expression matrices and generates before/after PCA plots with quantitative batch-mixing metrics.
• Why OmicsClaw: Pure Python ComBat implementation integrated into the OmicsClaw reporting framework, with automated batch-effect assessment.

Algorithm / Methodology

ComBat (Johnson et al., 2007)

1. Standardize expression data by gene (subtract mean, divide by std)
2. Estimate batch-specific location and scale parameters
3. Apply empirical Bayes shrinkage to batch parameter estimates
4. Adjust expression values to remove batch effects while preserving biological variation

Parametric vs Non-parametric

• Parametric (default): Assumes normal distribution for batch effects; faster
• Non-parametric: Uses kernel density estimation; more robust for non-normal batch effects

PCA Assessment

• PCA on log2(CPM+1) transformed data, colored by batch label
• Silhouette score: measures how well batches cluster (lower = better mixing after correction)

Input Formats

Format	Extension	Description
Expression matrix	.csv	Genes as rows, samples as columns; first column is gene identifiers
Batch metadata	.csv	Two columns: and (or auto-detected from sample names)