chromatographic-peak-classification
Summary
Classify benchmark chromatographic peaks detected by non-targeted preprocessing (NPP) tools into status categories (found, split, missing, misaligned) by matching against reference peaks with known m/z, retention time boundaries, and isotopologue identities. This enables quantitative assessment of NPP reliability in LC-HRMS metabolomics.
When to use
Apply this skill when you have (1) a benchmark dataset of reference peaks with validated m/z, retention time boundaries, and isotopologue assignments, and (2) NPP output feature tables (unaligned and aligned) from tools like XCMS, MZmine 2, or MS-DIAL that you wish to evaluate. Use it to generate a matching record that quantifies how well the NPP tool recovered, split, or missed the known peaks.
When NOT to use
- NPP output is already a curated, manually validated peak list — use this skill on raw automated NPP results, not manually post-processed features.
- Benchmark peaks lack isotopologue boundary information or retention time windows — this skill requires precise chromatographic boundaries for all enviPat-predicted isotopologues.
- Input mzML files are not centroided — mzRAPP requires centroided mzML format; use MSconvert to prepare raw vendor files first.
Inputs
- Benchmark peak CSV file (molecule identifier, m/z value, retention time boundaries, isotopologue identifier, adduct type)
- NPP unaligned feature table (m/z, retention time, peak intensity/area)
- NPP aligned feature table (m/z, aligned retention time, peak intensity/area)
- Sample metadata and target molecule file
Outputs
- Matched record CSV table with columns: benchmark peak ID, matching status (found/split/missing/misaligned), matched NPP feature ID, confidence scores, isotopologue validation flags
- Performance metrics per NPP tool: percentage of peaks found (83–99%), percentage of split peaks, percentage with degenerated isotopologue ratio (1–53%)
How to apply
Load benchmark peaks (with m/z, retention time boundaries, isotopologue identifiers, adduct types) and NPP output feature tables into mzRAPP. For each benchmark peak, apply m/z matching with 6 ppm precision tolerance and 5 ppm accuracy threshold to identify candidate NPP features. Narrow candidates using retention-time windowing to the expected chromatographic boundaries. For isotopologue clusters, validate peak shape correlation (Pearson r ≥ 0.85) with the most abundant isotopologue and filter isotopologues where isotopologue ratio bias exceeds 30%. Assign each benchmark peak to one of four categories: 'found' (single NPP match), 'split' (multiple NPP matches), 'missing' (no NPP match), or 'misaligned' (detected outside expected RT window). Generate a matched record CSV containing benchmark peak ID, classification status, matched NPP feature ID if found, confidence scores, and isotopologue validation flags for both unaligned and aligned feature tables.
Related tools
- mzRAPP (Primary tool implementing benchmark–NPP peak matching, isotopologue validation, and classification workflow) — https://github.com/YasinEl/mzRAPP
- enviPat (Predicts isotopologue m/z and abundance patterns for target molecules; integrated into mzRAPP for isotopologue envelope definition)
- XCMS (Example NPP tool whose output feature tables are classified by this skill; generates unaligned and aligned feature matrices)
- MZmine 2 (Alternative NPP tool for which this skill classifies detected peaks; output compared against benchmark)
- Skyline (Optional downstream tool for manual inspection and export of benchmark peaks with validated retention time boundaries)
- R (Environment for running mzRAPP and reproducing matching/classification via library(mzRAPP) or R scripts)
Examples
library(mzRAPP); benchmark <- read.csv('Benchmark_MTBLS267.csv'); npp_unaligned <- read.csv('XCMS_Run1_unaligned_peaks.csv'); npp_aligned <- read.csv('XCMS_Run1_aligned_peaks.csv'); matched_record <- classifyPeaks(benchmark, npp_unaligned, npp_aligned, mz_tol_ppm = 6, rt_tol_ppm = 5, iso_ratio_threshold = 0.30, cor_threshold = 0.85); write.csv(matched_record, 'XCMS_Run1_classification.csv')
Evaluation signals
- Benchmark dataset composition is confirmed: exactly 47 molecules, 157 features (adducts + isotopologues), 2870 total peaks extracted and validated before classification.
- All benchmark peaks are assigned to exactly one of four classes (found/split/missing/misaligned); no unclassified records remain.
- For 'found' peaks, matched NPP feature m/z is within 6 ppm precision and 5 ppm accuracy of benchmark; retention time is within provided boundaries.
- For isotopologue clusters classified as 'found', peak shape correlation to most abundant isotopologue is ≥ 0.85 and isotopologue ratio bias is < 30%.
- Performance summary statistics (e.g., 'XCMS detected 93–99% of peaks post-alignment with 3–20% degenerated IR') are generated and match expected ranges from comparable NPP runs.
Limitations
- Classification accuracy depends critically on accurate retention time boundaries and isotopologue m/z predictions; incomplete or incorrect boundary specification will inflate 'missing' or 'misaligned' counts.
- The 30% isotopologue ratio bias threshold and 0.85 Pearson correlation cutoff are fixed; peaks near these boundaries may be sensitivity-dependent and require manual review.
- Benchmark peaks with poor chromatographic resolution or overlapping isotopologue signals may be incorrectly split or misclassified when NPP reports multiple co-eluting features.
- Classification does not account for chemical background, matrix effects, or instrument drift; benchmark data should be acquired under consistent, representative conditions.
- Split classification (one benchmark peak matching multiple NPP features) may reflect genuine NPP over-segmentation or may arise from isotopologue doublets not fully resolved in the benchmark; additional curation may be needed.
Evidence
- [readme] mzRAPP extracts and validates chromatographic peaks for which boundaries are provided for all (enviPat predicted) isotopologues: "mzRAPP extracts and validates chromatographic peaks for which boundaries are provided for all (enviPat predicted) isotopologues"
- [other] For each benchmark peak, apply m/z matching with specified precision tolerance (6 ppm) and accuracy threshold (5 ppm) to candidate NPP features.: "apply m/z matching with specified precision tolerance (6 ppm) and accuracy threshold (5 ppm) to candidate NPP features"
- [other] Apply retention-time windowing to narrow candidate matches to the expected chromatographic boundaries provided in the benchmark.: "Apply retention-time windowing to narrow candidate matches to the expected chromatographic boundaries provided in the benchmark"
- [other] Classify each benchmark peak as 'found', 'split' (matched to multiple NPP peaks), 'missing', or 'misaligned' based on the matching result in both unaligned and aligned feature tables.: "Classify each benchmark peak as 'found', 'split' (matched to multiple NPP peaks), 'missing', or 'misaligned' based on the matching result"
- [readme] Isotopologue peaks with an area or height which is more than 30% off the predicted value or a Pearson Correlation coef < 0.85 (as compared to the highest isotopologue) are removed.: "Isotopologue peaks with an area or height which is more than 30% off the predicted value or a Pearson Correlation coef < 0.85 are removed"
- [methods] XCMS run 1 detected 83-94% of peaks with 28-53% degenerated isotopologue ratio. XCMS run 3 improved detection to 93-99% of peaks with 3-20% degenerated isotopologue ratio.: "XCMS run 1 detected 83-94% of peaks with 28-53% degenerated isotopologue ratio; XCMS run 3 improved detection to 93-99% of peaks with 3-20% degenerated isotopologue ratio"
1---2name: chromatographic-peak-classification-23description: Use when you have (1) a benchmark dataset of reference peaks with validated m/z, retention time boundaries, and isotopologue assignments, and (2) NPP output feature tables (unaligned and aligned) from tools like XCMS, MZmine 2, or MS-DIAL that you wish to evaluate.4license: CC-BY-4.05metadata:6 source: https://skillmd.com/skills/holobiomicslab/chromatographic-peak-classification-27 edam_operation: http://edamontology.org/operation_36328 edam_topics:9 - http://edamontology.org/topic_317210 - http://edamontology.org/topic_009111 tools:12 - mzRAPP13 - R14 - enviPat15 - XCMS16 - MZmine 217 - Skyline18 techniques:19 - mass-spectrometry20derived_from:21- doi: 10.1093/bioinformatics/btab231/621453022 title: mzRAPP23evidence_spans:24- 'You can now start mzRAPP using: library(mzRAPP); callmzRAPP()'25- The goal of mzRAPP is to allow reliability assessment of non-targeted data pre-processing (NPP)26- library(mzRAPP)27claims: []28provenance:29 collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v230 assembled_by: scripts/collect_metabolomics_collection.py31 sources:32 - build: coll_mzrapp_cq33 doi: 10.1093/bioinformatics/btab231/621453034 title: mzRAPP35 dedup_kept_from: coll_mzrapp_cq36schema_version: 0.2.037attribution:38 generator: AgenticScienceBuilder39 original_doi: 10.1093/bioinformatics/btab231/621453040 all_source_dois:41 - 10.1093/bioinformatics/btab231/621453042 zenodo_doi: 10.5281/zenodo.2079402743 curators: []44 promoter: Louis-Félix Nothias45 sponsor: CNRS & Université Côte d'Azur46---4748# chromatographic-peak-classification4950## Summary5152Classify benchmark chromatographic peaks detected by non-targeted preprocessing (NPP) tools into status categories (found, split, missing, misaligned) by matching against reference peaks with known m/z, retention time boundaries, and isotopologue identities. This enables quantitative assessment of NPP reliability in LC-HRMS metabolomics.5354## When to use5556Apply this skill when you have (1) a benchmark dataset of reference peaks with validated m/z, retention time boundaries, and isotopologue assignments, and (2) NPP output feature tables (unaligned and aligned) from tools like XCMS, MZmine 2, or MS-DIAL that you wish to evaluate. Use it to generate a matching record that quantifies how well the NPP tool recovered, split, or missed the known peaks.5758## When NOT to use5960- NPP output is already a curated, manually validated peak list — use this skill on raw automated NPP results, not manually post-processed features.61- Benchmark peaks lack isotopologue boundary information or retention time windows — this skill requires precise chromatographic boundaries for all enviPat-predicted isotopologues.62- Input mzML files are not centroided — mzRAPP requires centroided mzML format; use MSconvert to prepare raw vendor files first.6364## Inputs6566- Benchmark peak CSV file (molecule identifier, m/z value, retention time boundaries, isotopologue identifier, adduct type)67- NPP unaligned feature table (m/z, retention time, peak intensity/area)68- NPP aligned feature table (m/z, aligned retention time, peak intensity/area)69- Sample metadata and target molecule file7071## Outputs7273- Matched record CSV table with columns: benchmark peak ID, matching status (found/split/missing/misaligned), matched NPP feature ID, confidence scores, isotopologue validation flags74- Performance metrics per NPP tool: percentage of peaks found (83–99%), percentage of split peaks, percentage with degenerated isotopologue ratio (1–53%)7576## How to apply7778Load benchmark peaks (with m/z, retention time boundaries, isotopologue identifiers, adduct types) and NPP output feature tables into mzRAPP. For each benchmark peak, apply m/z matching with 6 ppm precision tolerance and 5 ppm accuracy threshold to identify candidate NPP features. Narrow candidates using retention-time windowing to the expected chromatographic boundaries. For isotopologue clusters, validate peak shape correlation (Pearson r ≥ 0.85) with the most abundant isotopologue and filter isotopologues where isotopologue ratio bias exceeds 30%. Assign each benchmark peak to one of four categories: 'found' (single NPP match), 'split' (multiple NPP matches), 'missing' (no NPP match), or 'misaligned' (detected outside expected RT window). Generate a matched record CSV containing benchmark peak ID, classification status, matched NPP feature ID if found, confidence scores, and isotopologue validation flags for both unaligned and aligned feature tables.7980## Related tools8182- **mzRAPP** (Primary tool implementing benchmark–NPP peak matching, isotopologue validation, and classification workflow) — https://github.com/YasinEl/mzRAPP83- **enviPat** (Predicts isotopologue m/z and abundance patterns for target molecules; integrated into mzRAPP for isotopologue envelope definition)84- **XCMS** (Example NPP tool whose output feature tables are classified by this skill; generates unaligned and aligned feature matrices)85- **MZmine 2** (Alternative NPP tool for which this skill classifies detected peaks; output compared against benchmark)86- **Skyline** (Optional downstream tool for manual inspection and export of benchmark peaks with validated retention time boundaries)87- **R** (Environment for running mzRAPP and reproducing matching/classification via library(mzRAPP) or R scripts)8889## Examples9091```92library(mzRAPP); benchmark <- read.csv('Benchmark_MTBLS267.csv'); npp_unaligned <- read.csv('XCMS_Run1_unaligned_peaks.csv'); npp_aligned <- read.csv('XCMS_Run1_aligned_peaks.csv'); matched_record <- classifyPeaks(benchmark, npp_unaligned, npp_aligned, mz_tol_ppm = 6, rt_tol_ppm = 5, iso_ratio_threshold = 0.30, cor_threshold = 0.85); write.csv(matched_record, 'XCMS_Run1_classification.csv')93```9495## Evaluation signals9697- Benchmark dataset composition is confirmed: exactly 47 molecules, 157 features (adducts + isotopologues), 2870 total peaks extracted and validated before classification.98- All benchmark peaks are assigned to exactly one of four classes (found/split/missing/misaligned); no unclassified records remain.99- For 'found' peaks, matched NPP feature m/z is within 6 ppm precision and 5 ppm accuracy of benchmark; retention time is within provided boundaries.100- For isotopologue clusters classified as 'found', peak shape correlation to most abundant isotopologue is ≥ 0.85 and isotopologue ratio bias is < 30%.101- Performance summary statistics (e.g., 'XCMS detected 93–99% of peaks post-alignment with 3–20% degenerated IR') are generated and match expected ranges from comparable NPP runs.102103## Limitations104105- Classification accuracy depends critically on accurate retention time boundaries and isotopologue m/z predictions; incomplete or incorrect boundary specification will inflate 'missing' or 'misaligned' counts.106- The 30% isotopologue ratio bias threshold and 0.85 Pearson correlation cutoff are fixed; peaks near these boundaries may be sensitivity-dependent and require manual review.107- Benchmark peaks with poor chromatographic resolution or overlapping isotopologue signals may be incorrectly split or misclassified when NPP reports multiple co-eluting features.108- Classification does not account for chemical background, matrix effects, or instrument drift; benchmark data should be acquired under consistent, representative conditions.109- Split classification (one benchmark peak matching multiple NPP features) may reflect genuine NPP over-segmentation or may arise from isotopologue doublets not fully resolved in the benchmark; additional curation may be needed.110111## Evidence112113- [readme] mzRAPP extracts and validates chromatographic peaks for which boundaries are provided for all (enviPat predicted) isotopologues: "mzRAPP extracts and validates chromatographic peaks for which boundaries are provided for all (enviPat predicted) isotopologues"114- [other] For each benchmark peak, apply m/z matching with specified precision tolerance (6 ppm) and accuracy threshold (5 ppm) to candidate NPP features.: "apply m/z matching with specified precision tolerance (6 ppm) and accuracy threshold (5 ppm) to candidate NPP features"115- [other] Apply retention-time windowing to narrow candidate matches to the expected chromatographic boundaries provided in the benchmark.: "Apply retention-time windowing to narrow candidate matches to the expected chromatographic boundaries provided in the benchmark"116- [other] Classify each benchmark peak as 'found', 'split' (matched to multiple NPP peaks), 'missing', or 'misaligned' based on the matching result in both unaligned and aligned feature tables.: "Classify each benchmark peak as 'found', 'split' (matched to multiple NPP peaks), 'missing', or 'misaligned' based on the matching result"117- [readme] Isotopologue peaks with an area or height which is more than 30% off the predicted value or a Pearson Correlation coef < 0.85 (as compared to the highest isotopologue) are removed.: "Isotopologue peaks with an area or height which is more than 30% off the predicted value or a Pearson Correlation coef < 0.85 are removed"118- [methods] XCMS run 1 detected 83-94% of peaks with 28-53% degenerated isotopologue ratio. XCMS run 3 improved detection to 93-99% of peaks with 3-20% degenerated isotopologue ratio.: "XCMS run 1 detected 83-94% of peaks with 28-53% degenerated isotopologue ratio; XCMS run 3 improved detection to 93-99% of peaks with 3-20% degenerated isotopologue ratio"