Repository files navigation

• Overview
• Repo Contents
• System Requirements
• Installation Guide
• Demo
• Results and figure reproduction
• License
• Issues
• Citation

Batch effects, undesirable sources of variance across multiple experiments, present significant challenges for scientific and clinical discoveries. Specifically, batch effects can (i) produce spurious signals and/or (ii) obscure genuine signals, contributing to the ongoing reproducibility crisis. Typically, batch effects are modeled as classical, rather than causal, statistical effects. This model choice renders the methods unable to differentiate between biological or experimental sources of variability, leading to unnecessary false positive and negative effect detections and over-confidence. We formalize batch effects as causal effects to address these concerns, and augment existing batch effect detection and correction approaches with causal machinery. Simulations illustrate that our causal approaches mitigate spurious findings and reveal otherwise obscured signals as compared to non-causal approaches. Applying our causal methods to a large neuroimaging mega-study reveals instances where prior art confidently asserts that the data do not support the presence of batch effects when we expect to detect them. On the other hand, our causal methods correctly discern that there exists irreducible confounding in the data, so it is unclear whether differences are due to batches or not. This work therefore provides a framework for understanding the potential capabilities and limitations of analysis of multi-site data using causal machinery.

• R:R package code.
• docs: usage of thecausalBatch package on many real and simulated data examples for scientific articles.
• man: package manual for help in R session.
• tests:R unit tests written using thetestthat package.
• vignettes:R vignettes for R session html help pages.

ThecausalBatch package requires only a standard computer with enough RAM to support the operations defined by a user. For minimal performance, this will be a computer with about 2 GB of RAM. For optimal performance, we recommend a computer with the following specs:

RAM: 16+ GB
CPU: 4+ cores, 3+ GHz/core

The runtimes below are generated using a computer with the recommended specs (16 GB RAM, 4 cores@3 GHz) and internet of speed 100 Mbps.

The package development version is tested onMac operating systems. The developmental version of the package has been tested on the following systems:

Linux:Mac OSX: Ventura 13.1Windows:

Before setting up thecausalBatch package, users should haveR version 4.2.0 or higher, and several packages set up from CRAN.

The stable release of the package is available on CRAN, and can be installed fromR as:

install.packages('causalBatch')

Users should install the following packages prior to installinglolR, from anR terminal:

install.packages(c('cdcsis', 'MatchIt', 'nnet', 'dplyr', 'tidyverse', 'magrittr'))if (!require("BiocManager", quietly = TRUE))    install.packages("BiocManager")BiocManager::install(version = "3.18")BiocManager::install("sva")

which will install in about 1 minute on a machine with the recommended specs.

ThecausalBatch package functions with all packages in their latest versions as they appear onCRAN on January 22, 2024. The versions of software are, specifically:

sva=3.50.0cdcsis=2.0.3tidyverse=2.0.0dplyr=1.1.4MatchIt=4.5.5nnet=7.3.19magrittr=2.0.3

If you are having an issue that you believe to be tied to software versioning issues, please drop us anIssue.

From anR session, type:

require(devtools)# install causalBatch with the vignettesinstall_github('neurodata/causal_batch', build_vignettes=TRUE, force=TRUE)require(causalBatch)# view one of the basic vignettesvignette("causal_simulations", package="causalBatch")

The package should take approximately 40 seconds to install with vignettes on a recommended computer.

For interactive demos of the functions, please check out the vignettes built into the package. They can be accessed as follows:

require(causalBatch)vignette("causal_simulations", package="causalBatch")vignette("causal_balancing", package="causalBatch")vignette("causal_cdcorr", package="causalBatch")vignette("causal_ccombat", package="causalBatch")

SeeBatch Effects Paper for instructions to reproduce figures from Bridgeford et al. (2025).

For usage of the package and associated manuscript, please cite according to the enclosedcitation.bib.