/bulkrna-batch-correction

name: bulkrna-batch-correction
description: Load when correcting batch effects in bulk expression using R sva ComBat or the legacy Python parametric approximation. Skip single-batch inputs; use sc-batch-integration for single-cell data or spatial-integrate for spatial slices.
trigger: batch correction, ComBat, batch effect, harmonize, multi-cohort, batch removal
tags:
- bulkrna
- batch-correction
- ComBat
- harmonization
- batch-effect

bulkrna-batch-correction

When to use

Load when correcting batch effects in bulk expression using R sva ComBat or the legacy Python parametric approximation. Skip single-batch inputs; use sc-batch-integration for single-cell data or spatial-integrate for spatial slices.

Use from a step

from skills._sdk.notebook import load_skill, write_output
library = load_skill("bulkrna-batch-correction")
result = library.correct(data, batches=batches, backend="python")
write_output(result, "tables/result.csv")
write_output(library.pca_figure(result, batches=batches), "figures/result.png")

Read expression and metadata with `read_input` before calling the library. `examples/example_step.py` constructs a small synthetic dataset and checks its results through the step runner and fresh-kernel replay.

API

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

`correct(data: pd.DataFrame, *, batches: pd.DataFrame, mode: str='parametric', backend: str='auto') -> pd.DataFrame`

Return corrected expression, leaving the input unchanged.

:param data: Finite nonnegative expression, features by samples; correction uses this scale directly. :param batches: Metadata with sample and batch columns, and optional biological condition. :param mode: CLI default parametric, or non-parametric (requires R sva). :param backend: auto prefers R as the CLI did; r requires R, python uses the legacy parametric approximation. :returns: Corrected DataFrame with run_info diagnostics; values can be negative. :raises ValueError: Data, metadata, mode or backend is invalid. :raises ImportError: An explicitly requested R backend is unavailable. :raises RuntimeError: R fails and the requested mode/design has no Python fallback.

`run_info(data: pd.DataFrame, *, keep: bool=True) -> dict`

Return backend diagnostics and before/after batch metrics.

:param data: Result of correct. :param keep: Keep diagnostics by default; the CLI passes False. :returns: Diagnostics dictionary. :raises ValueError: No correction diagnostics are attached.

`pca_figure(data: pd.DataFrame, *, batches: pd.DataFrame)`

Plot PCA after signed log2(1+abs(x)), accepting negative corrections.

:param data: Original or corrected feature-by-sample expression. :param batches: Metadata containing sample and batch. :returns: Matplotlib Figure. :raises ValueError: Samples lack batch metadata.

<!-- api:end -->

Methods and parameters

The function library returns DataFrames and Figures. The CLI loads the same library and owns reports and file writes. R runs in a temporary directory using Matrix Market, feature/sample identifiers and metadata. No R intermediate is a permanent CLI output.

Gotchas

• `correct(backend="auto")` prefers R sva and warns/records any Python fallback. `backend="r"` requires R. The Python method is the legacy parametric approximation, not numerical equivalence to sva.
• `correct` requires at least two batches and two samples per batch. Missing labels and single-batch inputs raise before any backend runs.
• `correct` applies ComBat directly to the supplied scale, not to an automatic log transform. Outputs may be negative and are not integer counts for DESeq2.
• `correct(mode="non-parametric")` and condition covariates require R; Python cannot silently substitute a different design or mode.
• `run_info()["summary"]` contains before/after PCA silhouette metrics using signed log2(1+abs(x)), so negative corrections remain finite. Inspect condition-by-batch balance before removing effects.

Inputs and outputs

Expression CSV with feature identifiers in the first column; metadata CSV with sample and batch, plus optional condition.

CLI outputs:

• `tables/corrected_expression.csv`
• `tables/batch_metrics.csv`
• `figures/pca_before_correction.png`
• `figures/pca_after_correction.png`
• `figures/batch_assessment.png`
• `report.md`, `result.json`
• `reproducibility/commands.sh`

CLI

python skills/bulkrna/bulkrna-batch-correction/bulkrna_batch_correction.py --demo --output /tmp/bulkrna_batch_correction_demo

Run the script with `--help` for real-input arguments.

See also

• `references/parameters.md`
• `references/methodology.md`
• `references/output_contract.md`

Dependencies

`matplotlib`, `numpy`, `pandas`, `scipy`, `sva`, `Matrix`