mass-isotopologue-adduct-grouping
Summary
Groups aligned LC-MS peaks by their isotopologue and adduct relationships using mass difference and intensity ratio criteria. This step consolidates redundant ion representations of the same molecular feature, reducing complexity in the final feature table.
When to use
After sample alignment has established consensus retention time and m/z coordinates across all samples, and you need to identify and merge peaks that represent isotopologues (e.g., ¹³C variants) or adducts (e.g., [M+H]⁺, [M+Na]⁺) of the same underlying molecule rather than distinct features.
When NOT to use
- Input data are profile (not centroided) spectra — grouping requires discrete peak m/z values.
- Mass accuracy is poor (>10 ppm) — isotope and adduct mass differences (0.99–1.01 Da) cannot be reliably distinguished from noise.
- Peak table already contains pre-grouped ions or has been processed by another tool that merged isotopologues — re-grouping may create artifacts.
Inputs
- aligned peak table with retention time and m/z consensus coordinates
- sample-wise intensity matrices from peak picking
- mass calibration metadata (ppm tolerance)
Outputs
- grouped feature table with isotopologue/adduct annotations
- consolidated peak intensity matrix (one row per feature group)
- isotopic composition assignments per feature
How to apply
SLAW applies isotopologue and adduct grouping by comparing mass differences and intensity ratios between aligned peaks within each sample. Peaks are grouped if their mass difference matches known isotopic shifts (e.g., ~1.003 Da for ¹³C, ~0.994 Da for ¹⁸O) or common adduct mass offsets, and their intensity ratios conform to expected natural abundance patterns or co-ionization behavior. The grouping is performed as a distinct workflow step following sample alignment, consolidating redundant ion forms before gap-filling and final feature annotation. Success depends on accurate mass calibration (typically <5 ppm) and sufficient peak intensity dynamic range to resolve natural isotopic ratios.
Related tools
- Centwave (Upstream peak picking algorithm; outputs peaks that are fed into isotopologue/adduct grouping)
- FeatureFinderMetabo (Upstream peak picking algorithm; outputs peaks that are fed into isotopologue/adduct grouping)
- ADAP (Upstream peak picking algorithm; outputs peaks that are fed into isotopologue/adduct grouping)
- SLAW (Container framework orchestrating the complete LC-MS workflow including isotopologue/adduct grouping as step 4) — https://github.com/zamboni-lab/SLAW
Examples
docker run --rm -v /path/to/input:/input -v /path/to/output:/output zambonilab/slaw:latest
Evaluation signals
- Grouped features show expected natural abundance ratios for common isotopes (e.g., ¹³C ~1.1% relative intensity).
- Mass differences between grouped peaks match known isotope or adduct shifts (±0.005 Da tolerance).
- The count of features in the output table is less than the input aligned peak count, confirming redundant ions were merged.
- Retention times of grouped peaks are identical (consensus RT) and intensities are correlated across samples.
- No spurious grouping across unrelated molecules — peaks in the same group co-elute and share sample intensity patterns.
Limitations
- Grouping accuracy depends on mass calibration; miscalibration (>5 ppm drift) may cause false negatives (failure to group true isotopologues) or false positives (erroneous grouping of unrelated peaks).
- Overlapping peaks with similar m/z in low-resolution or heavily congested regions may be incorrectly merged or split.
- Works only with DDA (data-dependent acquisition) MS2 data; DIA-MS2 spectra are not supported in SLAW and will be skipped during grouping.
- Natural abundance ratios can be distorted by sample complexity, ion suppression, or non-uniform ionization; ratios are used as heuristics, not absolute rules.
Evidence
- [other] Group detected peaks by isotopologue and adduct relationships using mass difference and intensity ratio criteria.: "Group detected peaks by isotopologue and adduct relationships using mass difference and intensity ratio criteria."
- [readme] Complete processing including peak picking, sample alignment, pick picking, grouping of isotopologues and adducts, gap-filling by data recursion, extraction of consolidated MS2 spectra and isotopic data: "Complete processing including peak picking, sample alignment, pick picking, grouping of isotopologues and adducts, gap-filling by data recursion, extraction of consolidated MS2 spectra and isotopic"
- [other] SLAW implements a complete processing pipeline comprising six sequential steps: peak picking, sample alignment, peak picking (repeated), grouping of isotopologues and adducts, gap-filling by data recursion, and extraction of consolidated MS2 spectra and isotopic data.: "SLAW implements a complete processing pipeline comprising six sequential steps: peak picking, sample alignment, peak picking (repeated), grouping of isotopologues and adducts, gap-filling by data"
- [readme] Files can include MS1 and DDA-MS2 scans. DIA-MS is not supported.: "Files can include MS1 and DDA-MS2 scans. DIA-MS is not supported."
- [readme] All data must be centroided and of unique polarity.: "All data must be centroided and of unique polarity."
1---2name: mass-isotopologue-adduct-grouping3description: Use when after sample alignment has established consensus retention time and m/z coordinates across all samples, and you need to identify and merge peaks that represent isotopologues (e.g., ¹³C variants) or adducts (e.4license: CC-BY-4.05---67# mass-isotopologue-adduct-grouping89## Summary1011Groups aligned LC-MS peaks by their isotopologue and adduct relationships using mass difference and intensity ratio criteria. This step consolidates redundant ion representations of the same molecular feature, reducing complexity in the final feature table.1213## When to use1415After sample alignment has established consensus retention time and m/z coordinates across all samples, and you need to identify and merge peaks that represent isotopologues (e.g., ¹³C variants) or adducts (e.g., [M+H]⁺, [M+Na]⁺) of the same underlying molecule rather than distinct features.1617## When NOT to use1819- Input data are profile (not centroided) spectra — grouping requires discrete peak m/z values.20- Mass accuracy is poor (>10 ppm) — isotope and adduct mass differences (0.99–1.01 Da) cannot be reliably distinguished from noise.21- Peak table already contains pre-grouped ions or has been processed by another tool that merged isotopologues — re-grouping may create artifacts.2223## Inputs2425- aligned peak table with retention time and m/z consensus coordinates26- sample-wise intensity matrices from peak picking27- mass calibration metadata (ppm tolerance)2829## Outputs3031- grouped feature table with isotopologue/adduct annotations32- consolidated peak intensity matrix (one row per feature group)33- isotopic composition assignments per feature3435## How to apply3637SLAW applies isotopologue and adduct grouping by comparing mass differences and intensity ratios between aligned peaks within each sample. Peaks are grouped if their mass difference matches known isotopic shifts (e.g., ~1.003 Da for ¹³C, ~0.994 Da for ¹⁸O) or common adduct mass offsets, and their intensity ratios conform to expected natural abundance patterns or co-ionization behavior. The grouping is performed as a distinct workflow step following sample alignment, consolidating redundant ion forms before gap-filling and final feature annotation. Success depends on accurate mass calibration (typically <5 ppm) and sufficient peak intensity dynamic range to resolve natural isotopic ratios.3839## Related tools4041- **Centwave** (Upstream peak picking algorithm; outputs peaks that are fed into isotopologue/adduct grouping)42- **FeatureFinderMetabo** (Upstream peak picking algorithm; outputs peaks that are fed into isotopologue/adduct grouping)43- **ADAP** (Upstream peak picking algorithm; outputs peaks that are fed into isotopologue/adduct grouping)44- **SLAW** (Container framework orchestrating the complete LC-MS workflow including isotopologue/adduct grouping as step 4) — https://github.com/zamboni-lab/SLAW4546## Examples4748```49docker run --rm -v /path/to/input:/input -v /path/to/output:/output zambonilab/slaw:latest50```5152## Evaluation signals5354- Grouped features show expected natural abundance ratios for common isotopes (e.g., ¹³C ~1.1% relative intensity).55- Mass differences between grouped peaks match known isotope or adduct shifts (±0.005 Da tolerance).56- The count of features in the output table is less than the input aligned peak count, confirming redundant ions were merged.57- Retention times of grouped peaks are identical (consensus RT) and intensities are correlated across samples.58- No spurious grouping across unrelated molecules — peaks in the same group co-elute and share sample intensity patterns.5960## Limitations6162- Grouping accuracy depends on mass calibration; miscalibration (>5 ppm drift) may cause false negatives (failure to group true isotopologues) or false positives (erroneous grouping of unrelated peaks).63- Overlapping peaks with similar m/z in low-resolution or heavily congested regions may be incorrectly merged or split.64- Works only with DDA (data-dependent acquisition) MS2 data; DIA-MS2 spectra are not supported in SLAW and will be skipped during grouping.65- Natural abundance ratios can be distorted by sample complexity, ion suppression, or non-uniform ionization; ratios are used as heuristics, not absolute rules.6667## Evidence6869- [other] Group detected peaks by isotopologue and adduct relationships using mass difference and intensity ratio criteria.: "Group detected peaks by isotopologue and adduct relationships using mass difference and intensity ratio criteria."70- [readme] Complete processing including peak picking, sample alignment, pick picking, grouping of isotopologues and adducts, gap-filling by data recursion, extraction of consolidated MS2 spectra and isotopic data: "Complete processing including peak picking, sample alignment, pick picking, grouping of isotopologues and adducts, gap-filling by data recursion, extraction of consolidated MS2 spectra and isotopic"71- [other] SLAW implements a complete processing pipeline comprising six sequential steps: peak picking, sample alignment, peak picking (repeated), grouping of isotopologues and adducts, gap-filling by data recursion, and extraction of consolidated MS2 spectra and isotopic data.: "SLAW implements a complete processing pipeline comprising six sequential steps: peak picking, sample alignment, peak picking (repeated), grouping of isotopologues and adducts, gap-filling by data"72- [readme] Files can include MS1 and DDA-MS2 scans. DIA-MS is not supported.: "Files can include MS1 and DDA-MS2 scans. DIA-MS is not supported."73- [readme] All data must be centroided and of unique polarity.: "All data must be centroided and of unique polarity."
HolobiomicsLab 