# Mass Spectral Relationship Matching

> Use when after peak detection and feature table generation when you have a collection of m/z, retention time, and intensity values and need to identify which features are related variants (isotopes, adducts, or fragments) of the same parent compound.

- Skill: `holobiomicslab/mass-spectral-relationship-matching` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/mass-spectral-relationship-matching`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/mass-spectral-relationship-matching/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/mass-spectral-relationship-matching

---


# mass-spectral-relationship-matching

## Summary

Annotate and group LC-MS features as isotopes, adducts, or in-source fragments by matching mass shifts and neutral loss patterns within retention time windows. This skill enables confident assignment of feature relationships that reflect the same underlying molecular entity.

## When to use

Apply this skill after peak detection and feature table generation when you have a collection of m/z, retention time, and intensity values and need to identify which features are related variants (isotopes, adducts, or fragments) of the same parent compound. Use it as a prerequisite for downstream annotation and compound identification workflows where grouping related features improves molecular hypothesis confidence.

## When NOT to use

- Input is already a grouped or curated metabolite list rather than raw detected features.
- Data from instruments or workflows where isotope envelopes or adduct formation are suppressed by design (e.g., some targeted methods with deliberate desalting).
- Feature table lacks reliable retention time information needed to enforce co-elution constraints.

## Inputs

- Feature table with m/z, retention time (RT), and intensity columns
- Detection parameters: isotope mass tolerance, adduct mass shifts, neutral loss patterns
- Retention time window threshold for co-elution

## Outputs

- Annotated feature table with group ID column
- Annotation label column (isotope, adduct, in-source fragment, or unrelated)
- Feature relationship network (implied by group membership)

## How to apply

Load the detected feature table containing m/z, retention time, and intensity columns. Sequentially apply three relationship detection engines: (1) Isotope detection: identify features differing by ~1.003 Da (carbon-13 shift) within a retention time window to group isotope envelopes. (2) Adduct detection: match features related by known adduct mass shifts (+H, +Na, +NH4, +K, –H) to identify multiply-charged or adducted ions. (3) In-source fragment detection: match features related by characteristic neutral loss patterns (–H2O, –NH3) to capture in-source fragmentation relationships. Assign each feature a group ID and an annotation label (isotope, adduct, or fragment) based on the detected relationships, then output the annotated feature table with group membership preserved. The retention time co-elution constraint ensures only chemically plausible relationships are confirmed.

## Related tools

- **masscube** (Integrated Python package that implements isotope, adduct, and in-source fragment detection and grouping for LC-MS feature tables.) — https://github.com/huaxuyu/masscube/

## Evaluation signals

- Every feature in the output table has been assigned a group ID and an annotation label (no missing or null values).
- Features assigned to the same group share a plausible mass relationship (isotope ±1.003 Da, adduct ±expected shift, fragment via known neutral loss) and co-elute within the specified retention time window.
- Isotope groups show monotonic intensity decrease from lighter to heavier isotopologues, consistent with natural abundance ratios.
- Adduct groups link the same molecular mass (M) under different ionization forms; verify by recalculating [M+adduct] for each member.
- In-source fragment groups show lower m/z and/or intensity compared to their parent feature, consistent with neutral loss mechanism.

## Limitations

- Accuracy depends on reliable m/z calibration and retention time alignment; poor peak detection or significant RT drift will confound relationship matching.
- Overlapping retention time windows and similar mass shifts (e.g., adduct +Na vs. in-source loss of water on a heavier ion) can cause misassignment; manual review of high-confidence matches is recommended for downstream use.
- The skill is designed for nontargeted LC-MS data; targeted or data-independent acquisition (DIA) workflows may require adapted parameters or thresholds.

## Evidence

- [other] masscube implements a feature group annotation mechanism that confidently labels features as isotopes, adducts, and in-source fragments.: "masscube implements a feature group annotation mechanism that confidently labels features as isotopes, adducts, and in-source fragments."
- [other] Apply isotope detection logic to identify features differing by 1.003 Da (carbon-13 isotope shift) within a retention time window. Apply adduct detection to identify features related by common adduct mass shifts (e.g., +H, +Na, +NH4, +K, –H). Apply in-source fragment detection to identify features related by characteristic neutral loss patterns (e.g., –H2O, –NH3).: "Apply isotope detection logic to identify features differing by 1.003 Da (carbon-13 isotope shift) within a retention time window. Apply adduct detection to identify features related by common adduct"
- [readme] Confident annotation of feature groups including isotopes, adducts and in-source fragments.: "Confident annotation of feature groups including isotopes, adducts and in-source fragments."
- [other] Load the feature table (containing m/z, retention time, and intensity values for detected features).: "Load the feature table (containing m/z, retention time, and intensity values for detected features)."
- [other] Assign each feature a group ID and annotation label (isotope, adduct, or fragment) based on detected relationships.: "Assign each feature a group ID and annotation label (isotope, adduct, or fragment) based on detected relationships."