Chromatographic Peak Processing

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

Recursive mass correction refines m/z accuracy of detected LC/HRMS peaks by recalibrating against internal reference standards or lock masses. This is a critical post-detection stage in untargeted metabolomics workflows that improves downstream peak alignment and annotation reliability.

When to use

Apply this skill after peak detection when you have a table of detected peaks with m/z values and retention times from LC/HRMS data, and you observe systematic m/z drift across a batch or population-scale study (n > 500 samples). It is essential before peak alignment and annotation steps to minimize mass calibration errors that propagate through downstream analysis.

When NOT to use

• Input peaks are already aligned and annotated to a compound database—mass correction should precede annotation, not follow it.
• No internal reference standards or lock masses are available and mass drift is negligible (<1 ppm across the batch).
• Raw MS data has not yet undergone peak detection; mass correction operates on detected peaks, not raw spectra.

Inputs

• Detected peaks table (Rdata or CSV format) with m/z values, retention times, and peak properties from prior peak detection
• Internal reference standards or lock mass list (m/z and expected retention time or m/z window)
• IPA parameter spreadsheet (IPA_parameters.xlsx) with mass correction and reference marker settings

Outputs

• Corrected peak table (Rdata and CSV formats) with recalibrated m/z values
• Mass accuracy metrics (pre- and post-correction ppm error, residual mass distribution)
• Correction diagnostics (reference marker recovery, drift trajectory across batch)

How to apply

Load the detected peaks table containing m/z values and peak properties (peak area, chromatographic descriptors, isotope ratios) generated by the peak detection stage. Apply IDSL.IPA's recursive mass correction algorithm, which iteratively recalibrates m/z values using endogenous or exogenous reference markers (lock masses) to eliminate systematic drift. Compare pre- and post-correction m/z accuracy metrics (e.g., mass error in ppm, deviation from theoretical m/z). Export the corrected peak table with updated m/z coordinates, ensuring mass error is reduced to specifications compatible with your downstream annotation tool (typically ≤5 ppm for high-resolution Orbitrap data). Evaluate correction success by examining the distribution of residual mass errors and checking that isotope mass differences (e.g., ¹²C/¹³C, ±1.003 Da) are preserved.

Related tools

• IDSL.IPA (Primary R package implementing the recursive mass correction algorithm; processes mzXML, mzML, and netCDF LC/HRMS data and applies mass recalibration after peak detection) — https://github.com/idslme/IDSL.IPA
• R (Execution environment for IDSL.IPA; required for running the mass correction workflow)
• RnetCDF (Optional R package for reading netCDF/CDF mass spectrometry data formats before mass correction) — https://CRAN.R-project.org/package=RNetCDF

Examples

library(IDSL.IPA)
IPA_workflow("path/to/IPA_parameters.xlsx")

Evaluation signals

• Mass error (ppm) after correction is systematically lower and narrower in distribution than pre-correction values, typically within ±5 ppm for high-resolution instruments.
• Isotope mass differences (¹²C/¹³C pairs, nIsoPair, RCS metrics) remain intact post-correction, confirming no spurious m/z shifts were introduced.
• Reference marker peaks used for calibration show residual mass error < 1 ppm, indicating successful anchor recovery.
• Peak alignment statistics downstream of mass correction (e.g., retention time deviation, number of aligned features across samples) show improvement relative to uncorrected peaks.
• Corrected peak table structure and completeness match input format (same number of rows/columns, no NaN or Inf values introduced).

Limitations

• Recursive mass correction requires reliable internal reference standards or lock masses; absence or poor quality of references will degrade correction fidelity.
• Algorithm assumes mass drift is systematic and smooth across the chromatographic run; non-linear or localized drift may not be fully corrected.
• Mass correction operates only on m/z dimension; retention time drift requires a separate retention time correction step using endogenous markers.
• No changelog or explicit version history is provided, limiting reproducibility tracking for specific algorithm revisions.
• Performance and parameter sensitivity for non-standard ionization modes (e.g., APCI, EI) are not explicitly documented.

Evidence

• [other] recursive mass correction algorithm as implemented in IDSL.IPA to recalibrate m/z values using internal reference standards or lock masses: "Apply recursive mass correction algorithm as implemented in IDSL.IPA to recalibrate m/z values using internal reference standards or lock masses."
• [other] Load detected peaks table containing m/z values and peak properties from prior detection step: "Load detected peaks table containing m/z values and peak properties from prior detection step."
• [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] 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: "algorithms covering extracted ion chromatogram (EIC) candidate generation, peak detection, peak property evaluation, recursive mass correction, retention time correction across multiple batches and"
• [other] Compare pre- and post-correction m/z accuracy metrics and export final corrected peak dataset: "Compare pre- and post-correction m/z accuracy metrics and export final corrected peak dataset."