K-Way matching

Description

A function for performing k-way matching using the matchIt package. Looks for samples which have corresponding matches across all other treatment levels.

Usage

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

Arguments

Value

a list, containing the following:

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

• Reference the reference batch.

Details

For more details see the help vignette: vignette("causal_balancing", 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).

Examples

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

Vector Matching

Description

A function for implementing the vector matching procedure, a pre-processing step for causal conditional distance correlation. Uses propensity scores to strategically include/exclude samples from subsequent inference, based on whether (or not) there are samples with similar propensity scores across all treatment levels (conceptually, a k-way "propensity trimming"). It is imperative that this function is used in conjunction with domain expertise to ensure that the covariates are not colliders, and that the system satisfies the strong ignorability condiiton to derive causal conclusions.

Usage

cb.align.vm_trim(
  Ts,
  Xs,
  prop.form = NULL,
  retain.ratio = 0.05,
  ddx = FALSE,
  reference = NULL
)

Arguments

Value

a [m] vector containing the indices of samples retained after vector matching.

Details

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

Author(s)

Eric W. Bridgeford

References

Michael J. Lopez, et al. "Estimation of Causal Effects with Multiple Treatments" Statistical Science (2017). ran

Examples

library(causalBatch)
sim <- cb.sims.sim_linear(a=-1, n=100, err=1/8, unbalancedness=3)
cb.align.vm_trim(sim$Ts, sim$Xs)

Augmented Inverse Probability Weighting Conditional ComBat

Description

A function for implementing the AIPW conditional ComBat (AIPW 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 could be argued to satisfy the ignorability condition) to derive causal conclusions. See citation for more details as to the conditions under which conclusions derived are causal.

Usage

cb.correct.aipw_cComBat(
  Ys,
  Ts,
  Xs,
  aipw.form,
  covar.out.form = NULL,
  retain.ratio = 0.05
)

Arguments

Details

Note: This function is experimental, and has not been tested on real data. It has only been tested with simulated data with binary (0 or 1) exposures.

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.

• Model the fit batch effect correction model.

• Corrected.Ids the ids to which batch effect correction was applied.

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).

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=2)
cb.correct.aipw_cComBat(sim$Ys, sim$Ts, data.frame(Covar=sim$Xs), "Covar")

Fit AIPW ComBat model for batch effect correction

Description

This function applies an Augmented Inverse Probability Weighting (AIPW) ComBat model for batch effect correction to new data.

Usage

cb.correct.apply_aipw_cComBat(Ys, Ts, Xs, Model)

Arguments

Details

Note: This function is experimental, and has not been tested on real data. It has only been tested with simulated data with binary (0 or 1) exposures.

Value

an [n, d] matrix, the batch-effect corrected data.

Examples

library(causalBatch)
sim <- cb.sims.sim_linear(a=-1, n=200, err=1/8, unbalancedness=3)
# fit batch effect correction for first 100 samples
cb.fit <- cb.correct.matching_cComBat(sim$Ys[1:100,,drop=FALSE], sim$Ts[1:100], 
                                  data.frame(Covar=sim$Xs[1:100,,drop=FALSE]), "Covar")
# apply to all samples
cor.dat <- cb.correct.apply_cComBat(sim$Ys, sim$Ts, data.frame(Covar=sim$Xs), cb.fit$Model)

Adjust for batch effects using an empirical Bayes framework

Description

ComBat allows users to adjust for batch effects in datasets where the batch covariate is known, using methodology described in Johnson et al. 2007. It uses either parametric or non-parametric empirical Bayes frameworks for adjusting data for batch effects. Users are returned an expression matrix that has been corrected for batch effects. The input data are assumed to be cleaned and normalized before batch effect removal.

Usage

cb.correct.apply_cComBat(Ys, Ts, Xs, Model)

Arguments

Details

Note: this code is adapted directly from the ComBat algorithm featured in the 'sva' package.

Value

an [n, d] matrix, the batch-effect corrected data.

Examples

library(causalBatch)
sim <- cb.sims.sim_linear(a=-1, n=200, err=1/8, unbalancedness=3)
# fit batch effect correction for first 100 samples
cb.fit <- cb.correct.matching_cComBat(sim$Ys[1:100,,drop=FALSE], sim$Ts[1:100], 
                                  data.frame(Covar=sim$Xs[1:100,,drop=FALSE]), "Covar")
# apply to all samples
cor.dat <- cb.correct.apply_cComBat(sim$Ys, sim$Ts, data.frame(Covar=sim$Xs), cb.fit$Model)

Matching Conditional ComBat

Description

A function for implementing the matching conditional ComBat (matching 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 could be argued to satisfy the ignorability condition) to derive causal conclusions. See citation for more details as to the conditions under which conclusions derived are causal.

Usage

cb.correct.matching_cComBat(
  Ys,
  Ts,
  Xs,
  match.form,
  covar.out.form = NULL,
  prop.form = NULL,
  reference = NULL,
  match.args = list(method = "nearest", exact = NULL, replace = FALSE, caliper = 0.1),
  retain.ratio = 0.05,
  apply.oos = FALSE
)

Arguments

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.

• Model the fit batch effect correction model. See ComBat for details.

• InSample.Ids the ids which were used to fit the batch effect correction model.

• Corrected.Ids the ids to which batch effect correction was applied. Differs from InSample.Ids if apply.oos is TRUE.

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).

Leek JT, Johnson WE, Parker HS, Fertig EJ, Jaffe AE, Zhang Y, Storey JD, Torres LC (2024). sva: Surrogate Variable Analysis. R package version 3.52.0.

Examples

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

Causal Conditional Distance Correlation

Description

A function for implementing the causal conditional distance correlation (causal cDCorr) algorithm. This algorithm allows users to identify whether a treatment causes changes in an outcome, given assorted covariates/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.detect.caus_cdcorr(
  Ys,
  Ts,
  Xs,
  prop.form = NULL,
  R = 1000,
  dist.method = "euclidean",
  distance = FALSE,
  seed = 1,
  num.threads = 1,
  retain.ratio = 0.05,
  ddx = FALSE
)

Arguments

Value

a list, containing the following:

• Test The outcome of the statistical test, from cdcov.test.

• Retained.Ids The sample indices retained after vertex matching, which correspond to the samples for which statistical inference is performed.

Details

For more details see the help vignette: vignette("causal_cdcorr", 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).

Eric W. Bridgeford, et al. "Learning sources of variability from high-dimensional observational studies" arXiv (2023).

Xueqin Wang, et al. "Conditional Distance Correlation" American Statistical Association (2015).

Examples

library(causalBatch)
sim <- cb.sims.sim_linear(a=-1, n=100, err=1/8, unbalancedness=3)
cb.detect.caus_cdcorr(sim$Ys, sim$Ts, sim$Xs)

Impulse Simulation

Description

Impulse Simulation

Usage

cb.sims.sim_impulse(
  n = 100,
  pi = 0.5,
  eff_sz = 1,
  alpha = 2,
  unbalancedness = 1,
  err = 1/2,
  null = FALSE,
  a = -0.5,
  b = 1/2,
  c = 4,
  nbreaks = 200
)

Arguments

Value

a list, containing the following:

Details

A sigmoidal relationship between the covariate and the outcome. The first dimension of the outcome is:

Y_i = c \times \phi(X_i, \mu = a, \sigma = b) - \text{eff\_sz} \times T_i + \frac{1}{2} \epsilon_i

where \phi(x, \mu, \sigma) is the probability density function for the normal distribution with mean \mu and standard deviation \sigma.

where the batch/group labels are:

T_i \overset{iid}{\sim} Bern(\pi)

The beta coefficient for the covariate sampling is:

\beta = \alpha \times \text{unbalancedness}

The covariate values for the first batch are:

X_i | T_i = 0 \overset{ind}{\sim} 2 Beta(\alpha, \beta) - 1

and the covariate values for the second batch are:

X_i | T_i = 1 \overset{ind}{\sim} 2 Beta(\beta, \alpha) - 1

Note that X_i | T_i = 0 \overset{D}{=} - X_i | T_i = 1, or that the covariates are symmetric about the origin in distribution.

Finally, the error terms are:

\epsilon_i \overset{iid}{\sim} Norm(0, \text{err}^2)

For more details see the help vignette: vignette("causal_simulations", 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).

Examples

library(causalBatch)
sim = cb.sims.sim_impulse()

Impulse Simulation with Asymmetric Covariates

Description

Impulse Simulation with Asymmetric Covariates

Usage

cb.sims.sim_impulse_asycov(
  n = 100,
  pi = 0.5,
  eff_sz = 1,
  alpha = 2,
  unbalancedness = 1,
  null = FALSE,
  a = -0.5,
  b = 1/2,
  c = 4,
  err = 1/2,
  nbreaks = 200
)

Arguments

Value

a list, containing the following:

Details

A sigmoidal relationship between the covariate and the outcome. The first dimension of the outcome is:

Y_i = c \times \phi(X_i, \mu = a, \sigma = b) - \text{eff\_sz} \times T_i + \frac{1}{2} \epsilon_i

where \phi(x, \mu, \sigma) is the probability density function for the normal distribution with mean \mu and standard deviation \sigma.

where the batch/group labels are:

T_i \overset{iid}{\sim} Bern(\pi)

The beta coefficient for the covariate sampling is:

\beta = \alpha \times \text{unbalancedness}

The covariate values for the first batch are asymmetric, in that for the first batch:

X_i | T_i = 0 \overset{ind}{\sim} 2 Beta(\alpha, \alpha) - 1

and the covariate values for the second batch are:

X_i | T_i = 1 \overset{ind}{\sim} 2 Beta(\beta, \alpha) - 1

Finally, the error terms are:

\epsilon_i \overset{iid}{\sim} Norm(0, \text{err}^2)

For more details see the help vignette: vignette("causal_simulations", 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).

Examples

library(causalBatch)
sim = cb.sims.sim_impulse_asycov()

Linear Simulation

Description

Linear Simulation

Usage

cb.sims.sim_linear(
  n = 100,
  pi = 0.5,
  eff_sz = 1,
  alpha = 2,
  unbalancedness = 1,
  err = 1/2,
  null = FALSE,
  a = -2,
  b = -1,
  nbreaks = 200
)

Arguments

Value

a list, containing the following:

Details

A linear relationship between the covariate and the outcome. The first dimension of the outcome is:

Y_i = a\times (X_i + b) - \text{eff\_sz} \times T_i + \frac{1}{2} \epsilon_i

where the batch/group labels are:

T_i \overset{iid}{\sim} Bern(\pi)

The beta coefficient for the covariate sampling is:

\beta = \alpha \times \text{unbalancedness}

The covariate values for the first batch are:

X_i | T_i = 0 \overset{ind}{\sim} 2 Beta(\alpha, \beta) - 1

and the covariate values for the second batch are:

X_i | T_i = 1 \overset{ind}{\sim} 2 Beta(\beta, \alpha) - 1

Finally, the error terms are:

\epsilon_i \overset{iid}{\sim} Norm(0, \text{err}^2)

For more details see the help vignette: vignette("causal_simulations", 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).

Examples

library(causalBatch)
sim = cb.sims.sim_linear()

Sigmoidal Simulation

Description

Sigmoidal Simulation

Usage

cb.sims.sim_sigmoid(
  n = 100,
  pi = 0.5,
  eff_sz = 1,
  alpha = 2,
  unbalancedness = 1,
  null = FALSE,
  a = -4,
  b = 8,
  err = 1/2,
  nbreaks = 200
)

Arguments

Value

a list, containing the following:

Details

A sigmoidal relationship between the covariate and the outcome. The first dimension of the outcome is:

Y_i = a\times \text{sigmoid}(b \times X_i) - a - \text{eff\_sz} \times T_i + \frac{1}{2} \epsilon_i

where the batch/group labels are:

T_i \overset{iid}{\sim} Bern(\pi)

The beta coefficient for the covariate sampling is:

\beta = \alpha \times \text{unbalancedness}

The covariate values for the first batch are:

X_i | T_i = 0 \overset{ind}{\sim} 2 Beta(\alpha, \beta) - 1

and the covariate values for the second batch are:

X_i | T_i = 1 \overset{ind}{\sim} 2 Beta(\beta, \alpha) - 1

Finally, the error terms are:

\epsilon_i \overset{iid}{\sim} Norm(0, \text{err}^2)

For more details see the help vignette: vignette("causal_simulations", 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).

Examples

library(causalBatch)
sim = cb.sims.sim_sigmoid()