r-bioconductor-workflow-orchestration
Summary
Orchestrate multi-step LC/MS metabolomics pipelines in R by chaining Bioconductor packages (XCMS, geoRge) with explicit sample class annotations and parameter passing to detect stable isotope-labeled metabolic features. This skill chains peak detection, alignment, and isotope-enrichment inference into a reproducible workflow.
When to use
You have untargeted LC/MS metabolomics data from stable isotope labeling experiments (e.g., 13C-glucose vs. 12C-glucose) already converted to mzXML format, and you need to systematically identify putatively incorporated metabolic features by comparing unlabeled and labeled sample groups. Use this when you have replicate sample cohorts (e.g., 6 unlabeled, 6 labeled) that require coordinated XCMS preprocessing followed by isotope-aware feature detection.
When NOT to use
- Input is already a processed feature abundance table or pre-filtered peak list — XCMS preprocessing (peak picking, alignment, grouping) is required upstream
- Sample metadata lacks clear unlabeled–labeled class distinction or replicates are unpaired/unbalanced — the workflow assumes replicated cohorts for valid statistical testing
- LC/MS data originates from targeted (SRM/MRM) or data-dependent acquisition (DDA) methods rather than untargeted full-scan — geoRge is designed for untargeted metabolomics mass traces
Inputs
- XCMS peak detection object (XCMSet) with aligned and grouped features from mzXML LC/MS data
- Sample metadata mapping sample names to unlabeled or labeled class labels (string tags, e.g. 'CELL_Glc12', 'CELL_Glc13')
- Replicate cohort structure (minimum 2 groups with ≥2 replicates each for statistical comparison)
Outputs
- PuIncR data structure: ranked list of features with fold-change, p-value, and putative incorporation flags
- Basepeak results: isotope-annotated features mapped to monoisotopic peaks with mass error (ppm) and confidence metrics
- Database query hits (optional downstream): matched metabolite identities from spectral/structural databases
How to apply
Begin by loading XCMS-processed peak data (via the data(mtbls213) pattern or custom XCMS object) into R. Set sample class annotations to distinguish unlabeled (e.g., CELL_Glc12_05mM_Normo) from labeled (e.g., CELL_Glc13_05mM_Normo) replicates using the metadata slot. Then execute PuInc_seeker with matched XCMSet, ULtag, and Ltag parameters, applying fold-change (default 1.5), p-value (default 0.05), and intensity thresholds (e.g., PuInc.int.lim=4000) to filter features with statistically significant and biologically meaningful differences between groups. Chain the output to basepeak_finder to resolve putative incorporations to their likely base peaks using atomic mass (UL.atomM=12.0, L.atomM=13.003355) and mass accuracy (ppm.s=6.5). This ordered chaining ensures coherent parameter propagation and avoids re-reading raw data.
Related tools
Examples
library(geoRge); data(mtbls213); s1 <- PuInc_seeker(XCMSet=mtbls213, ULtag="CELL_Glc12", Ltag="CELL_Glc13", sep.pos.front=TRUE, fc.threshold=1.5, p.value.threshold=0.05, PuInc.int.lim=4000); s2 <- basepeak_finder(PuIncR=s1, XCMSet=mtbls213, UL.atomM=12.0, L.atomM=13.003355, ppm.s=6.5, Basepeak.minInt=2000)
Evaluation signals
- PuIncR output contains non-empty ranked feature table with fold-change ≥ 1.5 and p-value ≤ 0.05, confirming statistical filtering was applied
- Basepeak_finder mass error (ppm) values fall within specified tolerance (e.g., ≤ 6.5 ppm for input ppm.s=6.5), validating isotope-to-monoisotopic mapping precision
- Putative incorporation intensity for flagged features exceeds the specified intensity limit (e.g., ≥ 4000 for PuInc.int.lim=4000), confirming intensity thresholding
- Number of output features is substantially smaller than input XCMSet features, reflecting expected filtering stringency for stable isotope signals
- Replicate fold-change consistency: compare PuIncR fold-changes across replicates or cross-validation splits to ensure robustness of isotope detection
Limitations
- Requires clear, replicated sample cohort structure — unpaired or single-replicate designs cannot be statistically validated by the p-value threshold
- Fixed threshold parameters (fold-change=1.5, p-value=0.05, intensity=4000) may be suboptimal for datasets with different dynamic ranges or noise profiles; user customization needed
- Assumes XCMS preprocessing has already been completed with appropriate retention-time alignment and peak grouping; misalignment upstream invalidates downstream isotope detection
- No built-in handling of confounding natural isotope distributions (e.g., 13C background in unlabeled samples) beyond mass accuracy filtering — high natural abundance isotopes may inflate false positives
- geoRge 1.0 reduced function arguments ('less tiring to use') but may introduce breaking changes if older scripts use deprecated parameter names; see help(function) documentation
Evidence
- [intro] Workflow overview and chaining rationale: "s1 <- PuInc_seeker(XCMSet=mtbls213,ULtag="CELL_Glc12",Ltag="CELL_Glc13", sep.pos.front=TRUE ,fc.threshold=1.5,p.value.threshold=.05,PuInc.int.lim = 4000)"
- [methods] XCMS preprocessing requirement: "Use XCMS package (https://bioconductor.org/packages/release/bioc/html/xcms.html) for peak picking, alignment and grouping"
- [intro] Basepeak_finder chaining and mass accuracy parameters: "s2 <- basepeak_finder(PuIncR = s1, XCMSet = mtbls213, UL.atomM=12.0,L.atomM=13.003355, ppm.s=6.5,Basepeak.minInt=2000)"
- [readme] Installation and library loading in R: "install_github("jcapelladesto/geoRge")
library(geoRge)"
- [readme] geoRge 1.0 documentation and parameter simplification: "I have updated the functions so they are less tiring to use. Check
help(function) to see the new arguments and function usage"
- [methods] Core skill application: isotope-enriched feature detection rationale: "Set sample class annotations to distinguish CELL_Glc12_05mM_Normo (unlabelled, 6 replicates) from CELL_Glc13_05mM_Normo (labelled, 6 replicates)"
1---2name: r-bioconductor-workflow-orchestration3description: Use when you have untargeted LC/MS metabolomics data from stable isotope labeling experiments (e.g., 13C-glucose vs. 12C-glucose) already converted to mzXML format, and you need to systematically identify putatively incorporated metabolic features by comparing unlabeled and labeled sample groups.4license: CC-BY-4.05---67# r-bioconductor-workflow-orchestration89## Summary1011Orchestrate multi-step LC/MS metabolomics pipelines in R by chaining Bioconductor packages (XCMS, geoRge) with explicit sample class annotations and parameter passing to detect stable isotope-labeled metabolic features. This skill chains peak detection, alignment, and isotope-enrichment inference into a reproducible workflow.1213## When to use1415You have untargeted LC/MS metabolomics data from stable isotope labeling experiments (e.g., 13C-glucose vs. 12C-glucose) already converted to mzXML format, and you need to systematically identify putatively incorporated metabolic features by comparing unlabeled and labeled sample groups. Use this when you have replicate sample cohorts (e.g., 6 unlabeled, 6 labeled) that require coordinated XCMS preprocessing followed by isotope-aware feature detection.1617## When NOT to use1819- Input is already a processed feature abundance table or pre-filtered peak list — XCMS preprocessing (peak picking, alignment, grouping) is required upstream20- Sample metadata lacks clear unlabeled–labeled class distinction or replicates are unpaired/unbalanced — the workflow assumes replicated cohorts for valid statistical testing21- LC/MS data originates from targeted (SRM/MRM) or data-dependent acquisition (DDA) methods rather than untargeted full-scan — geoRge is designed for untargeted metabolomics mass traces2223## Inputs2425- XCMS peak detection object (XCMSet) with aligned and grouped features from mzXML LC/MS data26- Sample metadata mapping sample names to unlabeled or labeled class labels (string tags, e.g. 'CELL_Glc12', 'CELL_Glc13')27- Replicate cohort structure (minimum 2 groups with ≥2 replicates each for statistical comparison)2829## Outputs3031- PuIncR data structure: ranked list of features with fold-change, p-value, and putative incorporation flags32- Basepeak results: isotope-annotated features mapped to monoisotopic peaks with mass error (ppm) and confidence metrics33- Database query hits (optional downstream): matched metabolite identities from spectral/structural databases3435## How to apply3637Begin by loading XCMS-processed peak data (via the `data(mtbls213)` pattern or custom XCMS object) into R. Set sample class annotations to distinguish unlabeled (e.g., CELL_Glc12_05mM_Normo) from labeled (e.g., CELL_Glc13_05mM_Normo) replicates using the metadata slot. Then execute PuInc_seeker with matched XCMSet, ULtag, and Ltag parameters, applying fold-change (default 1.5), p-value (default 0.05), and intensity thresholds (e.g., PuInc.int.lim=4000) to filter features with statistically significant and biologically meaningful differences between groups. Chain the output to basepeak_finder to resolve putative incorporations to their likely base peaks using atomic mass (UL.atomM=12.0, L.atomM=13.003355) and mass accuracy (ppm.s=6.5). This ordered chaining ensures coherent parameter propagation and avoids re-reading raw data.3839## Related tools4041- **XCMS** (Peak picking, alignment, and grouping of LC/MS features from raw mzXML; produces the XCMSet input object) — https://bioconductor.org/packages/release/bioc/html/xcms.html42- **geoRge** (Stable isotope labeling detection; provides PuInc_seeker, basepeak_finder, and database_query functions for isotope-enrichment workflow) — https://github.com/jcapelladesto/geoRge43- **devtools** (R package installation from GitHub repositories)44- **R** (Statistical computation and workflow orchestration environment)4546## Examples4748```49library(geoRge); data(mtbls213); s1 <- PuInc_seeker(XCMSet=mtbls213, ULtag="CELL_Glc12", Ltag="CELL_Glc13", sep.pos.front=TRUE, fc.threshold=1.5, p.value.threshold=0.05, PuInc.int.lim=4000); s2 <- basepeak_finder(PuIncR=s1, XCMSet=mtbls213, UL.atomM=12.0, L.atomM=13.003355, ppm.s=6.5, Basepeak.minInt=2000)50```5152## Evaluation signals5354- PuIncR output contains non-empty ranked feature table with fold-change ≥ 1.5 and p-value ≤ 0.05, confirming statistical filtering was applied55- Basepeak_finder mass error (ppm) values fall within specified tolerance (e.g., ≤ 6.5 ppm for input ppm.s=6.5), validating isotope-to-monoisotopic mapping precision56- Putative incorporation intensity for flagged features exceeds the specified intensity limit (e.g., ≥ 4000 for PuInc.int.lim=4000), confirming intensity thresholding57- Number of output features is substantially smaller than input XCMSet features, reflecting expected filtering stringency for stable isotope signals58- Replicate fold-change consistency: compare PuIncR fold-changes across replicates or cross-validation splits to ensure robustness of isotope detection5960## Limitations6162- Requires clear, replicated sample cohort structure — unpaired or single-replicate designs cannot be statistically validated by the p-value threshold63- Fixed threshold parameters (fold-change=1.5, p-value=0.05, intensity=4000) may be suboptimal for datasets with different dynamic ranges or noise profiles; user customization needed64- Assumes XCMS preprocessing has already been completed with appropriate retention-time alignment and peak grouping; misalignment upstream invalidates downstream isotope detection65- No built-in handling of confounding natural isotope distributions (e.g., 13C background in unlabeled samples) beyond mass accuracy filtering — high natural abundance isotopes may inflate false positives66- geoRge 1.0 reduced function arguments ('less tiring to use') but may introduce breaking changes if older scripts use deprecated parameter names; see help(function) documentation6768## Evidence6970- [intro] Workflow overview and chaining rationale: "s1 <- PuInc_seeker(XCMSet=mtbls213,ULtag="CELL_Glc12",Ltag="CELL_Glc13", sep.pos.front=TRUE ,fc.threshold=1.5,p.value.threshold=.05,PuInc.int.lim = 4000)"71- [methods] XCMS preprocessing requirement: "Use XCMS package (https://bioconductor.org/packages/release/bioc/html/xcms.html) for peak picking, alignment and grouping"72- [intro] Basepeak_finder chaining and mass accuracy parameters: "s2 <- basepeak_finder(PuIncR = s1, XCMSet = mtbls213, UL.atomM=12.0,L.atomM=13.003355, ppm.s=6.5,Basepeak.minInt=2000)"73- [readme] Installation and library loading in R: "install_github("jcapelladesto/geoRge")74library(geoRge)"75- [readme] geoRge 1.0 documentation and parameter simplification: "I have updated the functions so they are less tiring to use. Check `help(function)` to see the new arguments and function usage"76- [methods] Core skill application: isotope-enriched feature detection rationale: "Set sample class annotations to distinguish CELL_Glc12_05mM_Normo (unlabelled, 6 replicates) from CELL_Glc13_05mM_Normo (labelled, 6 replicates)"
HolobiomicsLab 