https://github.com/zheng206/combatfamqc
Streamline interactive batch effect diagnostics, harmonization, and post-harmonization downstream analysis to greatly simplify the data harmonization process and improve transparency and reproducibility.
https://github.com/zheng206/combatfamqc
diagnostic-tool harmonization rshinyapp
Last synced: 4 months ago
JSON representation
Streamline interactive batch effect diagnostics, harmonization, and post-harmonization downstream analysis to greatly simplify the data harmonization process and improve transparency and reproducibility.
- Host: GitHub
- URL: https://github.com/zheng206/combatfamqc
- Owner: Zheng206
- License: other
- Created: 2024-10-27T23:31:23.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-02-14T23:23:51.000Z (4 months ago)
- Last Synced: 2026-02-15T06:47:07.483Z (4 months ago)
- Topics: diagnostic-tool, harmonization, rshinyapp
- Language: R
- Homepage:
- Size: 256 MB
- Stars: 5
- Watchers: 2
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: NEWS.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Codemeta: codemeta.json
Awesome Lists containing this project
README
# ComBatFamQC
[](https://github.com/Zheng206/ComBatFamQC/actions/workflows/R-CMD-check.yaml) [](https://app.codecov.io/gh/Zheng206/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**
- **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.
- **Harmonization**: ComBatFamQC also provides four types of commonly used harmonization techniques, integrated through the [ComBatFamily](https://github.com/andy1764/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)
- **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
2. **Post-Harmonization Downstream Analysis**
- **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**
- **Residual Generation** \
Generate residual data set, removing specific covariates' effetcs.
## Installation
### CRAN
```{r}
install.packages("ComBatFamQC")
```
### GitHub
The GitHub build is one release ahead of CRAN and includes out-of-sample harmonization for CovBat.
```{r}
if (!require("devtools", quietly = TRUE)) {
install.packages("devtools")
}
library(devtools)
devtools::install_github("Zheng206/ComBatFamQC", build_vignettes = TRUE)
```
## Tutorial
```{r}
vignette("ComBatQC")
vignette("Post-Harmonization")
```
## Command-line Interface
```{bash}
RSCRIPT=${RSCRIPT:-$(command -v Rscript)}
combatqc_cli="$($RSCRIPT -e 'cat(system.file("combatQC_CLI.R", package="ComBatFamQC"))')"
post_cli="$($RSCRIPT -e 'cat(system.file("post_CLI.R", package="ComBatFamQC"))')"
Rscript $combatqc_cli -h
Rscript $post_cli -h
```