# Chromatographic Peak Processing

> 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).

- Skill: `holobiomicslab/chromatographic-peak-processing` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/chromatographic-peak-processing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/chromatographic-peak-processing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/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. <!-- 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."