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."
1---2name: mass-spectral-relationship-matching3description: 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.4license: CC-BY-4.05---67# mass-spectral-relationship-matching89## Summary1011Annotate 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.1213## When to use1415Apply 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.1617## When NOT to use1819- Input is already a grouped or curated metabolite list rather than raw detected features.20- Data from instruments or workflows where isotope envelopes or adduct formation are suppressed by design (e.g., some targeted methods with deliberate desalting).21- Feature table lacks reliable retention time information needed to enforce co-elution constraints.2223## Inputs2425- Feature table with m/z, retention time (RT), and intensity columns26- Detection parameters: isotope mass tolerance, adduct mass shifts, neutral loss patterns27- Retention time window threshold for co-elution2829## Outputs3031- Annotated feature table with group ID column32- Annotation label column (isotope, adduct, in-source fragment, or unrelated)33- Feature relationship network (implied by group membership)3435## How to apply3637Load 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.3839## Related tools4041- **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/4243## Evaluation signals4445- Every feature in the output table has been assigned a group ID and an annotation label (no missing or null values).46- 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.47- Isotope groups show monotonic intensity decrease from lighter to heavier isotopologues, consistent with natural abundance ratios.48- Adduct groups link the same molecular mass (M) under different ionization forms; verify by recalculating [M+adduct] for each member.49- In-source fragment groups show lower m/z and/or intensity compared to their parent feature, consistent with neutral loss mechanism.5051## Limitations5253- Accuracy depends on reliable m/z calibration and retention time alignment; poor peak detection or significant RT drift will confound relationship matching.54- 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.55- The skill is designed for nontargeted LC-MS data; targeted or data-independent acquisition (DIA) workflows may require adapted parameters or thresholds.5657## Evidence5859- [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."60- [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"61- [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."62- [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)."63- [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."
HolobiomicsLab 