# Isotopologue Grouping By Mass Accuracy

> Use when after PuInc_seeker has identified putative incorporations in a stable-isotope-labeled LC/MS dataset (e.g., CELL_Glc12 unlabeled vs. CELL_Glc13 labeled samples).

- Skill: `holobiomicslab/isotopologue-grouping-by-mass-accuracy` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/isotopologue-grouping-by-mass-accuracy`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/isotopologue-grouping-by-mass-accuracy/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/isotopologue-grouping-by-mass-accuracy

---


# isotopologue-grouping-by-mass-accuracy

## Summary

Identify base-peak isotopologue groupings from putative stable-isotope incorporations by matching m/z pairs within specified mass accuracy tolerance and intensity thresholds. This skill links enriched features to their unlabeled and labeled isotope counterparts in LC/MS untargeted metabolomics.

## When to use

Apply this skill after PuInc_seeker has identified putative incorporations in a stable-isotope-labeled LC/MS dataset (e.g., CELL_Glc12 unlabeled vs. CELL_Glc13 labeled samples). Use it when you need to resolve base-peak isotopologue pairs from feature clusters, accounting for instrumental mass accuracy limits and signal intensity.

## When NOT to use

- Input has not been processed through PuInc_seeker; basepeak_finder requires putative incorporation annotations as input.
- XCMS peak picking, alignment, and grouping have not been completed; the XCMSet must be a fully processed feature matrix.
- Mass accuracy of the instrument is >6.5 ppm or unknown; the 6.5 ppm threshold is specific to the mtbls213 dataset and may require recalibration for other instruments or datasets.

## Inputs

- PuInc_seeker output (putative incorporation result object)
- XCMS peak group object (XCMSet)
- sample class labels (ULtag for unlabeled, Ltag for labeled)

## Outputs

- geoRge object with identified base-peak isotopologue groupings
- m/z-intensity pairs annotated with isotope assignment and sample origin

## How to apply

Execute the basepeak_finder function on PuInc_seeker output, specifying unlabeled atom mass (12.0 for carbon-12), labeled atom mass (13.003355 for carbon-13), mass accuracy tolerance (6.5 ppm for the mtbls213 dataset), and base-peak minimum intensity threshold (2000). The function matches m/z values between the two sample groups (ULtag and Ltag) using front-position logic to group isotopologue pairs. The algorithm filters out low-intensity noise and resolves ambiguous mass assignments by enforcing the ppm tolerance window. Validate output by confirming the geoRge object contains isotope-pair annotations with m/z, intensity, and sample-group tags intact.

## Related tools

- **geoRge** (Host R package providing basepeak_finder and related isotope-detection functions) — https://github.com/jcapelladesto/geoRge
- **XCMS** (Prerequisite peak picking, alignment, and grouping to produce the XCMSet input) — https://bioconductor.org/packages/release/bioc/html/xcms.html
- **R** (Execution environment for basepeak_finder function)

## Examples

```
s2 <- basepeak_finder(PuIncR = s1, XCMSet = mtbls213, UL.atomM=12.0, L.atomM=13.003355, ppm.s=6.5, Basepeak.minInt=2000)
```

## Evaluation signals

- Output geoRge object contains non-empty isotope-pair annotations with both m/z and intensity fields populated.
- All paired isotopologues fall within the specified mass accuracy tolerance (6.5 ppm) for the labeled–unlabeled mass difference.
- Base-peak intensities in the output are ≥2000, confirming the minimum intensity threshold was applied.
- Sample group tags (ULtag, Ltag) are correctly assigned to paired features, with no cross-contamination.
- Number of identified base peaks is consistent with the putative incorporation count from PuInc_seeker, accounting for p-value and fold-change filtering.

## Limitations

- Mass accuracy tolerance (6.5 ppm) is calibrated to the mtbls213 dataset; different instruments or chromatographic conditions may require recalibration.
- Minimum intensity threshold (2000) is dataset-specific and may suppress weak labeling signals in low-abundance metabolites.
- Requires preceding execution of PuInc_seeker; cannot operate on raw XCMS output without fold-change and p-value filtering.
- Front-position matching logic (sep.pos.front=TRUE) assumes stable retention-time alignment; misaligned peaks across samples may produce spurious or missed pairings.
- No changelog documented; version compatibility with recent XCMS and R versions unclear.

## Evidence

- [other] The basepeak_finder function operates on PuInc_seeker output and uses unlabeled atom mass (12.0), labeled atom mass (13.003355), mass accuracy tolerance (6.5 ppm), and minimum intensity threshold (2000) to identify base-peak isotopologue groupings: "The basepeak_finder function operates on PuInc_seeker output and uses unlabeled atom mass (12.0), labeled atom mass (13.003355), mass accuracy tolerance (6.5 ppm), and minimum intensity threshold"
- [other] Validate that the resulting geoRge object contains identified base peaks with m/z, intensity, and isotope-pair annotations.: "Validate that the resulting geoRge object contains identified base peaks with m/z, intensity, and isotope-pair annotations."
- [intro] basepeak_finder function to identify base peaks with specified mass accuracy and intensity thresholds: "basepeak_finder function to identify base peaks with specified mass accuracy and intensity thresholds"
- [readme] s2 <- basepeak_finder(PuIncR = s1, XCMSet = mtbls213, UL.atomM=12.0,L.atomM=13.003355, ppm.s=6.5,Basepeak.minInt=2000): "s2 <- basepeak_finder(PuIncR = s1, XCMSet = mtbls213, UL.atomM=12.0,L.atomM=13.003355, ppm.s=6.5,Basepeak.minInt=2000)"
- [methods] Use XCMS package (https://bioconductor.org/packages/release/bioc/html/xcms.html) for peak picking, alignment and grouping: "Use XCMS package (https://bioconductor.org/packages/release/bioc/html/xcms.html) for peak picking, alignment and grouping"