peak-table-harmonization
License: restricted — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution.
Summary
Align and harmonize peak tables across multiple LC/HRMS batches by applying retention time correction to resolve batch-induced shifts in chromatographic retention times while preserving peak identity across samples. This skill ensures that chemically identical compounds with the same m/z and elution profile are assigned consistent retention times across all batches in large-scale population studies.
When to use
When you have extracted peak tables from multiple independent LC/HRMS analysis batches (each with retention time and m/z values) and need to align peaks across batches to create a unified feature matrix for downstream statistical analysis. Specifically apply this skill if: (1) you observe systematic retention time drift or batch-to-batch variation in peak elution times for the same compounds, (2) your study includes n > 500 samples across multiple instrumental runs or days, or (3) you are generating a single consensus peak alignment table from individually processed peaklists in separate mzXML/mzML/netCDF files.
When NOT to use
- Input data is already a single batch or all samples were collected in a single instrumental run (no batch effect correction needed).
- Retention time variation is non-systematic or instrument-specific and cannot be modeled with global endogenous reference markers.
- Peak tables have already been aligned by another tool (e.g., xcms or MZmine 2); applying a second harmonization may introduce conflicting coordinate systems.
Inputs
- Individual batch peaklists with retention time (RT) and mass-to-charge (m/z) values in Rdata or CSV format
- Multiple LC/HRMS data files (mzXML, mzML, or netCDF format) from separate batches or instrumental runs
- IPA parameter spreadsheet specifying input/output directories and retention time correction settings
Outputs
- Harmonized peak alignment table with corrected retention times and unified m/z-RT coordinates
- Gap-filled peak height matrix aligned across all samples
- Batch-level retention time correction metadata or transformation functions
- Pairwise correlation lists for aligned peaks (to detect recurring adducts and fragment ions)
How to apply
Load extracted peak lists from each batch into IDSL.IPA with their raw retention time and m/z coordinates. Use endogenous reference markers (stable, consistently detected compounds across all batches) to estimate the retention time correction function for each batch relative to a reference batch or global alignment frame. Apply the retention time correction algorithm to shift all peaks in non-reference batches so that peaks with identical m/z and similar RT elution profiles align to a common retention time coordinate. Generate a corrected peak alignment table where each unique (m/z, corrected-RT) pair is assigned a single consensus row, with peak heights gap-filled across all samples. Evaluate alignment success by checking that isotopologue pairs, adducts, and fragments maintain expected mass differences and co-elution patterns across the harmonized table.
Related tools
- IDSL.IPA (Implements the full suite of retention time correction, peak alignment, and harmonization algorithms; outputs corrected peak alignment tables and gap-filled matrices.) — https://github.com/idslme/IDSL.IPA
- R (Execution environment for IDSL.IPA; required to run the IPA_workflow function.)
- IDSL.UFA (Integrates with harmonized peak tables for downstream molecular formula annotation.) — https://github.com/idslme/IDSL.UFA
- IDSL.CSA (Integrates with harmonized and annotated peak tables to cluster recurring ions and generate composite spectra.) — https://github.com/idslme/IDSL.CSA
Examples
library(IDSL.IPA)
IPA_workflow("path/to/IPA_parameters.xlsx")
Evaluation signals
- Peak alignment success: Verify that isotopologue pairs (12C/13C) and known adducts maintain expected mass differences (e.g., ±1.003 Da for 13C, ±18.01 Da for [M+NH4]+) across all harmonized rows.
- Retention time consistency: Check that peaks assigned the same (m/z, corrected-RT) coordinates in the alignment table have inter-batch CV in corrected RT < 5% (or per-batch SD < 1 scan width).
- Gap-filling validation: Confirm that the gap-filled peak height matrix has no structural NaNs or inconsistent row/column dimensions; compare gap-filled vs. observed peak counts to verify imputation occurred.
- Batch effect removal: Plot corrected RT vs. raw RT by batch; corrected RTs should cluster tightly around the reference coordinate for peaks detected in multiple batches, while raw RTs show systematic drift.
- Annotation fidelity: Verify that pairwise correlation lists for aligned peaks show expected co-elution patterns (e.g., adducts and in-source fragments of the same compound should have Pearson r > 0.7 in peak height correlation).
Limitations
- Retention time correction relies on identification of stable endogenous reference markers across all batches; if few markers are detected or markers are unstable, correction may be inaccurate or fail.
- Systematic non-linear retention time drift (e.g., gradient time non-uniformity) may not be fully captured by a global correction function, leading to residual misalignment in extreme RT regions.
- Peak harmonization assumes that the same compound has identical m/z and similar RT across batches; compounds with significant post-acquisition mass drift or unexpected RT shifts (e.g., due to column degradation) may not align correctly.
- Large population-scale studies (n > 500) may produce alignment ambiguities if multiple peaks with similar m/z and RT exist; filtering by peak quality metrics (S/N, peak width, symmetry) is recommended upstream.
Evidence
- [other] retention time correction algorithm across batches to align peaks with similar m/z and RT profiles: "Apply retention time correction algorithm across batches to align peaks with similar m/z and RT profiles."
- [other] IDSL.IPA includes retention time correction as one of its algorithmic components: "IDSL.IPA includes retention time correction as one of its algorithmic components in a suite covering EIC candidate generation, peak detection, peak property evaluation, recursive mass correction, and"
- [readme] Retention time correction using endogenous reference markers for multi-batch large scale studies: "Retention time correction using endogenous reference markers for multi-batch large scale studies"
- [readme] peak alignment tables in the peak_alignment directory: "Peak alignment tables in the "peak_alignment" directory."
- [readme] generates comprehensive and high-quality datasets from untargeted analysis of organic small molecules for population-size studies: "IDSL.IPA generates comprehensive and high-quality datasets from untargeted analysis of organic small molecules for population-size studies."
- [readme] Generating pairwise correlations list for aligned peak height and its gap-filled tables: "Generating pairwise correlations list for aligned peak height and its gap-filled tables to detect potential recurring adducts, in-source products and fragment peaks"
1---2name: peak-table-harmonization-23description: Use when when you have extracted peak tables from multiple independent LC/HRMS analysis batches (each with retention time and m/z values) and need to align peaks across batches to create a unified feature matrix for downstream statistical analysis.4license: CC-BY-4.05---67# peak-table-harmonization89> **License: restricted** — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution. <!-- asb-license-banner -->10## Summary1112Align and harmonize peak tables across multiple LC/HRMS batches by applying retention time correction to resolve batch-induced shifts in chromatographic retention times while preserving peak identity across samples. This skill ensures that chemically identical compounds with the same m/z and elution profile are assigned consistent retention times across all batches in large-scale population studies.1314## When to use1516When you have extracted peak tables from multiple independent LC/HRMS analysis batches (each with retention time and m/z values) and need to align peaks across batches to create a unified feature matrix for downstream statistical analysis. Specifically apply this skill if: (1) you observe systematic retention time drift or batch-to-batch variation in peak elution times for the same compounds, (2) your study includes n > 500 samples across multiple instrumental runs or days, or (3) you are generating a single consensus peak alignment table from individually processed peaklists in separate mzXML/mzML/netCDF files.1718## When NOT to use1920- Input data is already a single batch or all samples were collected in a single instrumental run (no batch effect correction needed).21- Retention time variation is non-systematic or instrument-specific and cannot be modeled with global endogenous reference markers.22- Peak tables have already been aligned by another tool (e.g., xcms or MZmine 2); applying a second harmonization may introduce conflicting coordinate systems.2324## Inputs2526- Individual batch peaklists with retention time (RT) and mass-to-charge (m/z) values in Rdata or CSV format27- Multiple LC/HRMS data files (mzXML, mzML, or netCDF format) from separate batches or instrumental runs28- IPA parameter spreadsheet specifying input/output directories and retention time correction settings2930## Outputs3132- Harmonized peak alignment table with corrected retention times and unified m/z-RT coordinates33- Gap-filled peak height matrix aligned across all samples34- Batch-level retention time correction metadata or transformation functions35- Pairwise correlation lists for aligned peaks (to detect recurring adducts and fragment ions)3637## How to apply3839Load extracted peak lists from each batch into IDSL.IPA with their raw retention time and m/z coordinates. Use endogenous reference markers (stable, consistently detected compounds across all batches) to estimate the retention time correction function for each batch relative to a reference batch or global alignment frame. Apply the retention time correction algorithm to shift all peaks in non-reference batches so that peaks with identical m/z and similar RT elution profiles align to a common retention time coordinate. Generate a corrected peak alignment table where each unique (m/z, corrected-RT) pair is assigned a single consensus row, with peak heights gap-filled across all samples. Evaluate alignment success by checking that isotopologue pairs, adducts, and fragments maintain expected mass differences and co-elution patterns across the harmonized table.4041## Related tools4243- **IDSL.IPA** (Implements the full suite of retention time correction, peak alignment, and harmonization algorithms; outputs corrected peak alignment tables and gap-filled matrices.) — https://github.com/idslme/IDSL.IPA44- **R** (Execution environment for IDSL.IPA; required to run the IPA_workflow function.)45- **IDSL.UFA** (Integrates with harmonized peak tables for downstream molecular formula annotation.) — https://github.com/idslme/IDSL.UFA46- **IDSL.CSA** (Integrates with harmonized and annotated peak tables to cluster recurring ions and generate composite spectra.) — https://github.com/idslme/IDSL.CSA4748## Examples4950```51library(IDSL.IPA)52IPA_workflow("path/to/IPA_parameters.xlsx")53```5455## Evaluation signals5657- Peak alignment success: Verify that isotopologue pairs (12C/13C) and known adducts maintain expected mass differences (e.g., ±1.003 Da for 13C, ±18.01 Da for [M+NH4]+) across all harmonized rows.58- Retention time consistency: Check that peaks assigned the same (m/z, corrected-RT) coordinates in the alignment table have inter-batch CV in corrected RT < 5% (or per-batch SD < 1 scan width).59- Gap-filling validation: Confirm that the gap-filled peak height matrix has no structural NaNs or inconsistent row/column dimensions; compare gap-filled vs. observed peak counts to verify imputation occurred.60- Batch effect removal: Plot corrected RT vs. raw RT by batch; corrected RTs should cluster tightly around the reference coordinate for peaks detected in multiple batches, while raw RTs show systematic drift.61- Annotation fidelity: Verify that pairwise correlation lists for aligned peaks show expected co-elution patterns (e.g., adducts and in-source fragments of the same compound should have Pearson r > 0.7 in peak height correlation).6263## Limitations6465- Retention time correction relies on identification of stable endogenous reference markers across all batches; if few markers are detected or markers are unstable, correction may be inaccurate or fail.66- Systematic non-linear retention time drift (e.g., gradient time non-uniformity) may not be fully captured by a global correction function, leading to residual misalignment in extreme RT regions.67- Peak harmonization assumes that the same compound has identical m/z and similar RT across batches; compounds with significant post-acquisition mass drift or unexpected RT shifts (e.g., due to column degradation) may not align correctly.68- Large population-scale studies (n > 500) may produce alignment ambiguities if multiple peaks with similar m/z and RT exist; filtering by peak quality metrics (S/N, peak width, symmetry) is recommended upstream.6970## Evidence7172- [other] retention time correction algorithm across batches to align peaks with similar m/z and RT profiles: "Apply retention time correction algorithm across batches to align peaks with similar m/z and RT profiles."73- [other] IDSL.IPA includes retention time correction as one of its algorithmic components: "IDSL.IPA includes retention time correction as one of its algorithmic components in a suite covering EIC candidate generation, peak detection, peak property evaluation, recursive mass correction, and"74- [readme] Retention time correction using endogenous reference markers for multi-batch large scale studies: "Retention time correction using endogenous reference markers for multi-batch large scale studies"75- [readme] peak alignment tables in the peak_alignment directory: "Peak alignment tables in the "peak_alignment" directory."76- [readme] generates comprehensive and high-quality datasets from untargeted analysis of organic small molecules for population-size studies: "IDSL.IPA generates comprehensive and high-quality datasets from untargeted analysis of organic small molecules for population-size studies."77- [readme] Generating pairwise correlations list for aligned peak height and its gap-filled tables: "Generating pairwise correlations list for aligned peak height and its gap-filled tables to detect potential recurring adducts, in-source products and fragment peaks"
HolobiomicsLab