isotope-and-adduct-pattern-recognition
License: restricted — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution.
Summary
Identifies and groups related mass tracks by recognizing characteristic m/z differences corresponding to 13C/12C isotopes, sodium/hydrogen (Na/H) adducts, and other mass-pattern relationships. This anchors mass tracks to a common neutral mass, reducing redundancy and improving feature annotation in high-resolution LC-MS metabolomics.
When to use
When processing MS1 mass tracks from a single sample and you have already constructed per-bin mass tracks with consensus m/z and intensity vectors. Apply this skill to annotate groups of co-eluting ions that share the same or closely-related retention time profile but differ in m/z by known isotope ratios (13C offset ≈ 1.003 amu) or adduct mass shifts (Na vs H ≈ 22 amu). This is essential when feature redundancy from isotopologues or multiply-charged/adducted species would otherwise inflate the final feature table.
When NOT to use
- Input is already a deduplicated feature table; this skill operates on raw mass tracks before final feature selection.
- MS/MS data or ion-pairing databases are not available and you require higher confidence in adduct assignment; pattern recognition alone may be ambiguous.
- Sample retention time is so short or instrument resolution so low that isotope/adduct clusters cannot be resolved; operate at lower mass resolution (< 50k FWHM) or very high scan-rate scenarios.
Inputs
- per-sample mass tracks (list of (consensus_mz, intensity_vector, retention_time_range) tuples)
- instrument mass accuracy specification (ppm tolerance, e.g., 5 ppm)
- reference adduct/isotope mass-shift library (13C offset, Na/H difference, etc.)
Outputs
- isotope/adduct-annotated mass tracks (with relationship tags and inferred neutral mass)
- reduced feature set (anchor tracks only, with secondary tracks labeled)
- mass pattern validation metrics (observed vs. expected abundance ratios, mass error in ppm)
How to apply
After mass track construction, compute pairwise m/z differences between all tracks co-eluting in the same retention-time window. Screen these differences against a library of known mass shifts: 13C/12C isotope patterns (1.003355 amu per carbon, typically seen as +1.003 in singly-charged species), Na–H substitution (+21.982 amu), and other common adducts. For each observed m/z difference within instrument mass accuracy (typically ≤ 5 ppm for Orbitrap), cluster tracks into isotopic families or adduct families. Use intensity ratios and expected natural abundance patterns (e.g., ~1.1% per 12C for a single 13C substitution) to validate suspected 13C peaks. Establish a primary (lightest, or most intense) track as the anchor and tag secondary tracks with their relationship type (e.g., '[M+Na]+', '[M+13C]+'). This reduces downstream redundancy and aids structural annotation by inferring neutral mass from the anchor track.
Related tools
- pymzml (Parses mzML files to retrieve MS1 spectra and reconstruct mass track m/z values)
- khipu (Pre-annotation tool to group ions (including isotopologues and adducts) into empirical compounds and infer neutral mass) — https://github.com/shuzhao-li-lab/khipu
- mass2chem (Provides utility functions for adduct calculation and libraries of mass patterns for isotopologues and in-source fragments) — https://github.com/shuzhao-li/mass2chem
- asari (Orchestrates mass track construction and supplies filter/evaluation functions; isotope/adduct anchor identification is a built-in feature) — https://github.com/shuzhao-li/asari
Examples
from asari.chromatograms import extract_massTracks_; from mass2chem import adduct_calc; mass_tracks = extract_massTracks_(sample_data); anchored_tracks = identify_anchor_mass_tracks(mass_tracks, mass_shift_library={'13C': 1.003355, 'Na_H': 21.982}, ppm_tol=5)
Evaluation signals
- Isotope-cluster abundance ratios match theoretical natural-abundance expectations (e.g., 13C at ~1.1% of 12C for singly-charged peaks).
- All anchor tracks are assigned and secondary tracks are correctly tagged with their relationship type (13C, Na/H, etc.) and retain m/z differences within instrument tolerance (≤ 5 ppm).
- Co-elution of anchors and secondaries is verified: retention-time ranges overlap or differ by < 1 scan at typical LC timescales.
- No duplicate features in the final feature table for the same neutral mass; feature count is reduced relative to pre-grouping mass track count.
- Neutral mass inferred from anchor tracks is consistent with database queries (e.g., HMDB lookup succeeds) and MS/MS annotation (if available).
Limitations
- Ambiguity when m/z differences from different mass shifts (e.g., 13C vs. a different adduct) occupy overlapping windows; requires intensity ratio and chromatographic context to disambiguate.
- Low-abundance isotopologues or multiply-charged species may fall below the detection threshold and not be recognized; depends on minimum intensity threshold.
- In regions of very high peak density (e.g., lipid-rich samples with many isobaric species), clustering can merge unrelated mass tracks if retention times are close; user may need to adjust m/z or RT window tolerances.
- Performance depends on accurate prior construction of individual mass tracks; errors in consensus m/z or intensity vector propagate into adduct/isotope grouping.
Evidence
- [other] Establish anchor mass tracks by identifying m/z differences matching 13C/12C isotopes or Na/H adducts.: "Establish anchor mass tracks by identifying m/z differences matching 13C/12C isotopes or Na/H adducts."
- [readme] Pre-annotation tool to annotate degenerate ions in relationships to the original compound and infer neutral mass.: "Pre-annotation tool to annotate degenerate ions in relationships to the original compound and infer neutral mass."
- [readme] provides functions on handling chemical formulas, formula based adduct calculation, indexing and search functions on mass spec data, libraries of common metabolites, contaminants, mass differences: "provides functions on handling chemical formulas, formula based adduct calculation, indexing and search functions on mass spec data, libraries of common metabolites, contaminants, mass differences"
- [intro] Taking advantage of high mass resolution to prioritize mass separation and alignment: "Taking advantage of high mass resolution to prioritize mass separation and alignment"
1---2name: isotope-and-adduct-pattern-recognition-23description: Use when when processing MS1 mass tracks from a single sample and you have already constructed per-bin mass tracks with consensus m/z and intensity vectors.4license: CC-BY-4.05---67# isotope-and-adduct-pattern-recognition89> **License: restricted** — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution. <!-- asb-license-banner -->10## Summary1112Identifies and groups related mass tracks by recognizing characteristic m/z differences corresponding to 13C/12C isotopes, sodium/hydrogen (Na/H) adducts, and other mass-pattern relationships. This anchors mass tracks to a common neutral mass, reducing redundancy and improving feature annotation in high-resolution LC-MS metabolomics.1314## When to use1516When processing MS1 mass tracks from a single sample and you have already constructed per-bin mass tracks with consensus m/z and intensity vectors. Apply this skill to annotate groups of co-eluting ions that share the same or closely-related retention time profile but differ in m/z by known isotope ratios (13C offset ≈ 1.003 amu) or adduct mass shifts (Na vs H ≈ 22 amu). This is essential when feature redundancy from isotopologues or multiply-charged/adducted species would otherwise inflate the final feature table.1718## When NOT to use1920- Input is already a deduplicated feature table; this skill operates on raw mass tracks before final feature selection.21- MS/MS data or ion-pairing databases are not available and you require higher confidence in adduct assignment; pattern recognition alone may be ambiguous.22- Sample retention time is so short or instrument resolution so low that isotope/adduct clusters cannot be resolved; operate at lower mass resolution (< 50k FWHM) or very high scan-rate scenarios.2324## Inputs2526- per-sample mass tracks (list of (consensus_mz, intensity_vector, retention_time_range) tuples)27- instrument mass accuracy specification (ppm tolerance, e.g., 5 ppm)28- reference adduct/isotope mass-shift library (13C offset, Na/H difference, etc.)2930## Outputs3132- isotope/adduct-annotated mass tracks (with relationship tags and inferred neutral mass)33- reduced feature set (anchor tracks only, with secondary tracks labeled)34- mass pattern validation metrics (observed vs. expected abundance ratios, mass error in ppm)3536## How to apply3738After mass track construction, compute pairwise m/z differences between all tracks co-eluting in the same retention-time window. Screen these differences against a library of known mass shifts: 13C/12C isotope patterns (1.003355 amu per carbon, typically seen as +1.003 in singly-charged species), Na–H substitution (+21.982 amu), and other common adducts. For each observed m/z difference within instrument mass accuracy (typically ≤ 5 ppm for Orbitrap), cluster tracks into isotopic families or adduct families. Use intensity ratios and expected natural abundance patterns (e.g., ~1.1% per 12C for a single 13C substitution) to validate suspected 13C peaks. Establish a primary (lightest, or most intense) track as the anchor and tag secondary tracks with their relationship type (e.g., '[M+Na]+', '[M+13C]+'). This reduces downstream redundancy and aids structural annotation by inferring neutral mass from the anchor track.3940## Related tools4142- **pymzml** (Parses mzML files to retrieve MS1 spectra and reconstruct mass track m/z values)43- **khipu** (Pre-annotation tool to group ions (including isotopologues and adducts) into empirical compounds and infer neutral mass) — https://github.com/shuzhao-li-lab/khipu44- **mass2chem** (Provides utility functions for adduct calculation and libraries of mass patterns for isotopologues and in-source fragments) — https://github.com/shuzhao-li/mass2chem45- **asari** (Orchestrates mass track construction and supplies filter/evaluation functions; isotope/adduct anchor identification is a built-in feature) — https://github.com/shuzhao-li/asari4647## Examples4849```50from asari.chromatograms import extract_massTracks_; from mass2chem import adduct_calc; mass_tracks = extract_massTracks_(sample_data); anchored_tracks = identify_anchor_mass_tracks(mass_tracks, mass_shift_library={'13C': 1.003355, 'Na_H': 21.982}, ppm_tol=5)51```5253## Evaluation signals5455- Isotope-cluster abundance ratios match theoretical natural-abundance expectations (e.g., 13C at ~1.1% of 12C for singly-charged peaks).56- All anchor tracks are assigned and secondary tracks are correctly tagged with their relationship type (13C, Na/H, etc.) and retain m/z differences within instrument tolerance (≤ 5 ppm).57- Co-elution of anchors and secondaries is verified: retention-time ranges overlap or differ by < 1 scan at typical LC timescales.58- No duplicate features in the final feature table for the same neutral mass; feature count is reduced relative to pre-grouping mass track count.59- Neutral mass inferred from anchor tracks is consistent with database queries (e.g., HMDB lookup succeeds) and MS/MS annotation (if available).6061## Limitations6263- Ambiguity when m/z differences from different mass shifts (e.g., 13C vs. a different adduct) occupy overlapping windows; requires intensity ratio and chromatographic context to disambiguate.64- Low-abundance isotopologues or multiply-charged species may fall below the detection threshold and not be recognized; depends on minimum intensity threshold.65- In regions of very high peak density (e.g., lipid-rich samples with many isobaric species), clustering can merge unrelated mass tracks if retention times are close; user may need to adjust m/z or RT window tolerances.66- Performance depends on accurate prior construction of individual mass tracks; errors in consensus m/z or intensity vector propagate into adduct/isotope grouping.6768## Evidence6970- [other] Establish anchor mass tracks by identifying m/z differences matching 13C/12C isotopes or Na/H adducts.: "Establish anchor mass tracks by identifying m/z differences matching 13C/12C isotopes or Na/H adducts."71- [readme] Pre-annotation tool to annotate degenerate ions in relationships to the original compound and infer neutral mass.: "Pre-annotation tool to annotate degenerate ions in relationships to the original compound and infer neutral mass."72- [readme] provides functions on handling chemical formulas, formula based adduct calculation, indexing and search functions on mass spec data, libraries of common metabolites, contaminants, mass differences: "provides functions on handling chemical formulas, formula based adduct calculation, indexing and search functions on mass spec data, libraries of common metabolites, contaminants, mass differences"73- [intro] Taking advantage of high mass resolution to prioritize mass separation and alignment: "Taking advantage of high mass resolution to prioritize mass separation and alignment"
HolobiomicsLab