metabolite-feature-association-across-labels
Summary
Identify base-peak isotopologue groupings from putative stable isotope incorporations by linking enriched features across unlabeled and labeled sample cohorts using atomic mass differences and mass accuracy constraints. This skill bridges isotope-tagged metabolite detection to metabolite identification by establishing which m/z peaks correspond to the same molecular entity under different labeling conditions.
When to use
Apply this skill after PuInc_seeker has identified putative incorporations (m/z features showing significant fold-change and p-value signals between labeled and unlabeled sample groups) and you need to assign base peaks—the most intense isotopologue signals—and validate isotope-pair mass gaps match theoretical labeled/unlabeled atomic mass differences (e.g., 13C vs 12C = 1.003355 Da). Use when processing LC/MS untargeted metabolomics data with stable isotope labeling (e.g., 13C-glucose) and mass accuracy is ≤ 6.5 ppm.
When NOT to use
- Input data has not undergone PuInc_seeker filtering or lacks fold-change and p-value pre-filtering; basepeak_finder expects pre-validated putative incorporations, not raw peak lists.
- Sample cohorts lack clear labeled vs. unlabeled group separation or are missing one of the two labeling conditions; the function requires paired sample class tags (ULtag and Ltag) to establish isotope pairs.
- Mass accuracy of the LC/MS instrument is substantially worse than 6.5 ppm (e.g., low-resolution TOF or quadrupole data); isotope mass gaps smaller than ~1 Da cannot be reliably resolved.
Inputs
- geoRge object produced by PuInc_seeker (containing putative incorporation features with m/z, RT, fold-change, p-value, and sample class annotations)
- XCMS dataset (XCMSet object with peak-picked, aligned, and grouped features from unlabeled and labeled LC/MS runs)
Outputs
- geoRge object with base-peak isotopologue annotations (m/z, intensity, isotope-pair mass gaps, sample class tags)
- annotated feature list mapping base peaks to isotope siblings with validated mass accuracy
How to apply
Execute basepeak_finder on the output geoRge object from PuInc_seeker, specifying: unlabeled atomic mass (12.0), labeled atomic mass (13.003355), mass accuracy tolerance (6.5 ppm), and base-peak minimum intensity threshold (2000). The function scans each putative incorporation feature, locates the highest-intensity m/z signal within the tolerance window, validates that the mass gap between unlabeled and labeled isotopologue peaks matches the theoretical difference, and flags the peak pair as a confirmed base-peak association. Filter candidate peaks by intensity to eliminate noise; reject m/z pairs where the mass offset deviates beyond the specified ppm tolerance, as these indicate artifacts or distinct metabolites rather than isotope pairs. The resulting geoRge object annotates each base peak with m/z, intensity, and isotope-pair relationships, enabling downstream database queries and metabolite assignment.
Related tools
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
- Resulting geoRge object contains base-peak m/z values with intensity ≥ 2000 and non-null isotope-pair annotations (labeled m/z, unlabeled m/z, mass gap).
- Mass gap between each unlabeled–labeled m/z pair deviates from theoretical 13C–12C difference (1.003355 Da) by ≤ 6.5 ppm; computed as |observed_gap − 1.003355| / 1.003355 × 1e6 ≤ 6.5.
- All base-peak m/z entries retain sample class tags (ULtag and Ltag) matching input; no cross-contamination of labeled features into unlabeled group or vice versa.
- Intensity of base peaks in the identified isotope pairs is consistent with expected fold-change patterns from PuInc_seeker (labeled >> unlabeled for 13C incorporation, or vice versa depending on experimental design).
- Output geoRge object is suitable for downstream database_query without null or malformed isotope-pair fields; all m/z and intensity values are numeric and within biologically plausible ranges (e.g., 50–1500 m/z for small metabolites).
Limitations
- basepeak_finder assumes that the highest-intensity m/z within the tolerance window is the true base peak; in complex mixtures or isomeric features at similar m/z, this assumption may fail.
- Mass accuracy tolerance (6.5 ppm in the mtbls213 example) must be tuned to the specific LC/MS platform and may not be universally applicable; high-resolution instruments can use tighter tolerances, while low-resolution instruments may require relaxation.
- The function requires explicit paired sample class labeling (ULtag and Ltag); metabolomics datasets without clear unlabeled/labeled group annotation cannot be processed.
- Putative incorporations filtered by PuInc_seeker's fold-change (1.5×) and p-value (0.05) thresholds may miss weak labeling signals or low-abundance metabolites; downstream base-peak identification is limited by upstream filter stringency.
- No changelog is maintained in the geoRge repository, making version-to-version API changes difficult to track; users upgrading from geoRge 0.x to 1.0+ should verify function arguments via help(basepeak_finder).
Evidence
- [other] 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): "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)"
- [other] Apply basepeak_finder to the PuInc_seeker output with unlabelled atomic mass 12.0, labelled atomic mass 13.003355, mass accuracy tolerance 6.5 ppm, and base-peak minimum intensity threshold 2000, matching the same sample tags and position logic.: "Apply basepeak_finder to the PuInc_seeker output with unlabelled atomic mass 12.0, labelled atomic mass 13.003355, mass accuracy tolerance 6.5 ppm, and base-peak minimum intensity threshold 2000"
- [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"
- [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)"
- [readme] geoRge: a computational tool for stable isotope labelling detection in LC/MS-based untargeted metabolomics: "geoRge: a computational tool for stable isotope labelling detection in LC/MS-based untargeted metabolomics"
1---2name: metabolite-feature-association-across-labels3description: Use when after PuInc_seeker has identified putative incorporations (m/z features showing significant fold-change and p-value signals between labeled and unlabeled sample groups) and you need to assign base peaks—the most intense isotopologue signals—and validate isotope-pair mass gaps match.4license: CC-BY-4.05---67# metabolite-feature-association-across-labels89## Summary1011Identify base-peak isotopologue groupings from putative stable isotope incorporations by linking enriched features across unlabeled and labeled sample cohorts using atomic mass differences and mass accuracy constraints. This skill bridges isotope-tagged metabolite detection to metabolite identification by establishing which m/z peaks correspond to the same molecular entity under different labeling conditions.1213## When to use1415Apply this skill after PuInc_seeker has identified putative incorporations (m/z features showing significant fold-change and p-value signals between labeled and unlabeled sample groups) and you need to assign base peaks—the most intense isotopologue signals—and validate isotope-pair mass gaps match theoretical labeled/unlabeled atomic mass differences (e.g., 13C vs 12C = 1.003355 Da). Use when processing LC/MS untargeted metabolomics data with stable isotope labeling (e.g., 13C-glucose) and mass accuracy is ≤ 6.5 ppm.1617## When NOT to use1819- Input data has not undergone PuInc_seeker filtering or lacks fold-change and p-value pre-filtering; basepeak_finder expects pre-validated putative incorporations, not raw peak lists.20- Sample cohorts lack clear labeled vs. unlabeled group separation or are missing one of the two labeling conditions; the function requires paired sample class tags (ULtag and Ltag) to establish isotope pairs.21- Mass accuracy of the LC/MS instrument is substantially worse than 6.5 ppm (e.g., low-resolution TOF or quadrupole data); isotope mass gaps smaller than ~1 Da cannot be reliably resolved.2223## Inputs2425- geoRge object produced by PuInc_seeker (containing putative incorporation features with m/z, RT, fold-change, p-value, and sample class annotations)26- XCMS dataset (XCMSet object with peak-picked, aligned, and grouped features from unlabeled and labeled LC/MS runs)2728## Outputs2930- geoRge object with base-peak isotopologue annotations (m/z, intensity, isotope-pair mass gaps, sample class tags)31- annotated feature list mapping base peaks to isotope siblings with validated mass accuracy3233## How to apply3435Execute basepeak_finder on the output geoRge object from PuInc_seeker, specifying: unlabeled atomic mass (12.0), labeled atomic mass (13.003355), mass accuracy tolerance (6.5 ppm), and base-peak minimum intensity threshold (2000). The function scans each putative incorporation feature, locates the highest-intensity m/z signal within the tolerance window, validates that the mass gap between unlabeled and labeled isotopologue peaks matches the theoretical difference, and flags the peak pair as a confirmed base-peak association. Filter candidate peaks by intensity to eliminate noise; reject m/z pairs where the mass offset deviates beyond the specified ppm tolerance, as these indicate artifacts or distinct metabolites rather than isotope pairs. The resulting geoRge object annotates each base peak with m/z, intensity, and isotope-pair relationships, enabling downstream database queries and metabolite assignment.3637## Related tools3839- **geoRge** (Core R package providing basepeak_finder function to identify and annotate base-peak isotopologue groupings with mass accuracy and intensity filters) — https://github.com/jcapelladesto/geoRge40- **XCMS** (Upstream peak picking, alignment, and grouping of LC/MS features from raw mzXML files; produces XCMSet input object) — https://bioconductor.org/packages/release/bioc/html/xcms.html41- **R** (Execution environment for geoRge and downstream statistical/visualization workflows)4243## Examples4445```46s2 <- basepeak_finder(PuIncR = s1, XCMSet = mtbls213, UL.atomM=12.0, L.atomM=13.003355, ppm.s=6.5, Basepeak.minInt=2000)47```4849## Evaluation signals5051- Resulting geoRge object contains base-peak m/z values with intensity ≥ 2000 and non-null isotope-pair annotations (labeled m/z, unlabeled m/z, mass gap).52- Mass gap between each unlabeled–labeled m/z pair deviates from theoretical 13C–12C difference (1.003355 Da) by ≤ 6.5 ppm; computed as |observed_gap − 1.003355| / 1.003355 × 1e6 ≤ 6.5.53- All base-peak m/z entries retain sample class tags (ULtag and Ltag) matching input; no cross-contamination of labeled features into unlabeled group or vice versa.54- Intensity of base peaks in the identified isotope pairs is consistent with expected fold-change patterns from PuInc_seeker (labeled >> unlabeled for 13C incorporation, or vice versa depending on experimental design).55- Output geoRge object is suitable for downstream database_query without null or malformed isotope-pair fields; all m/z and intensity values are numeric and within biologically plausible ranges (e.g., 50–1500 m/z for small metabolites).5657## Limitations5859- basepeak_finder assumes that the highest-intensity m/z within the tolerance window is the true base peak; in complex mixtures or isomeric features at similar m/z, this assumption may fail.60- Mass accuracy tolerance (6.5 ppm in the mtbls213 example) must be tuned to the specific LC/MS platform and may not be universally applicable; high-resolution instruments can use tighter tolerances, while low-resolution instruments may require relaxation.61- The function requires explicit paired sample class labeling (ULtag and Ltag); metabolomics datasets without clear unlabeled/labeled group annotation cannot be processed.62- Putative incorporations filtered by PuInc_seeker's fold-change (1.5×) and p-value (0.05) thresholds may miss weak labeling signals or low-abundance metabolites; downstream base-peak identification is limited by upstream filter stringency.63- No changelog is maintained in the geoRge repository, making version-to-version API changes difficult to track; users upgrading from geoRge 0.x to 1.0+ should verify function arguments via help(basepeak_finder).6465## Evidence6667- [other] 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): "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)"68- [other] Apply basepeak_finder to the PuInc_seeker output with unlabelled atomic mass 12.0, labelled atomic mass 13.003355, mass accuracy tolerance 6.5 ppm, and base-peak minimum intensity threshold 2000, matching the same sample tags and position logic.: "Apply basepeak_finder to the PuInc_seeker output with unlabelled atomic mass 12.0, labelled atomic mass 13.003355, mass accuracy tolerance 6.5 ppm, and base-peak minimum intensity threshold 2000"69- [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"70- [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)"71- [readme] geoRge: a computational tool for stable isotope labelling detection in LC/MS-based untargeted metabolomics: "geoRge: a computational tool for stable isotope labelling detection in LC/MS-based untargeted metabolomics"
HolobiomicsLab