Retention time feature clustering

Skill HolobiomicsLab/asb-skill-collections/packs/metabolomics/gc-ms/skills/retention-time-feature-clustering

Curated, evidence-grounded skill and software-tool collections for scientific AI agents, generated by the AgenticScienceBuilder

Install

npx -y skills add HolobiomicsLab/asb-skill-collections --skill retention-time-feature-clustering

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

14 stars14 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Use when after chromatographic peak detection (findChromPeaks) when you have a processed XcmsExperiment object with detected peaks and need to perform initial feature grouping. Use it when features of the same compound are expected to co-elute within a narrow retention-time window (e.

The file declares its own license as CC-BY-4.0. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

6.2 KB, as published. Nobody here has run it

retention-time-feature-clustering

Summary

Group LC-MS features by similar retention time within a specified time window to create preliminary feature groups representing potential ions from the same compound. This is typically the first step in multi-stage feature grouping, reducing data complexity before applying abundance- or peak-shape-based refinement.

When to use

Apply this skill after chromatographic peak detection (findChromPeaks) when you have a processed XcmsExperiment object with detected peaks and need to perform initial feature grouping. Use it when features of the same compound are expected to co-elute within a narrow retention-time window (e.g., 10–20 seconds in typical LC-MS), and before applying more sophisticated grouping methods based on abundance correlation or EIC similarity.

When NOT to use

Input data has not undergone chromatographic peak detection; call findChromPeaks() first.
Retention-time information is missing or unreliable (e.g., drift exceeds tolerance window size).
Feature groups should be based solely on MS/MS spectral similarity or external compound lists without chromatographic information.

Inputs

XcmsExperiment object with detected chromatographic peaks (result of findChromPeaks with centWave or similar)
SimilarRtimeParam object specifying retention-time window (in seconds)

Outputs

XcmsExperiment object with featureGroups() populated by retention-time-based clustering
Integer vector of feature group identifiers

How to apply

Load a pre-processed XcmsExperiment object (xmse) and invoke the groupFeatures() function with SimilarRtimeParam(window_size_seconds) as the parameter. The window size (e.g., 20 seconds) defines the maximum retention-time tolerance within which features are clustered together. Features whose retention times fall within this window are assigned to the same feature group. The resulting grouped xmse object will have featureGroups() populated with integer group identifiers. This approach is fast and requires no sample-level information, making it suitable as a first-pass grouping step that can be followed by abundance-correlation or EIC-similarity refinement to split groups with low within-group coherence.

Related tools

xcms (Provides groupFeatures() function and SimilarRtimeParam class for retention-time-based feature grouping; implements the core peak detection and grouping workflow.) — https://github.com/sneumann/xcms
MsFeatures (Supplies general MS feature grouping functionality and parameter classes used by xcms for modular grouping strategies.)

Examples

groupFeatures(xmse, param = SimilarRtimeParam(20))

Evaluation signals

Verify that featureGroups() returns a non-empty integer vector with unique group IDs after grouping.
Confirm that all features within a single group have retention times within the specified window (e.g., ±10 s for SimilarRtimeParam(20)).
Check that the total number of feature groups is substantially smaller than the total number of individual features detected, indicating successful clustering.
Validate that no features are unassigned (no NA values in featureGroups()).
Compare the resulting group count to published benchmarks or expected ranges from prior experiments on the same dataset (e.g., faahKO).

Limitations

Retention-time-only grouping cannot distinguish features of different compounds that co-elute; subsequent refinement by abundance correlation or EIC similarity is often necessary to split such groups.
The method is sensitive to retention-time calibration and reproducibility across runs; systematic drift can cause misalignment.
Window size choice is heuristic and data-dependent; no automated parameter optimization is provided by the tool.
Features with identical m/z and retention time but from different compounds (isomers, isobars) will be grouped together and require post-hoc disambiguation.

Evidence

[intro] Group features by similar retention time within specified time window: "groupFeatures(xmse, param = SimilarRtimeParam(10))"
[other] Retention-time grouping clusters features into distinct feature groups: "When features are grouped using SimilarRtimeParam(20), the initial retention time-based grouping clusters features into distinct feature groups identified by the featureGroups() function."
[intro] Features of the same compound should have similar retention time: "Features (ions) of the same compound should have similar retention time."
[other] Retention-time grouping is a first step followed by abundance-based refinement: "After applying retention-time-based grouping with a 20-second window on the faahKO dataset, how many feature groups result from applying abundance correlation-based refinement"
[readme] Tool provides efficient preprocessing for LC-MS data: "The xcms R package provides functionality to efficiently preprocess LC-MS (as well as GC-MS and LC-MS/MS) data."