Chromatographic Peak Processing

---
name: chromatographic-peak-processing
description: Use when 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).
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3632
  edam_topics:
  - http://edamontology.org/topic_0091
  - http://edamontology.org/topic_3370
  tools:
  - IDSL.IPA
  - R
  - RnetCDF
  techniques:
  - mass-spectrometry
  license_tier: restricted
  provenance_tier: literature
derived_from:
- doi: 10.1021/acs.jproteome.2c00120
  title: IDSL.IPA
evidence_spans:
- '**Intrinsic Peak Analysis (IPA)** by the [**Integrated Data Science Laboratory
  for Metabolomics and Exposomics (IDSL.ME)**](https://www.idsl.me) is a light-weight
  R package'
- light-weight R package
claims: []
provenance:
  collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v2
  assembled_by: scripts/collect_metabolomics_collection.py
  sources:
  - build: coll_idsl_ipa_cq
    doi: 10.1021/acs.jproteome.2c00120
    title: IDSL.IPA
  dedup_kept_from: coll_idsl_ipa_cq
schema_version: 0.2.0
attribution:
  generator: AgenticScienceBuilder
  original_doi: 10.1021/acs.jproteome.2c00120
  all_source_dois:
  - 10.1021/acs.jproteome.2c00120
  zenodo_doi: 10.5281/zenodo.20794027
  curators: []
  promoter: Louis-Félix Nothias
  sponsor: CNRS & Université Côte d'Azur
---

# 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. <!-- asb-license-banner -->
## 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."