cb.correct.caus_cComBat {causalBatch}

Causal Conditional ComBat

Description

A function for implementing the causal conditional ComBat (causal cComBat) algorithm. This algorithm allows users to remove batch effects (in each dimension), while adjusting for known confounding variables. It is imperative that this function is used in conjunction with domain expertise (e.g., to ensure that the covariates are not colliders, and that the system satisfies the strong ignorability condiiton) to derive causal conclusions. See citation for more details as to the conditions under which conclusions derived are causal.

Usage

cb.correct.caus_cComBat(
  Ys,
  Ts,
  Xs,
  match.form,
  reference = NULL,
  match.args = list(method = "nearest", exact = NULL, replace = FALSE, caliper = 0.1),
  retain.ratio = 0.05
)

Arguments

Ys

an [n, d] matrix, for the outcome variables with n samples in d dimensions.

Ts

[n] the labels of the samples, with K < n levels, as a factor variable.

Xs

[n, r] the r covariates/confounding variables, for each of the n samples, as a data frame with named columns.

match.form

A formula of columns from Xs, to be passed directly to matchit for subsequent matching. See formula argument from matchit for details.

reference

the name of the reference/control batch, against which to match. Defaults to NULL, which treats the reference batch as the smallest batch.

match.args

A named list arguments for the matchit function, to be used to specify specific matching strategies, where the list names are arguments and the corresponding values the value to be passed to matchit. Defaults to inexact nearest-neighbor caliper (width 0.1) matching without replacement.

retain.ratio

If the number of samples retained is less than retain.ratio*n, throws a warning. Defaults to 0.05.

Value

a list, containing the following:

• Ys.corrected an [m, d] matrix, for the m retained samples in d dimensions, after correction.

• Ts [m] the labels of the m retained samples, with K < n levels.

• Xs the r covariates/confounding variables for each of the m retained samples.

• Retained.Ids a [m] vector consisting of the sample ids of the n original samples that were retained after matching.

Details

For more details see the help vignette: vignette("causal_ccombat", package = "causalBatch")

Author(s)

Eric W. Bridgeford

References

Eric W. Bridgeford, et al. "A Causal Perspective for Batch Effects: When is no answer better than a wrong answer?" Biorxiv (2024).

Daniel E. Ho, et al. "MatchIt: Nonparametric Preprocessing for Parametric Causal Inference" JSS (2011).

W Evan Johnson, et al. "Adjusting batch effects in microarray expression data using empirical Bayes methods" Biostatistics (2007).

Examples

library(causalBatch)
sim <- cb.sims.sim_linear(a=-1, n=100, err=1/8, unbalancedness=3)
cb.correct.caus_cComBat(sim$Ys, sim$Ts, data.frame(Covar=sim$Xs), "Covar")