# Metabolite Feature Annotation Aggregation

> Use when after selecting statistically significant features from multi-assay LC-MS metabolomics datasets (e.g., via MB-VIP and permutation testing with p < 0.01).

- Skill: `holobiomicslab/metabolite-feature-annotation-aggregation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/metabolite-feature-annotation-aggregation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/metabolite-feature-annotation-aggregation/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/metabolite-feature-annotation-aggregation

---


# metabolite-feature-annotation-aggregation

## Summary

Automated annotation and structural linking of statistically significant untargeted LC-MS features into metabolite clusters defined by mass-to-charge ratio (m/z), retention time (RT), and structural properties (isotopologues, adducts, cross-assay links). This skill aggregates isolated feature detections into coherent metabolite signatures for improved biological interpretation.

## When to use

After selecting statistically significant features from multi-assay LC-MS metabolomics datasets (e.g., via MB-VIP and permutation testing with p < 0.01). Apply this skill when you need to collapse multiple m/z and RT observations into single metabolite identities, and when you have access to retention-time-based metabolite reference annotations (ROI files) or can perform computational structural inference via isotopologue/adduct mass matching within defined mass tolerance (e.g., 15 ppm).

## When NOT to use

- Input is already a curated targeted assay with authenticated metabolite identities; annotation-aggregation is redundant.
- LC-MS data were acquired on low-resolution instruments (unit or 0.1 Da mass accuracy) where mass-tolerance-based adduct matching is unreliable.
- Retention time is not calibrated or normalized across assays, making RT-window partitioning uninformative.

## Inputs

- Selected significant LC-MS features (pandas DataFrame with m/z, retention time, assay prefix columns)
- Multi-assay LC-MS data blocks (HPOS, LPOS, LNEG, RNEG, RPOS, or similar ionization modes)
- Correlation matrix or hierarchical dendrogram from prior MamsiStructSearch run
- ROI files (peakPantheR format, optional) containing reference metabolite annotations with RT and m/z

## Outputs

- Structural cluster assignments (feature ID → cluster ID mapping)
- Cluster membership tables showing feature-level isotopologue, adduct, and cross-assay link types
- Agreement metrics between clustering methods (adjusted Rand index, normalized mutual information)
- Annotated feature list with putative metabolite identities (if ROI-based annotation is applied)
- Network object (NetworkX or Cytoscape-compatible) encoding structural relationships

## How to apply

First, partition significant features into retention-time windows (typically 5-second intervals) to isolate co-eluting species. Within each RT window, search for isotopologue signatures by detecting mass differences of 1.00335 Da between m/z values; group matching pairs. Next, calculate hypothetical neutral masses for each feature assuming common electrospray adducts ([M+H]+, [M-H]−, etc.), and cluster features whose neutral masses match within a defined mass tolerance (typically 15 ppm for high-resolution instruments). Merge overlapping isotopologue and adduct clusters to form structural clusters. Optionally, link cross-assay clusters using [M+H]+/[M-H]− mass-difference signatures as bridge references. If ROI files (peakPantheR format) are available, perform automated annotation by matching observed RT and m/z against reference libraries. Finally, compute a hierarchical dendrogram on feature correlation matrices and flatten using either constant-threshold or silhouette-score optimization to yield consensus cluster assignments. Evaluate agreement between methods (e.g., adjusted Rand index, normalized mutual information) to validate stability.

## Related tools

- **MAMSI (MamsiStructSearch)** (Core framework for structural clustering, isotopologue/adduct detection, and optional ROI-based annotation of LC-MS features) — https://github.com/kopeckylukas/py-mamsi
- **peakPantheR** (Provides ROI (region of interest) files encoding reference retention time and m/z for automated metabolite annotation) — https://github.com/phenomecentre/peakPantheR
- **scikit-learn** (Computes clustering agreement metrics (adjusted Rand index, normalized mutual information) and supports silhouette-score optimization for dendrogram flattening)
- **scipy** (Provides hierarchical clustering, dendrogram construction, and distance metrics for feature correlation analysis)
- **NetworkX / Cytoscape** (Visualizes and exports structural relationship networks as interactive graph objects for manual inspection of adduct/isotopologue/cross-assay links)
- **pandas / numpy** (Data manipulation, tabulation of cluster assignments, and mass/RT difference calculations)

## Examples

```
struct = MamsiStructSearch(rt_win=5, ppm=15)
struct.load_lcms(selected)
struct.get_structural_clusters(annotate=True)
struct.get_correlation_clusters(flat_method='silhouette', max_clusters=11)
```

## Evaluation signals

- Isotopologue detection: verify that identified mass differences match 1.00335 Da (±instrument accuracy) and that paired features co-elute within the same RT window
- Adduct clustering: confirm that inferred neutral masses for features within a structural cluster agree to within the specified tolerance (15 ppm); check that adduct type assignments are chemically plausible for the ionization mode
- Cluster stability: agreement metrics (e.g., adjusted Rand index > 0.8) between constant-threshold and silhouette-optimized clustering solutions indicate robust assignments
- Cross-assay linking: verify that [M+H]+/[M-H]− links correctly map features across positive and negative ion-mode assays with expected mass differences (~1.008 Da per charge)
- Annotation coverage: if ROI-based annotation is applied, report the proportion of features with matched reference entries and the median RT/m/z error distributions

## Limitations

- Annotation quality depends on mass measurement accuracy and RT calibration consistency; low-resolution instruments (>5 ppm error) may produce spurious adduct matches within 15 ppm tolerance.
- ROI-based annotation is limited to metabolites covered by reference libraries (e.g., NPC assay annotations); novel or unknown metabolites will lack putative identities.
- Isotopologue and adduct detection assume standard ESI polarity conventions; non-standard ionization methods or exotic adducts (e.g., [M+Na]+, [M+Cl]−) may not be detected.
- Hierarchical dendrogram flattening is sensitive to linkage method choice (complete, average, single); silhouette optimization requires specification of max_clusters parameter, which is data-dependent and not automatically determined.
- The framework was tested on metabolomics phenotyping data; applicability to other LC-MS data types (e.g., proteomics, lipidomics-specific instruments) is acknowledged but not formally validated.

## Evidence

- [methods] each RT window is searched for isotopologue signatures by searching mass differences of 1.00335 Da between mass-to-charge ratios (m/z) of the features: "each RT window is searched for isotopologue signatures by searching mass differences of 1.00335 *Da* between mass-to-charge ratios (*m/z*) of the features"
- [methods] This is followed by a search for common adduct signatures. This is achieved by calculating hypothetical neutral masses based on common adducts in electrospray ionisation.: "This is followed by a search for common adduct signatures. This is achieved by calculating hypothetical neutral masses based on common adducts in electrospray ionisation."
- [methods] Overlapping adduct clusters and isotopologue clusters are then merged to form structural clusters.: "Overlapping adduct clusters and isotopologue clusters are then merged to form structural clusters."
- [methods] Further, we search cross-assay clusters using [M+H]+/[M-H]− as link references.: "Further, we search cross-assay clusters using [M+H]<sup>+</sup>/[M-H]<sup>−</sup> as link references."
- [intro] MAMSI links statistically significant features of untargeted multi-assay LC-MS metabolomics datasets into clusters defined by structural properties based on m/z and RT: "the MAMSI framework provides a platform for linking statistically significant features of untargeted multi-assay liquid chromatography – mass spectrometry (LC-MS) metabolomics datasets into clusters"
- [methods] our structural search tool, that utilises region of interest (ROI) files from peakPantheR, allows for automated annotation of some features based on the RT for a given chromatography and m/z.: "our structural search tool, that utilises region of interest [(ROI) files](https://github.com/phenomecentre/npc-open-lcms) from peakPantheR [[4](#references)], allows for automated annotation of"
- [intro] the framework was tested on metabolomics phenotyping data, but it should be usable with other types of LC-MS data.: "the framework was tested on metabolomics phenotyping data, but it should be usable with other types of LC-MS data."
- [methods] Re-flatten the same dendrogram using silhouette-score optimization with max_clusters=11 via the get_correlation_clusters() method with flat_method='silhouette'.: "Re-flatten the same dendrogram using silhouette-score optimization with max_clusters=11 via the get_correlation_clusters() method with flat_method='silhouette'."
- [methods] Compute agreement metrics (adjusted Rand index, normalized mutual information) between the two clustering solutions.: "Compute agreement metrics (adjusted Rand index, normalized mutual information) between the two clustering solutions."