# Recursive Algorithm Implementation

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

- Skill: `holobiomicslab/recursive-algorithm-implementation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/recursive-algorithm-implementation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/recursive-algorithm-implementation/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/recursive-algorithm-implementation

---


# 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

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