README.md

In ComBatFamQC: Comprehensive Batch Effect Diagnostics and Harmonization

ComBatFamQC

The ComBatFamQC package is a powerful tool designed to streamline interactive batch effect diagnostics, harmonization, and post-harmonization downstream analysis. This package is specifically tailored to provide both interactive qualitative visualization and statistical testing for batch effects diagnostics, as well as to offer various easily-used built-in harmonization techniques to facilitate a better harmonization process.

Additionally, the package provides life span age trends of brain structures and residual datasets, eliminating specific covariates' effects to better conduct post-harmonization downstream analysis. For the final delivery, the package offers interactive visualizations through R Shiny for batch effect diagnostics and age trend visualization. For users who wish to save a copy of the diagnostic report, the package also includes an option to generate a Quarto report (if Quarto is installed). Furthermore, it integrates the harmonization process and can provide a harmonized dataset, a fitted ComBat model, a residual dataset, a fitted regression model, and more.

To make the harmonization process more accessible to users from diverse backgrounds, two unified command-line interfaces have been developed for different stages of the processing pipeline (located in the inst folder):

• CombatQC_CLI.R: Batch Effect Diagnostics & Harmonization Stage
  • Offers interactive diagnostics for batch effects
  • Export the batch effect diagnosis report
  • Performs data harmonization to adjust for batch effects
• post_CLI.R: Post-Harmonization Stage
  • Visualizes age trends across brain structures over the lifespan
  • Generates a residual dataset with unwanted covariate effects removed

Note: Detailed information and tutorials can be found: https://zheng206.github.io/ComBatQC-Web/

Diagram

Package Features

The ComBatFamQC package offers the following five key functionalities:

1. Interactive Batch Effect Diagnostics & Harmonization

2. Batch Effect Diagnostics: ComBatFamQC provides two types of batch effect diagnostics methods for both individual batch effects and global batch effects: 1) Qualitative Visualization and 2) Statistical Testing. It simplifies the process of performing statistical analyses to detect potential batch effects and provides all relevant statistical test results for batch effect visualization and evaluation.

3. Harmonization: ComBatFamQC also provides four types of commonly used harmonization techniques, integrated through the ComBatFamily package developed by Dr. Andrew Chen, for users to consider. The four harmonization techniques include:

   • Original ComBat (Johnson et al., 2007)
   • Longitudinal ComBat (Beer et al., 2020)
   • ComBat-GAM (Pomponio et al., 2020)
   • CovBat (Chen et al., 2021)

4. Interactive Visualization through R Shiny: The ComBatFamQC package comes with an interactive visualization tool built on R Shiny, providing an intuitive user interface to explore and evaluate batch effects, as well as conduct interactive harmonization if needed. The output is organized into multiple tabs, which includes:

   • Data Overview: Complete data overview and exploratory analysis
   • Summary: Sample Size and Covariate Distribution
   • Residual Plot: Additive and Multiplicative Batch Effect
   • Diagnosis of Global Batch Effect: PCA, T-SNE and MDMR
   • Diagnosis of Individual Batch Effect:
     • Statistical Tests for Additive Batch Effect: Kenward-Roger (liner mix model), ANOVA, Kruskal-Wallis
     • Statistical Tests for Multiplicative Batch Effect: Fligner-Killeen, Levene's Test, Bartlett's Test
   • Harmonization Interactive Harmonization if needed

5. Post-Harmonization Downstream Analysis

6. Age Trajectory \ Generate age trend of each brain structure (ROI), adjusting sex and ICV. Customized centiles are enabled as well.

   • Age Trend Plots
   • Age Trend Table

7. Residual Generation \ Generate residual data set, removing specific covariates' effetcs.

Installation

if (!require("devtools", quietly = TRUE)) {
    install.packages("devtools")   
}

library(devtools)

devtools::install_github("Zheng206/ComBatFamQC", build_vignettes = TRUE)

Tutorial

vignette("ComBatQC")
vignette("Post-Harmonization")

ComBatFamQC documentation built on April 4, 2025, 12:24 a.m.