# Mass Spectrometry Feature Deconvolution

> Use when you have a peak table from LC-MS peak picking software (e.

- Skill: `holobiomicslab/mass-spectrometry-feature-deconvolution` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/mass-spectrometry-feature-deconvolution`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/mass-spectrometry-feature-deconvolution/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/mass-spectrometry-feature-deconvolution

---


# Reconstruct the feature clustering algorithm producing Cluster_ID assignments

## Summary

Group correlated LC-MS metabolic features into clusters based on mass-to-charge ratio proximity, retention time co-elution, and abundance correlation, then assign cluster identifiers named after the highest-abundance feature in each cluster. This skill resolves isotopologues, adducts, and in-source fragments that represent the same underlying metabolite.

## When to use

Apply this skill when you have a peak table from LC-MS peak picking software (e.g., MS-DIAL output) with Feature_ID, Mass, RetentionTime, and abundance columns, and you need to reduce redundancy by merging features likely to originate from the same compound before statistical analysis or metabolite identification.

## When NOT to use

- Input features are already known to represent distinct metabolites (i.e., target analysis with pre-defined compound lists); clustering adds unnecessary complexity.
- Retention time information is unreliable or missing; the ±RT window filter becomes ineffective.
- Peak picking output is incomplete or lacks standardized feature identifiers, making correlation-based linkage unreliable.

## Inputs

- MetaboSet object with feature abundance matrix (exprs) and feature metadata (fData)
- Feature metadata: Feature_ID, Mass (m/z), RetentionTime columns
- Sample abundance data: feature intensities across all samples

## Outputs

- Updated MetaboSet object with Cluster_ID column added to feature data
- Cluster membership assignments (each feature labeled with its cluster)
- Cluster representatives (the feature with highest median peak area per cluster)

## How to apply

First, extract sample abundances and feature metadata (Feature_ID, Mass, RetentionTime) from the MetaboSet object using combined_data() and fData(). Execute find_connections() with a correlation threshold (e.g., 0.9), a retention time window (e.g., ±1 s), and specify column names (name_col='Feature_ID', mz_col='Mass', rt_col='RetentionTime') to build a graph where nodes are features and edges connect correlated pairs within the RT window. Run find_clusters() with a degree threshold (e.g., 0.8) to decompose the graph into connected components and iteratively prune low-degree nodes until each remaining node meets the minimum connectivity criterion. Finally, execute assign_cluster_id() to label all features with a Cluster_ID (named after the feature with highest median peak area in each cluster). Verify that the Cluster_ID column has been added to feature metadata and inspect within-cluster groupings to confirm biologically plausible associations.

## Related tools

- **notame** (Provides find_connections(), find_clusters(), and assign_cluster_id() functions; manages MetaboSet data structure holding feature metadata and abundances) — https://github.com/hanhineva-lab/notame
- **Biobase** (ExpressionSet class upon which MetaboSet is built, enabling unified access to feature metadata and abundance matrices)
- **R** (Runtime environment for executing notame functions and data manipulation)

## Examples

```
find_connections(metaboset, name_col='Feature_ID', mz_col='Mass', rt_col='RetentionTime', correlation_threshold=0.9, rt_window=1); clusters <- find_clusters(connections, degree_threshold=0.8); metaboset <- assign_cluster_id(metaboset, clusters)
```

## Evaluation signals

- Cluster_ID column is present in fData(metaboset) and contains no missing values for valid features
- Each Cluster_ID is named after a valid Feature_ID corresponding to the highest median peak area feature in that cluster
- All features within a cluster have pairwise correlation ≥ threshold AND retention times within ±RT window
- Cluster sizes are reasonable (no single cluster contains >90% of features, suggesting threshold parameters are too permissive)
- Degree distribution of cluster members shows that iterative pruning removed low-connectivity outliers as expected

## Limitations

- Clustering quality depends critically on accurate m/z and retention time measurements; calibration drift or peak picking errors propagate into spurious cluster assignments.
- Correlation threshold and retention time window are user-specified and may require optimization for different LC-MS methods, ionization modes, or metabolite classes; no universally optimal values are provided.
- Features with very low abundance across samples may have unstable correlation estimates, leading to unexpected cluster membership or isolation.
- The algorithm assumes that co-eluting, correlated features represent the same metabolite; genuine metabolites with very similar m/z and RT (isobars) may be incorrectly merged.

## Evidence

- [other] Execute find_connections() with correlation threshold 0.9, retention time window ±1 s, and column names (name_col='Feature_ID', mz_col='Mass', rt_col='RetentionTime') to identify all correlated feature pairs within the RT window.: "Execute find_connections() with correlation threshold 0.9, retention time window ±1 s, and column names (name_col='Feature_ID', mz_col='Mass', rt_col='RetentionTime') to identify all correlated"
- [other] Run find_clusters() with degree threshold 0.8 on the connections output to decompose the graph into connected components and prune nodes iteratively until each node meets the minimum degree criterion.: "Run find_clusters() with degree threshold 0.8 on the connections output to decompose the graph into connected components and prune nodes iteratively until each node meets the minimum degree criterion."
- [other] Execute assign_cluster_id() to label all features with Cluster_ID (named after the feature with highest median peak area in each cluster) and record cluster membership.: "Execute assign_cluster_id() to label all features with Cluster_ID (named after the feature with highest median peak area in each cluster) and record cluster membership."
- [readme] A novel method for clustering similar molecular features: "A novel method for clustering similar molecular features"
- [readme] The algorithm for clustering molecular features originating from the same compound is based on MATLAB code written by David Broadhurst: "The algorithm for clustering molecular features originating from the same compound is based on MATLAB code written by David Broadhurst"