batch-vector-preparation
Summary
Construct a categorical batch assignment vector from metabolomics sample metadata to label each observation with its batch provenance. This vector is a required input to concordance-based batch correction workflows and must align dimensionally with the metabolite matrix rows.
When to use
You have a metabolomics dataset with samples collected across multiple batches (e.g., different MS runs, sample preparation rounds, or instrument configurations) and need to apply batch-aware correction methods such as CordBat. Batch labeling must be encoded as a vector with one entry per sample, matching the row order of the metabolite matrix.
When NOT to use
- Samples have no batch structure or all samples come from a single batch — batch correction is unnecessary.
- Batch labels are already embedded in row names of the metabolite matrix and cannot be reliably extracted as a separate vector.
- The metadata contains missing or ambiguous batch assignments that cannot be unambiguously mapped to samples.
Inputs
- sample metadata table (data frame with batch assignment column)
- metabolite matrix (rows = samples, columns = metabolites)
Outputs
- batch assignment vector (character or factor; length = number of samples)
How to apply
Extract the batch assignment column(s) from your sample metadata table and construct a vector with length equal to the number of rows in your metabolite matrix. Each entry should be a batch label (e.g., 'Batch1', 'Batch2', or 'Ref') corresponding to the batch in which that sample was analyzed. The vector must be in the same row order as your metabolite data matrix. Pass this vector as the batch parameter to CordBat() along with log2-transformed metabolite measurements and a group assignment vector. Verify that the vector contains no missing values and that all unique batch labels are represented; if one batch is designated as a reference (e.g., 'Ref'), ensure it is explicitly labeled so it can be specified via the ref.batch parameter.
Related tools
- CordBat (Accepts batch-vector as input parameter to perform concordance-based batch effect correction on log-transformed metabolite matrices) — https://github.com/BorchLab/CordBat
- R (Language environment for constructing vectors from data frames and executing batch correction workflows)
Examples
batch_vec <- cordbat_example$batch; fit <- CordBat(X=X_mat, batch=batch_vec, group=group_vec, ref.batch="Ref", grouping=FALSE, print.detail=FALSE)
Evaluation signals
- batch_vec length equals number of rows in metabolite matrix (nrow(X_mat))
- batch_vec contains no NA or NULL entries
- All unique batch labels in batch_vec are valid strings (e.g., no whitespace-only entries)
- If ref.batch='Ref' is specified in CordBat call, 'Ref' is present in batch_vec with at least one occurrence
- Row order of batch_vec matches row order of metabolite matrix (samples at index i in both structures correspond)
Limitations
- Batch vector does not account for confounding effects beyond batch; group effects must be specified separately via group_vec parameter.
- Concordance-based correction assumes batch effects are multiplicative on log-scale; highly non-linear or sample-specific batch artifacts may not be adequately corrected.
- Reference batch selection influences the scale and direction of corrections; misspecification of ref.batch can bias results.
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: "CordBat() accepts a log-transformed metabolite matrix (X_mat), batch assignment vector (batch_vec), group assignment vector (group_vec), a reference batch label ("Ref")"
- [other] Log2-transform the metabolite matrix and prepare batch and group vectors from metadata.: "Log2-transform the metabolite matrix and prepare batch and group vectors from metadata"
- [other] Run CordBat() with X=log2-transformed matrix, batch=batch vector, group=group vector, ref.batch='Ref', grouping=FALSE, and print.detail=FALSE.: "Run CordBat() with X=log2-transformed matrix, batch=batch vector, group=group vector, ref.batch='Ref', grouping=FALSE"
- [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
)"
- [readme] Concordance-Based Batch Effect Correction for Large-Scale Metabolomics: "Concordance-Based Batch Effect Correction for Large-Scale Metabolomics"
1---2name: batch-vector-preparation3description: Use when you have a metabolomics dataset with samples collected across multiple batches (e.g., different MS runs, sample preparation rounds, or instrument configurations) and need to apply batch-aware correction methods such as CordBat.4license: CC-BY-4.05---67# batch-vector-preparation89## Summary1011Construct a categorical batch assignment vector from metabolomics sample metadata to label each observation with its batch provenance. This vector is a required input to concordance-based batch correction workflows and must align dimensionally with the metabolite matrix rows.1213## When to use1415You have a metabolomics dataset with samples collected across multiple batches (e.g., different MS runs, sample preparation rounds, or instrument configurations) and need to apply batch-aware correction methods such as CordBat. Batch labeling must be encoded as a vector with one entry per sample, matching the row order of the metabolite matrix.1617## When NOT to use1819- Samples have no batch structure or all samples come from a single batch — batch correction is unnecessary.20- Batch labels are already embedded in row names of the metabolite matrix and cannot be reliably extracted as a separate vector.21- The metadata contains missing or ambiguous batch assignments that cannot be unambiguously mapped to samples.2223## Inputs2425- sample metadata table (data frame with batch assignment column)26- metabolite matrix (rows = samples, columns = metabolites)2728## Outputs2930- batch assignment vector (character or factor; length = number of samples)3132## How to apply3334Extract the batch assignment column(s) from your sample metadata table and construct a vector with length equal to the number of rows in your metabolite matrix. Each entry should be a batch label (e.g., 'Batch1', 'Batch2', or 'Ref') corresponding to the batch in which that sample was analyzed. The vector must be in the same row order as your metabolite data matrix. Pass this vector as the `batch` parameter to CordBat() along with log2-transformed metabolite measurements and a group assignment vector. Verify that the vector contains no missing values and that all unique batch labels are represented; if one batch is designated as a reference (e.g., 'Ref'), ensure it is explicitly labeled so it can be specified via the `ref.batch` parameter.3536## Related tools3738- **CordBat** (Accepts batch-vector as input parameter to perform concordance-based batch effect correction on log-transformed metabolite matrices) — https://github.com/BorchLab/CordBat39- **R** (Language environment for constructing vectors from data frames and executing batch correction workflows)4041## Examples4243```44batch_vec <- cordbat_example$batch; fit <- CordBat(X=X_mat, batch=batch_vec, group=group_vec, ref.batch="Ref", grouping=FALSE, print.detail=FALSE)45```4647## Evaluation signals4849- batch_vec length equals number of rows in metabolite matrix (nrow(X_mat))50- batch_vec contains no NA or NULL entries51- All unique batch labels in batch_vec are valid strings (e.g., no whitespace-only entries)52- If ref.batch='Ref' is specified in CordBat call, 'Ref' is present in batch_vec with at least one occurrence53- Row order of batch_vec matches row order of metabolite matrix (samples at index i in both structures correspond)5455## Limitations5657- Batch vector does not account for confounding effects beyond batch; group effects must be specified separately via group_vec parameter.58- Concordance-based correction assumes batch effects are multiplicative on log-scale; highly non-linear or sample-specific batch artifacts may not be adequately corrected.59- Reference batch selection influences the scale and direction of corrections; misspecification of ref.batch can bias results.6061## Evidence6263- [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: "CordBat() accepts a log-transformed metabolite matrix (X_mat), batch assignment vector (batch_vec), group assignment vector (group_vec), a reference batch label ("Ref")"64- [other] Log2-transform the metabolite matrix and prepare batch and group vectors from metadata.: "Log2-transform the metabolite matrix and prepare batch and group vectors from metadata"65- [other] Run CordBat() with X=log2-transformed matrix, batch=batch vector, group=group vector, ref.batch='Ref', grouping=FALSE, and print.detail=FALSE.: "Run CordBat() with X=log2-transformed matrix, batch=batch vector, group=group vector, ref.batch='Ref', grouping=FALSE"66- [methods] fit <- CordBat( X = X_mat, batch = batch_vec, group = group_vec, ref.batch = "Ref", grouping = FALSE, print.detail = FALSE ): "fit <- CordBat(67 X = X_mat,68 batch = batch_vec,69 group = group_vec,70 ref.batch = "Ref",71 grouping = FALSE, 72 print.detail = FALSE73)"74- [readme] Concordance-Based Batch Effect Correction for Large-Scale Metabolomics: "Concordance-Based Batch Effect Correction for Large-Scale Metabolomics"
HolobiomicsLab