isotopologue-adduct-cluster-assignment
Summary
Groups detected LC-MS features into isotopologue and adduct clusters by clustering features that share the same molecular ion and mass differences corresponding to isotopic shifts (C13, N15, D) or common adduct transformations ([M+H]+, [M+Na]+, [M+NH4]+). This step operates after peak picking and sample alignment to consolidate redundant feature representations into molecular equivalence classes.
When to use
After sample alignment and peak picking have produced an aligned feature table with m/z and retention time coordinates. Use this skill when your untargeted LC-MS workflow requires deconvolution of isotope and adduct variants into single molecular entities for downstream annotation and quantification. Essential when downstream analysis (e.g., gap-filling, MS2 consolidation) expects non-redundant feature lists.
When NOT to use
- Input is already a consolidated feature table with isotopologues and adducts pre-grouped
- Analysis requires retention of all adduct and isotope variants separately (e.g., for adduct-specific quantification or ion suppression studies)
- Data are profile-mode (non-centroided) mzML; SLAW requires centroided input and will skip processing
Inputs
- aligned feature table (m/z × retention time matrix from sample alignment step)
- feature coordinates (m/z and RT values for detected peaks)
- mass tolerance parameters (ppm or Da) for isotope/adduct matching
Outputs
- grouped feature table with isotopologue/adduct cluster identifiers
- cluster membership assignments mapping features to canonical molecular ions
- cluster statistics (size, mass differences, RT variance)
How to apply
Load the aligned feature table output from the sample alignment step, which contains m/z and retention time coordinates for all detected peaks. Apply a clustering algorithm that identifies features differing by isotopic mass shifts (e.g., 1.003 Da for C13, 0.997 Da for N15) or adduct mass differences (e.g., 21.98 Da for [M+H]+ to [M+Na]+, 18.03 Da for [M+H]+ to [M+NH4]+). Assign cluster identifiers to group features by molecular ion identity, accounting for typical mass tolerance windows used in the alignment step. Output a grouped feature table with isotopologue/adduct cluster membership annotations. Verification relies on inspecting cluster sizes, mass difference distributions within clusters, and retention time clustering (isotopologues and adducts must co-elute).
Related tools
Evaluation signals
- All features within a cluster have co-eluting retention times (RT variance < alignment tolerance)
- Mass differences within clusters match expected isotopic shifts (C13 = 1.003 Da, N15 = 0.997 Da) or adduct transformations ([M+H]+ to [M+Na]+ = +21.98 Da)
- Cluster size distribution is reasonable (no artificially large clusters combining unrelated ions)
- Post-grouping feature count is lower than pre-grouping (redundancy removed)
- Gap-filling and downstream MS2 consolidation steps execute successfully without mass/RT mismatches
Limitations
- Requires centroided mzML input; profile-mode data will cause skip or failure
- Accuracy depends on mass tolerance and alignment precision from preceding steps; poor alignment propagates into incorrect cluster assignments
- Does not disambiguate between isotopologues and isobaric adducts with identical mass differences; retention time overlap is assumed to break ties
- Performance scales with feature table size; processing thousands of samples with SLAW requires automated parameter optimization enabled
Evidence
- [other] SLAW includes a processing step for grouping of isotopologues and adducts as part of its complete untargeted LC-MS workflow, which operates after peak picking and sample alignment.: "SLAW includes a processing step for grouping of isotopologues and adducts as part of its complete untargeted LC-MS workflow, which operates after peak picking and sample alignment."
- [other] Apply isotopologue and adduct grouping algorithm to cluster features sharing the same molecular ion with mass differences corresponding to isotopic shifts (e.g., C13, N15, D) or common adduct transformations (e.g., [M+H]+, [M+Na]+, [M+NH4]+).: "Apply isotopologue and adduct grouping algorithm to cluster features sharing the same molecular ion with mass differences corresponding to isotopic shifts (e.g., C13, N15, D) or common adduct"
- [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: "Complete processing including peak picking, sample alignment, pick picking, grouping of isotopologues and adducts, gap-filling by data recursion, extraction of consolidated MS2 spectra"
- [readme] All data must be centroided and of unique polarity. Centroided mzML can be obtained with ProteoWizard.: "All data must be centroided and of unique polarity. Centroided mzML can be obtained with ProteoWizard."
1---2name: isotopologue-adduct-cluster-assignment3description: Use when after sample alignment and peak picking have produced an aligned feature table with m/z and retention time coordinates.4license: CC-BY-4.05---67# isotopologue-adduct-cluster-assignment89## Summary1011Groups detected LC-MS features into isotopologue and adduct clusters by clustering features that share the same molecular ion and mass differences corresponding to isotopic shifts (C13, N15, D) or common adduct transformations ([M+H]+, [M+Na]+, [M+NH4]+). This step operates after peak picking and sample alignment to consolidate redundant feature representations into molecular equivalence classes.1213## When to use1415After sample alignment and peak picking have produced an aligned feature table with m/z and retention time coordinates. Use this skill when your untargeted LC-MS workflow requires deconvolution of isotope and adduct variants into single molecular entities for downstream annotation and quantification. Essential when downstream analysis (e.g., gap-filling, MS2 consolidation) expects non-redundant feature lists.1617## When NOT to use1819- Input is already a consolidated feature table with isotopologues and adducts pre-grouped20- Analysis requires retention of all adduct and isotope variants separately (e.g., for adduct-specific quantification or ion suppression studies)21- Data are profile-mode (non-centroided) mzML; SLAW requires centroided input and will skip processing2223## Inputs2425- aligned feature table (m/z × retention time matrix from sample alignment step)26- feature coordinates (m/z and RT values for detected peaks)27- mass tolerance parameters (ppm or Da) for isotope/adduct matching2829## Outputs3031- grouped feature table with isotopologue/adduct cluster identifiers32- cluster membership assignments mapping features to canonical molecular ions33- cluster statistics (size, mass differences, RT variance)3435## How to apply3637Load the aligned feature table output from the sample alignment step, which contains m/z and retention time coordinates for all detected peaks. Apply a clustering algorithm that identifies features differing by isotopic mass shifts (e.g., 1.003 Da for C13, 0.997 Da for N15) or adduct mass differences (e.g., 21.98 Da for [M+H]+ to [M+Na]+, 18.03 Da for [M+H]+ to [M+NH4]+). Assign cluster identifiers to group features by molecular ion identity, accounting for typical mass tolerance windows used in the alignment step. Output a grouped feature table with isotopologue/adduct cluster membership annotations. Verification relies on inspecting cluster sizes, mass difference distributions within clusters, and retention time clustering (isotopologues and adducts must co-elute).3839## Related tools4041- **SLAW grouping module** (Performs isotopologue and adduct clustering as a dedicated processing step within the complete SLAW workflow) — https://github.com/zamboni-lab/SLAW42- **Centwave** (Peak picking algorithm whose output (aligned features) feeds into the grouping module) — https://github.com/zamboni-lab/SLAW4344## Evaluation signals4546- All features within a cluster have co-eluting retention times (RT variance < alignment tolerance)47- Mass differences within clusters match expected isotopic shifts (C13 = 1.003 Da, N15 = 0.997 Da) or adduct transformations ([M+H]+ to [M+Na]+ = +21.98 Da)48- Cluster size distribution is reasonable (no artificially large clusters combining unrelated ions)49- Post-grouping feature count is lower than pre-grouping (redundancy removed)50- Gap-filling and downstream MS2 consolidation steps execute successfully without mass/RT mismatches5152## Limitations5354- Requires centroided mzML input; profile-mode data will cause skip or failure55- Accuracy depends on mass tolerance and alignment precision from preceding steps; poor alignment propagates into incorrect cluster assignments56- Does not disambiguate between isotopologues and isobaric adducts with identical mass differences; retention time overlap is assumed to break ties57- Performance scales with feature table size; processing thousands of samples with SLAW requires automated parameter optimization enabled5859## Evidence6061- [other] SLAW includes a processing step for grouping of isotopologues and adducts as part of its complete untargeted LC-MS workflow, which operates after peak picking and sample alignment.: "SLAW includes a processing step for grouping of isotopologues and adducts as part of its complete untargeted LC-MS workflow, which operates after peak picking and sample alignment."62- [other] Apply isotopologue and adduct grouping algorithm to cluster features sharing the same molecular ion with mass differences corresponding to isotopic shifts (e.g., C13, N15, D) or common adduct transformations (e.g., [M+H]+, [M+Na]+, [M+NH4]+).: "Apply isotopologue and adduct grouping algorithm to cluster features sharing the same molecular ion with mass differences corresponding to isotopic shifts (e.g., C13, N15, D) or common adduct"63- [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: "Complete processing including peak picking, sample alignment, pick picking, grouping of isotopologues and adducts, gap-filling by data recursion, extraction of consolidated MS2 spectra"64- [readme] All data must be centroided and of unique polarity. Centroided mzML can be obtained with ProteoWizard.: "All data must be centroided and of unique polarity. Centroided mzML can be obtained with ProteoWizard."
HolobiomicsLab 