batch-effect-correction-reference-based
Summary
Apply concordance-based batch effect correction to log-transformed metabolomics data by designating a reference batch and disabling group-level stratification. This skill removes batch-driven signal drift while preserving biological group differences in large-scale metabolite matrices.
When to use
When you have log-transformed metabolite abundance data from multiple batches (e.g., mass spectrometry runs or sample processing cohorts), a single batch can be nominated as a stable reference standard, and you want to correct all other batches to match the reference's statistical properties without stratifying correction within biological groups.
When NOT to use
- Data is not log-transformed; CordBat expects log-scale input to model multiplicative batch effects.
- No clear reference batch exists or reference batch quality is questionable; design should nominate a batch known to have minimal technical variability.
- Correction should preserve or exploit group-level batch heterogeneity; set grouping=FALSE assumes batch effects are consistent across groups, which may not hold if group×batch interactions are strong.
Inputs
- log2-transformed metabolite abundance matrix (numeric; samples × metabolites)
- batch assignment vector (character or factor; length = number of samples)
- group assignment vector (character or factor; length = number of samples)
- reference batch label (character; must match one unique value in batch vector)
Outputs
- corrected log2-scale metabolite matrix (numeric; samples × metabolites; from fit$X.cor)
- fitted CordBat object (contains convergence details and model parameters)
How to apply
Prepare a log2-transformed metabolite matrix (rows = samples, columns = metabolites), a batch assignment vector identifying which batch each sample belongs to (with one batch labeled 'Ref'), and a group assignment vector. Call CordBat() with the log-transformed matrix, batch vector, group vector, ref.batch='Ref', and grouping=FALSE. CordBat uses concordance-based normalization to align batch statistics to the reference batch without iterative loops. Extract the corrected log2-scale matrix from the fit object (fit$X.cor). Back-transform by exponentiating (2^corrected_mat) for downstream visualization or statistical testing. The reference batch acts as the anchor; all other batches' systematic offsets are measured and removed relative to it.
Related tools
- CordBat (Performs concordance-based batch effect correction on log-transformed metabolite matrices with reference batch specification and optional group stratification.) — https://github.com/BorchLab/CordBat
- R (Runtime environment for executing CordBat function calls and data transformations.)
- ggplot2 (Visualization of PCA results before and after batch correction to assess removal of batch effects.)
- dplyr (Data wrangling and preparation of batch and group assignment vectors from metadata.)
Examples
fit <- CordBat(X = as.matrix(log2(cordbat_example[metabolite_cols])), batch = batch_vec, group = group_vec, ref.batch = "Ref", grouping = FALSE, print.detail = FALSE); corrected_mat <- fit$X.cor
Evaluation signals
- PCA plot on back-transformed corrected data (2^corrected_mat) shows samples from different batches overlapping in principal component space, whereas uncorrected PCA showed clear batch-driven clustering.
- Corrected matrix retains original dimensions and range; no NaN, Inf, or unexpected values introduced.
- fit object contains convergence status and model parameters; print.detail=FALSE still allows inspection of fit$X.cor.
- Biological group signal is preserved: mean log2-abundance differences between groups remain statistically significant post-correction.
- Reference batch samples remain numerically unchanged or minimally perturbed in corrected matrix (ref.batch acts as anchor).
Limitations
- Assumes batch effects are multiplicative and uniform across metabolites; if batch effects are additive or highly metabolite-specific, correction may be incomplete.
- Requires designation of a high-quality reference batch; poor reference choice propagates bias to all corrected batches.
- grouping=FALSE means correction does not account for group×batch interactions; if such interactions are present, residual group-confounded batch signal may persist.
- CordBat is optimized for large-scale metabolomics (25+ metabolites per sample in the example); performance or stability on very small datasets not characterized.
Evidence
- [other] CordBat() accepts a log-transformed metabolite matrix (X_mat), batch assignment vector (batch_vec), group assignment vector (group_vec), a reference batch label ('Ref'), and a grouping parameter set to FALSE, producing a fitted object from which the corrected matrix is extracted via fit$X.cor.: "CordBat() accepts a log-transformed metabolite matrix (X_mat), batch assignment vector (batch_vec), group assignment vector (group_vec), a reference batch label ("Ref"), and a grouping parameter set"
- [methods] fit <- CordBat(
X = X_mat,
batch = batch_vec,
group = group_vec,
ref.batch = "Ref",
grouping = FALSE,
print.detail = FALSE
): "fit <- CordBat(
X = X_mat,
batch = batch_vec,
group = group_vec,
ref.batch = "Ref",
grouping = FALSE,
print.detail = FALSE
)"
- [methods] Log-transform metabolite measurements and extract the corrected log2-scale matrix from fit$X.cor.: "X_mat <- as.matrix(log2(cordbat_example[met_cols]))"
- [readme] This is a R package implementation of the Concordance-Based Batch Effect Correction for Large-Scale Metabolomics (CordBat).: "This is a R package implementation of the Concordance-Based Batch Effect Correction for Large-Scale Metabolomics (CordBat)."
- [readme] There is no methodologic change within the CordBat package from the original publication, however, substantial changes have been made to improve computational efficiency and limit iterative loops.: "There is no methodologic change within the CordBat package from the original publication, however, substantial changes have been made to improve computational efficiency and limit iterative loops."
1---2name: batch-effect-correction-reference-based3description: Use when when you have log-transformed metabolite abundance data from multiple batches (e.4license: CC-BY-4.05---67# batch-effect-correction-reference-based89## Summary1011Apply concordance-based batch effect correction to log-transformed metabolomics data by designating a reference batch and disabling group-level stratification. This skill removes batch-driven signal drift while preserving biological group differences in large-scale metabolite matrices.1213## When to use1415When you have log-transformed metabolite abundance data from multiple batches (e.g., mass spectrometry runs or sample processing cohorts), a single batch can be nominated as a stable reference standard, and you want to correct all other batches to match the reference's statistical properties without stratifying correction within biological groups.1617## When NOT to use1819- Data is not log-transformed; CordBat expects log-scale input to model multiplicative batch effects.20- No clear reference batch exists or reference batch quality is questionable; design should nominate a batch known to have minimal technical variability.21- Correction should preserve or exploit group-level batch heterogeneity; set grouping=FALSE assumes batch effects are consistent across groups, which may not hold if group×batch interactions are strong.2223## Inputs2425- log2-transformed metabolite abundance matrix (numeric; samples × metabolites)26- batch assignment vector (character or factor; length = number of samples)27- group assignment vector (character or factor; length = number of samples)28- reference batch label (character; must match one unique value in batch vector)2930## Outputs3132- corrected log2-scale metabolite matrix (numeric; samples × metabolites; from fit$X.cor)33- fitted CordBat object (contains convergence details and model parameters)3435## How to apply3637Prepare a log2-transformed metabolite matrix (rows = samples, columns = metabolites), a batch assignment vector identifying which batch each sample belongs to (with one batch labeled 'Ref'), and a group assignment vector. Call CordBat() with the log-transformed matrix, batch vector, group vector, ref.batch='Ref', and grouping=FALSE. CordBat uses concordance-based normalization to align batch statistics to the reference batch without iterative loops. Extract the corrected log2-scale matrix from the fit object (fit$X.cor). Back-transform by exponentiating (2^corrected_mat) for downstream visualization or statistical testing. The reference batch acts as the anchor; all other batches' systematic offsets are measured and removed relative to it.3839## Related tools4041- **CordBat** (Performs concordance-based batch effect correction on log-transformed metabolite matrices with reference batch specification and optional group stratification.) — https://github.com/BorchLab/CordBat42- **R** (Runtime environment for executing CordBat function calls and data transformations.)43- **ggplot2** (Visualization of PCA results before and after batch correction to assess removal of batch effects.)44- **dplyr** (Data wrangling and preparation of batch and group assignment vectors from metadata.)4546## Examples4748```49fit <- CordBat(X = as.matrix(log2(cordbat_example[metabolite_cols])), batch = batch_vec, group = group_vec, ref.batch = "Ref", grouping = FALSE, print.detail = FALSE); corrected_mat <- fit$X.cor50```5152## Evaluation signals5354- PCA plot on back-transformed corrected data (2^corrected_mat) shows samples from different batches overlapping in principal component space, whereas uncorrected PCA showed clear batch-driven clustering.55- Corrected matrix retains original dimensions and range; no NaN, Inf, or unexpected values introduced.56- fit object contains convergence status and model parameters; print.detail=FALSE still allows inspection of fit$X.cor.57- Biological group signal is preserved: mean log2-abundance differences between groups remain statistically significant post-correction.58- Reference batch samples remain numerically unchanged or minimally perturbed in corrected matrix (ref.batch acts as anchor).5960## Limitations6162- Assumes batch effects are multiplicative and uniform across metabolites; if batch effects are additive or highly metabolite-specific, correction may be incomplete.63- Requires designation of a high-quality reference batch; poor reference choice propagates bias to all corrected batches.64- grouping=FALSE means correction does not account for group×batch interactions; if such interactions are present, residual group-confounded batch signal may persist.65- CordBat is optimized for large-scale metabolomics (25+ metabolites per sample in the example); performance or stability on very small datasets not characterized.6667## Evidence6869- [other] CordBat() accepts a log-transformed metabolite matrix (X_mat), batch assignment vector (batch_vec), group assignment vector (group_vec), a reference batch label ('Ref'), and a grouping parameter set to FALSE, producing a fitted object from which the corrected matrix is extracted via fit$X.cor.: "CordBat() accepts a log-transformed metabolite matrix (X_mat), batch assignment vector (batch_vec), group assignment vector (group_vec), a reference batch label ("Ref"), and a grouping parameter set"70- [methods] fit <- CordBat(71 X = X_mat,72 batch = batch_vec,73 group = group_vec,74 ref.batch = "Ref",75 grouping = FALSE, 76 print.detail = FALSE77): "fit <- CordBat(78 X = X_mat,79 batch = batch_vec,80 group = group_vec,81 ref.batch = "Ref",82 grouping = FALSE, 83 print.detail = FALSE84)"85- [methods] Log-transform metabolite measurements and extract the corrected log2-scale matrix from fit$X.cor.: "X_mat <- as.matrix(log2(cordbat_example[met_cols]))"86- [readme] This is a R package implementation of the Concordance-Based Batch Effect Correction for Large-Scale Metabolomics (CordBat).: "This is a R package implementation of the Concordance-Based Batch Effect Correction for Large-Scale Metabolomics (CordBat)."87- [readme] There is no methodologic change within the CordBat package from the original publication, however, substantial changes have been made to improve computational efficiency and limit iterative loops.: "There is no methodologic change within the CordBat package from the original publication, however, substantial changes have been made to improve computational efficiency and limit iterative loops."
