Fit ComBat-refQL reference-batch adjustment — combat_ref

Fits model-based reference-counterfactual means with edgeR v4, moderates QL batch contrasts with continuous evidence-adaptive EB, and adjusts non-reference counts by deterministic negative-binomial mid-P transport.

Usage

combat_ref_ql(
  counts,
  batch,
  group = NULL,
  covariates = NULL,
  reference = NULL,
  fractional_counts = c("round", "error"),
  chunk_size = 5000L,
  verbose = TRUE
)

Arguments

counts: Numeric raw-count matrix with genes in rows and samples in columns.
batch: Sample batch vector, optionally named for automatic reordering.
group: Optional biological group vector to preserve. Exact batch/group aliasing is an error; strong association is reported as a warning.
covariates: Optional sample-by-covariate data frame or matrix. Constant columns are recorded and omitted; redundant or aliased terms are errors.
reference: Optional reference batch. When NULL, the minimum-dispersion batch is selected from biologically adjusted within-batch QL fits.
fractional_counts: Round with an audit record, or reject fractional values.
chunk_size: Positive number of genes transported per chunk.
verbose: Logical. If TRUE, print concise progress, outcome, and runtime messages. Warnings and errors are not suppressed when FALSE.

Value

A validated CombatRefQLFit object with adjusted counts and structured input, batch-quality, and correction-confidence diagnostics.

Examples

set.seed(1)
batch <- factor(rep(c("reference", "study"), each = 6))
group <- factor(rep(c("control", "treated"), 6))
counts <- matrix(rnbinom(1200, mu = 40, size = 8), nrow = 100)
rownames(counts) <- paste0("gene", seq_len(nrow(counts)))
colnames(counts) <- paste0("sample", seq_len(ncol(counts)))
counts[, batch == "study"] <- counts[, batch == "study"] * 2

fit <- combat_ref_ql(counts, batch, group, reference = "reference")
#> 
#> ── ComBat-refQL ────────────────────────────────────────────────────────────────
#> ✔ Prepared 100 genes × 12 samples
#> ✔ Reference: reference (explicit)
#> ✔ Model fitted
#> ✔ Adjusted 100 | Unchanged 0 | Failed 0
#> 
#> ℹ Runtime: 0.1 s
fit
#> 
#> ── ComBat-refQL fit ────────────────────────────────────────────────────────────
#> 
#> ── Data ──
#> 
#> 100 genes × 12 samples
#> 2 batches
#> Biological groups 2
#> 
#> ── Reference ──
#> 
#> reference (explicit)
#> 
#> ── Outcome ──
#> 
#> Adjusted 100 (100.0%)
#> Unchanged 0 (0.0%)
#> Failed 0
#> 
#> ── Confidence ──
#> 
#> high 100
#> moderate 0
#> low 0
#> failed 0
#> 
#> ── Runtime ──
#> 
#> 0.1 s
summary(fit)
#> 
#> ── ComBat-refQL summary ────────────────────────────────────────────────────────
#> 
#> ── Design ──
#> 
#> Samples 12
#> Coefficients 3; rank 3
#> Residual df 9
#> Condition number 3.54
#> Biological groups 2
#> Maximum batch association 0.000
#> 
#> ── Reference ──
#> 
#> Selected reference (explicit)
#> reference 6 samples; score not scored
#> study 6 samples; score not scored
#> 
#> ── Batch adjustment ──
#> 
#> study dispersion x0.944 (estimated)
#> study median adaptive weight 0.319
#> 
#> ── Gene outcomes ──
#> 
#> Adjusted 100 (100.0%)
#> Unchanged 0 (0.0%)
#> Failed 0 (0.0%)
#> 
#> ── Correction confidence ──
#> 
#> high 100
#> moderate 0
#> low 0
#> failed 0
#> 
#> ── Runtime ──
#> 
#> 0.1 s
corrected <- fit@counts