xcms-grouped-object-manipulation
Summary
Manipulate and refine feature groupings in XcmsExperiment objects by applying sequential grouping strategies (retention time, abundance correlation, EIC similarity) to reduce feature complexity and consolidate ions from the same compound. This skill is essential for LC-MS metabolomics workflows where multiple ions per compound must be grouped before annotation.
When to use
Apply this skill when you have preprocessed LC-MS data with detected chromatographic peaks that need to be consolidated into feature groups representing putative compounds. Use it if your goal is to reduce data complexity by clustering features with similar retention time, correlated abundance patterns, and/or similar extracted ion chromatogram (EIC) peak shapes. Typical trigger: output from findChromPeaks() contains hundreds to thousands of individual features that require consolidation before annotation or statistical analysis.
When NOT to use
- Input data has not yet undergone chromatographic peak detection (findChromPeaks).
- Feature grouping has already been completed and you only need to extract or visualize existing groups.
- Your analysis requires preservation of all individual peak detections without consolidation (e.g., when peak multiplicity per compound is itself a variable of interest).
Inputs
- XcmsExperiment object (xmse) with detected chromatographic peaks from findChromPeaks()
- SimilarRtimeParam, AbundanceSimilarityParam, or EicSimilarityParam parameter object
Outputs
- Grouped XcmsExperiment object with reduced feature group count
- Integer count of final distinct feature groups from featureGroups()
How to apply
Begin with a pre-processed XcmsExperiment object containing detected chromatographic peaks. Apply groupFeatures() sequentially with parameter objects tailored to your data: first use SimilarRtimeParam(window_seconds) to cluster features within a retention-time window (e.g., 20 seconds), then refine with AbundanceSimilarityParam(threshold, transform) to group features whose abundances are correlated across samples (e.g., threshold=0.7, log2 transform), and optionally further refine with EicSimilarityParam(threshold, n) to group by similarity of extracted ion chromatogram peak shapes using the top n samples per group (e.g., threshold=0.7, n=2). After each groupFeatures() call, extract the final group count using featureGroups() to verify consolidation. The rationale is that features of the same compound should co-elute, show correlated abundance patterns, and display similar peak shapes; successive refinement progressively enforces these properties.
Related tools
- xcms (Provides groupFeatures() function, SimilarRtimeParam, AbundanceSimilarityParam, EicSimilarityParam classes, and featureGroups() extraction method.) — https://github.com/sneumann/xcms
- MsFeatures (Defines general MS feature grouping functionality and parameter classes used by xcms.)
Examples
groupFeatures(xmse, param = EicSimilarityParam(threshold = 0.7, n = 2)); featureGroups(xmse)
Evaluation signals
- Final feature group count from featureGroups() is reduced compared to initial peak count (e.g., 2289 features grouped into 589 feature groups as in task_003).
- Each feature is assigned to exactly one feature group (no duplicates or unassigned features).
- Features within each group have retention times within the specified SimilarRtimeParam window.
- When AbundanceSimilarityParam is applied, abundance correlation between grouped features meets or exceeds the threshold (e.g., ≥0.7).
- When EicSimilarityParam is applied, EIC peak shapes of grouped features show visual or quantitative similarity as computed by the parameter object.
Limitations
- Sequential grouping is order-dependent; the order of applying SimilarRtimeParam, AbundanceSimilarityParam, and EicSimilarityParam can affect final group counts and membership.
- Parameter threshold selection (e.g., SimilarRtimeParam window, AbundanceSimilarityParam threshold, EicSimilarityParam threshold) requires domain knowledge and may benefit from exploratory analysis; no single universal threshold is provided.
- EicSimilarityParam(n=2) uses only the top n samples per group for peak shape comparison, which may underutilize samples with lower abundance or miss subtle peak shape differences in low-abundance samples.
- The method assumes that features of the same compound have correlated abundances; compounds with sample-dependent ion suppression or ionization efficiency changes may yield spurious groupings or false negatives.
Evidence
- [intro] Features (ions) of the same compound should have similar retention time, similar abundance patterns across samples, and similar peak shapes of extracted ion chromatograms: "Features (ions) of the same compound should have similar retention time, similar abundance patterns across samples, and similar peak shapes of extracted ion chromatograms"
- [intro] Compounding aims now at grouping such features presumably representing signal from the same originating compound to reduce data set complexity: "Compounding aims now at grouping such features presumably representing signal from the same originating compound to reduce data set complexity"
- [intro] groupFeatures() with EicSimilarityParam(threshold = 0.7, n = 2) to group features by similarity of extracted ion chromatogram peak shapes: "groupFeatures(xmse, EicSimilarityParam(threshold = 0.7, n = 2)) to group features by similarity of extracted ion chromatogram peak shapes"
- [other] Call groupFeatures() with EicSimilarityParam(threshold = 0.7, n = 2) to group features by similarity of extracted ion chromatogram peak shapes.: "Call groupFeatures() with EicSimilarityParam(threshold = 0.7, n = 2) to group features by similarity of extracted ion chromatogram peak shapes."
- [other] the 2289 features being grouped into 589 distinct feature groups: "The grouping based on EIC correlation resulted in the 2289 features being grouped into 589 distinct feature groups."
1---2name: xcms-grouped-object-manipulation3description: Use when you have preprocessed LC-MS data with detected chromatographic peaks that need to be consolidated into feature groups representing putative compounds.4license: CC-BY-4.05---67# xcms-grouped-object-manipulation89## Summary1011Manipulate and refine feature groupings in XcmsExperiment objects by applying sequential grouping strategies (retention time, abundance correlation, EIC similarity) to reduce feature complexity and consolidate ions from the same compound. This skill is essential for LC-MS metabolomics workflows where multiple ions per compound must be grouped before annotation.1213## When to use1415Apply this skill when you have preprocessed LC-MS data with detected chromatographic peaks that need to be consolidated into feature groups representing putative compounds. Use it if your goal is to reduce data complexity by clustering features with similar retention time, correlated abundance patterns, and/or similar extracted ion chromatogram (EIC) peak shapes. Typical trigger: output from findChromPeaks() contains hundreds to thousands of individual features that require consolidation before annotation or statistical analysis.1617## When NOT to use1819- Input data has not yet undergone chromatographic peak detection (findChromPeaks).20- Feature grouping has already been completed and you only need to extract or visualize existing groups.21- Your analysis requires preservation of all individual peak detections without consolidation (e.g., when peak multiplicity per compound is itself a variable of interest).2223## Inputs2425- XcmsExperiment object (xmse) with detected chromatographic peaks from findChromPeaks()26- SimilarRtimeParam, AbundanceSimilarityParam, or EicSimilarityParam parameter object2728## Outputs2930- Grouped XcmsExperiment object with reduced feature group count31- Integer count of final distinct feature groups from featureGroups()3233## How to apply3435Begin with a pre-processed XcmsExperiment object containing detected chromatographic peaks. Apply groupFeatures() sequentially with parameter objects tailored to your data: first use SimilarRtimeParam(window_seconds) to cluster features within a retention-time window (e.g., 20 seconds), then refine with AbundanceSimilarityParam(threshold, transform) to group features whose abundances are correlated across samples (e.g., threshold=0.7, log2 transform), and optionally further refine with EicSimilarityParam(threshold, n) to group by similarity of extracted ion chromatogram peak shapes using the top n samples per group (e.g., threshold=0.7, n=2). After each groupFeatures() call, extract the final group count using featureGroups() to verify consolidation. The rationale is that features of the same compound should co-elute, show correlated abundance patterns, and display similar peak shapes; successive refinement progressively enforces these properties.3637## Related tools3839- **xcms** (Provides groupFeatures() function, SimilarRtimeParam, AbundanceSimilarityParam, EicSimilarityParam classes, and featureGroups() extraction method.) — https://github.com/sneumann/xcms40- **MsFeatures** (Defines general MS feature grouping functionality and parameter classes used by xcms.)4142## Examples4344```45groupFeatures(xmse, param = EicSimilarityParam(threshold = 0.7, n = 2)); featureGroups(xmse)46```4748## Evaluation signals4950- Final feature group count from featureGroups() is reduced compared to initial peak count (e.g., 2289 features grouped into 589 feature groups as in task_003).51- Each feature is assigned to exactly one feature group (no duplicates or unassigned features).52- Features within each group have retention times within the specified SimilarRtimeParam window.53- When AbundanceSimilarityParam is applied, abundance correlation between grouped features meets or exceeds the threshold (e.g., ≥0.7).54- When EicSimilarityParam is applied, EIC peak shapes of grouped features show visual or quantitative similarity as computed by the parameter object.5556## Limitations5758- Sequential grouping is order-dependent; the order of applying SimilarRtimeParam, AbundanceSimilarityParam, and EicSimilarityParam can affect final group counts and membership.59- Parameter threshold selection (e.g., SimilarRtimeParam window, AbundanceSimilarityParam threshold, EicSimilarityParam threshold) requires domain knowledge and may benefit from exploratory analysis; no single universal threshold is provided.60- EicSimilarityParam(n=2) uses only the top n samples per group for peak shape comparison, which may underutilize samples with lower abundance or miss subtle peak shape differences in low-abundance samples.61- The method assumes that features of the same compound have correlated abundances; compounds with sample-dependent ion suppression or ionization efficiency changes may yield spurious groupings or false negatives.6263## Evidence6465- [intro] Features (ions) of the same compound should have similar retention time, similar abundance patterns across samples, and similar peak shapes of extracted ion chromatograms: "Features (ions) of the same compound should have similar retention time, similar abundance patterns across samples, and similar peak shapes of extracted ion chromatograms"66- [intro] Compounding aims now at grouping such features presumably representing signal from the same originating compound to reduce data set complexity: "Compounding aims now at grouping such features presumably representing signal from the same originating compound to reduce data set complexity"67- [intro] groupFeatures() with EicSimilarityParam(threshold = 0.7, n = 2) to group features by similarity of extracted ion chromatogram peak shapes: "groupFeatures(xmse, EicSimilarityParam(threshold = 0.7, n = 2)) to group features by similarity of extracted ion chromatogram peak shapes"68- [other] Call groupFeatures() with EicSimilarityParam(threshold = 0.7, n = 2) to group features by similarity of extracted ion chromatogram peak shapes.: "Call groupFeatures() with EicSimilarityParam(threshold = 0.7, n = 2) to group features by similarity of extracted ion chromatogram peak shapes."69- [other] the 2289 features being grouped into 589 distinct feature groups: "The grouping based on EIC correlation resulted in the 2289 features being grouped into 589 distinct feature groups."
HolobiomicsLab 