cb.detect.caus_cdcorr {causalBatch}

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,
  R = 1000,
  dist.method = "euclidean",
  distance = FALSE,
  seed = 1,
  num.threads = 1,
  retain.ratio = 0.05,
  ddx = FALSE
)

Arguments

Ys

Either:

• [n, d] matrix the outcome variables with n samples in d dimensions. In this case, distance should be FALSE.

• [n, n] dist object a distance object for the n samples. In this case, distance should be TRUE.

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.

R

the number of repetitions for permutation testing. Defaults to 1000.

dist.method

the method used for computing distance matrices. Defaults to "euclidean". Other options can be identified by seeing the appropriate documention for the method argument for the dist function.

distance

a boolean for whether (or not) Ys are already distance matrices. Defaults to FALSE, which will use dist.method parameter to compute an [n, n] pairwise distance matrix for Ys.

seed

a random seed to set. Defaults to 1.

num.threads

The number of threads for parallel processing (if desired). Defaults to 1.

retain.ratio

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

ddx

whether to show additional diagnosis messages. Defaults to FALSE. Can help with debugging if unexpected results are obtained.

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)