Fit the baseline ComBat-ref correction — combat

combat_ref() exposes the original ComBat-ref reference-batch correction algorithm through an R-facing package API. The input matrix must contain genes in rows and samples in columns. The current implementation preserves the legacy negative-binomial fitting, dispersion estimation, automatic minimum-dispersion reference-batch selection, filtering, zero handling, and negative-binomial quantile mapping.

Usage

combat_ref(
  counts,
  batch,
  group = NULL,
  reference_batch = NULL,
  lib_size = NULL,
  verbose = interactive(),
  keep_model = FALSE
)

Arguments

counts: Numeric count matrix-like object with genes in rows and samples in columns. Row and column names are required and preserved.
batch: Batch vector aligned exactly with columns of counts.
group: Optional biological-group vector aligned exactly with columns of counts.
reference_batch: Optional reference batch. NULL reproduces the legacy automatic minimum-dispersion selection.
lib_size: Optional positive finite library sizes aligned with samples. NULL reproduces the legacy edgeR library-size behavior.
verbose: Logical. If TRUE, print concise progress messages with cli. Defaults to interactive().
keep_model: Logical. If TRUE, include selected intermediate model quantities under the model field. Large edgeR fit objects are not returned.

Value

A combatref_result object. Use $adjusted_counts to access the corrected count matrix.

Details

This function does not implement quasi-likelihood correction.

Examples

counts <- matrix(
  c(10, 12, 30, 33, 8, 9, 28, 31,
    4, 5, 14, 16, 3, 4, 15, 17,
    50, 55, 120, 130, 48, 52, 125, 135,
    1, 2, 4, 5, 1, 2, 5, 6),
  nrow = 4,
  byrow = TRUE,
  dimnames = list(paste0("gene", 1:4), paste0("sample", 1:8))
)
batch <- rep(c("batch_A", "batch_B"), each = 2, times = 2)
group <- rep(c("ctrl", "treated"), each = 4)

fit <- combat_ref(counts, batch = batch, group = group)
adjusted_counts <- fit$adjusted_counts