# Isotope And Adduct Pattern Recognition

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

- Skill: `holobiomicslab/isotope-and-adduct-pattern-recognition` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/isotope-and-adduct-pattern-recognition`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/isotope-and-adduct-pattern-recognition/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- 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/isotope-and-adduct-pattern-recognition

---


# isotope-and-adduct-pattern-recognition

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