Reconstruct the recursive mass correction stage
License: restricted — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution.
Summary
Apply a recursive mass correction algorithm to refine m/z accuracy of LC/HRMS peaks after initial detection, using internal reference standards or lock masses to recalibrate mass coordinates across population-scale untargeted datasets.
When to use
After peak detection on LC/HRMS data (mzXML, mzML, netCDF formats) when m/z values require refinement for improved mass accuracy in untargeted metabolomics workflows. This is especially critical in population-scale studies (n > 500) where systematic mass drift or calibration drift across batches degrades feature alignment and annotation fidelity.
When NOT to use
- Input peaks already post-corrected by another tool or workflow (prevents double-correction artifacts).
- Single-file or low-throughput analyses where mass drift is negligible (recursive correction is optimized for population-scale batch effects).
- Targeted workflows with predefined m/z tolerances if mass refinement is not a stated objective.
Inputs
- Detected peaks table (Rdata or CSV format) with columns: m/z, retention time, peak area, and peak properties (signal-to-noise ratio, peak width, asymmetry factor, etc.)
- Reference mass standards or lock masses (internal or external calibration compounds with known m/z values)
- Parameter spreadsheet (IPA_parameters.xlsx) with mass correction settings enabled
Outputs
- Corrected peaks table (Rdata and CSV formats) with updated m/z coordinates
- Pre- and post-correction m/z accuracy metrics (e.g., mass error in ppm, standard deviation of mass error)
- Mass correction calibration curve or coefficients applied
How to apply
Load the detected peaks table containing m/z values and peak properties from the prior peak detection stage. IDSL.IPA implements recursive mass correction as part of its processing pipeline; invoke it via the IPA_workflow function with the IPA parameter spreadsheet configured to enable mass correction. The algorithm recalibrates m/z values using endogenous or external reference markers (lock masses). Pre- and post-correction m/z accuracy should be quantified and compared; export the final corrected peak dataset for downstream retention time correction and peak annotation. The correction operates at the MS1 level and is applied batch-wise or across the entire dataset depending on parameter configuration.
Related tools
- IDSL.IPA (Implements recursive mass correction algorithm as part of the peak processing suite; coordinates EIC candidate generation, peak detection, property evaluation, and mass/retention-time correction) — https://github.com/idslme/IDSL.IPA
- R (Host language for IDSL.IPA package and execution of
IPA_workflow function)
- IDSL.UFA (Downstream integration: molecular formula annotation on mass-corrected peaks) — https://github.com/idslme/IDSL.UFA
- IDSL.UFAx (Downstream integration: extended molecular formula annotation on mass-corrected peaks) — https://github.com/idslme/IDSL.UFAx
Examples
library(IDSL.IPA)
IPA_workflow("path/to/IPA_parameters.xlsx")
Evaluation signals
- Mass error (ppm) post-correction should be ≤ 5 ppm (typical HRMS tolerance) and lower than pre-correction error; inspect histogram/distribution of corrected mass errors.
- Standard deviation of mass error across the peak set should decrease after correction; quantify reduction as a percentage.
- Aligned peak tables downstream should show improved feature overlap and reduced m/z jitter when peaks from multiple files are aligned post-correction.
- Pre- vs. post-correction m/z coordinates should differ only by small, systematic offsets (not random noise); validate that correction is repeatable and not introducing artifacts.
- Annotation rate (successful matches to a reference compound database) should increase after mass correction, as refined m/z values improve hit quality.
Limitations
- Recursive mass correction depends on the availability and accurate identification of reference standards or lock masses; poor reference mass selection will propagate systematic error.
- Performance degrades if the detected peaks table contains false positives or low-confidence peaks; upstream peak detection quality directly impacts correction fidelity.
- Multi-batch datasets require careful alignment of reference masses or retention-time markers across batches; if batch effects are severe or references shift, correction may fail or introduce batch-specific biases.
- The algorithm is optimized for LC/HRMS data (mzXML, mzML, netCDF); applicability to other ionization methods or mass analyzers is not explicitly stated.
Evidence
- [other] Load detected peaks table containing m/z values and peak properties from prior detection step. Apply recursive mass correction algorithm as implemented in IDSL.IPA to recalibrate m/z values using internal reference standards or lock masses.: "Load detected peaks table containing m/z values and peak properties from prior detection step. Apply recursive mass correction algorithm as implemented in IDSL.IPA to recalibrate m/z values using"
- [other] IDSL.IPA includes a recursive mass correction algorithm as part of its suite of peak processing algorithms, applied after peak detection to refine mass accuracy of detected peaks.: "IDSL.IPA includes a recursive mass correction algorithm as part of its suite of peak processing algorithms, applied after peak detection to refine mass accuracy of detected peaks."
- [readme] IDSL.IPA is a suite of new algorithms covering extracted ion chromatogram (EIC) candidate generation, peak detection, peak property evaluation, recursive mass correction, retention time correction across multiple batches and peak annotation.: "IDSL.IPA is a suite of new algorithms covering extracted ion chromatogram (EIC) candidate generation, peak detection, peak property evaluation, recursive mass correction, retention time correction"
- [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] Analyzing population size untargeted studies (n > 500): "Analyzing population size untargeted studies (n > 500)"
1---2name: recursive-algorithm-implementation3description: Use when after peak detection on LC/HRMS data (mzXML, mzML, netCDF formats) when m/z values require refinement for improved mass accuracy in untargeted metabolomics workflows.4license: CC-BY-4.05---67# Reconstruct the recursive mass correction stage89> **License: restricted** — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution. <!-- asb-license-banner -->10## Summary1112Apply a recursive mass correction algorithm to refine m/z accuracy of LC/HRMS peaks after initial detection, using internal reference standards or lock masses to recalibrate mass coordinates across population-scale untargeted datasets.1314## When to use1516After peak detection on LC/HRMS data (mzXML, mzML, netCDF formats) when m/z values require refinement for improved mass accuracy in untargeted metabolomics workflows. This is especially critical in population-scale studies (n > 500) where systematic mass drift or calibration drift across batches degrades feature alignment and annotation fidelity.1718## When NOT to use1920- Input peaks already post-corrected by another tool or workflow (prevents double-correction artifacts).21- Single-file or low-throughput analyses where mass drift is negligible (recursive correction is optimized for population-scale batch effects).22- Targeted workflows with predefined m/z tolerances if mass refinement is not a stated objective.2324## Inputs2526- Detected peaks table (Rdata or CSV format) with columns: m/z, retention time, peak area, and peak properties (signal-to-noise ratio, peak width, asymmetry factor, etc.)27- Reference mass standards or lock masses (internal or external calibration compounds with known m/z values)28- Parameter spreadsheet (IPA_parameters.xlsx) with mass correction settings enabled2930## Outputs3132- Corrected peaks table (Rdata and CSV formats) with updated m/z coordinates33- Pre- and post-correction m/z accuracy metrics (e.g., mass error in ppm, standard deviation of mass error)34- Mass correction calibration curve or coefficients applied3536## How to apply3738Load the detected peaks table containing m/z values and peak properties from the prior peak detection stage. IDSL.IPA implements recursive mass correction as part of its processing pipeline; invoke it via the `IPA_workflow` function with the IPA parameter spreadsheet configured to enable mass correction. The algorithm recalibrates m/z values using endogenous or external reference markers (lock masses). Pre- and post-correction m/z accuracy should be quantified and compared; export the final corrected peak dataset for downstream retention time correction and peak annotation. The correction operates at the MS1 level and is applied batch-wise or across the entire dataset depending on parameter configuration.3940## Related tools4142- **IDSL.IPA** (Implements recursive mass correction algorithm as part of the peak processing suite; coordinates EIC candidate generation, peak detection, property evaluation, and mass/retention-time correction) — https://github.com/idslme/IDSL.IPA43- **R** (Host language for IDSL.IPA package and execution of `IPA_workflow` function)44- **IDSL.UFA** (Downstream integration: molecular formula annotation on mass-corrected peaks) — https://github.com/idslme/IDSL.UFA45- **IDSL.UFAx** (Downstream integration: extended molecular formula annotation on mass-corrected peaks) — https://github.com/idslme/IDSL.UFAx4647## Examples4849```50library(IDSL.IPA)51IPA_workflow("path/to/IPA_parameters.xlsx")52```5354## Evaluation signals5556- Mass error (ppm) post-correction should be ≤ 5 ppm (typical HRMS tolerance) and lower than pre-correction error; inspect histogram/distribution of corrected mass errors.57- Standard deviation of mass error across the peak set should decrease after correction; quantify reduction as a percentage.58- Aligned peak tables downstream should show improved feature overlap and reduced m/z jitter when peaks from multiple files are aligned post-correction.59- Pre- vs. post-correction m/z coordinates should differ only by small, systematic offsets (not random noise); validate that correction is repeatable and not introducing artifacts.60- Annotation rate (successful matches to a reference compound database) should increase after mass correction, as refined m/z values improve hit quality.6162## Limitations6364- Recursive mass correction depends on the availability and accurate identification of reference standards or lock masses; poor reference mass selection will propagate systematic error.65- Performance degrades if the detected peaks table contains false positives or low-confidence peaks; upstream peak detection quality directly impacts correction fidelity.66- Multi-batch datasets require careful alignment of reference masses or retention-time markers across batches; if batch effects are severe or references shift, correction may fail or introduce batch-specific biases.67- The algorithm is optimized for LC/HRMS data (mzXML, mzML, netCDF); applicability to other ionization methods or mass analyzers is not explicitly stated.6869## Evidence7071- [other] Load detected peaks table containing m/z values and peak properties from prior detection step. Apply recursive mass correction algorithm as implemented in IDSL.IPA to recalibrate m/z values using internal reference standards or lock masses.: "Load detected peaks table containing m/z values and peak properties from prior detection step. Apply recursive mass correction algorithm as implemented in IDSL.IPA to recalibrate m/z values using"72- [other] IDSL.IPA includes a recursive mass correction algorithm as part of its suite of peak processing algorithms, applied after peak detection to refine mass accuracy of detected peaks.: "IDSL.IPA includes a recursive mass correction algorithm as part of its suite of peak processing algorithms, applied after peak detection to refine mass accuracy of detected peaks."73- [readme] IDSL.IPA is a suite of new algorithms covering extracted ion chromatogram (EIC) candidate generation, peak detection, peak property evaluation, recursive mass correction, retention time correction across multiple batches and peak annotation.: "IDSL.IPA is a suite of new algorithms covering extracted ion chromatogram (EIC) candidate generation, peak detection, peak property evaluation, recursive mass correction, retention time correction"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] Analyzing population size untargeted studies (n > 500): "Analyzing population size untargeted studies (n > 500)"
HolobiomicsLab