# Mass Spectrometry Cluster Detection

> Use when you have 32-dimensional GLEAMS embeddings (output from the `gleams embed` step) and need to group spectra by their underlying peptide identity.

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

---


# mass-spectrometry-cluster-detection

## Summary

Detects peptide-level spectrum clusters from learned 32-dimensional embeddings of mass spectra using hierarchical clustering. This skill groups spectra generated from the same peptide by identifying proximity in embedding space, enabling efficient large-scale peptide-centric analysis of millions of MS/MS spectra.

## When to use

Use this skill when you have 32-dimensional GLEAMS embeddings (output from the `gleams embed` step) and need to group spectra by their underlying peptide identity. This is the appropriate next step after spectrum embedding when your analysis goal is peptide-level clustering, deduplication, or spectral library construction rather than individual spectrum annotation.

## When NOT to use

- Input spectra have not been embedded into 32-dimensional GLEAMS space — the clustering algorithm depends on learned embeddings and cannot be applied directly to raw peak lists or alternative embedding schemes.
- Your analysis goal is individual spectrum annotation or scoring rather than peptide-level grouping — use spectrum-to-library matching tools instead.
- You require cluster assignments based on spectral similarity metrics other than learned embedding proximity (e.g., cosine similarity in peak space, precursor m/z tolerance) — use alternative clustering methods designed for those metrics.

## Inputs

- 32-dimensional embedding vectors in NumPy array format (n × 32, where n = number of spectra)
- Embedding metadata file (.parquet format) containing spectrum identifiers and associated annotations

## Outputs

- Cluster label assignment array (.npy file) mapping each spectrum to its cluster ID
- Cluster medoid indexes (.npy file) identifying representative spectra for each cluster
- Optional tabular output mapping spectrum identifiers to cluster IDs

## How to apply

Load the 32-dimensional embedding vectors (n × 32 NumPy array) produced by `gleams embed` along with their metadata. Execute `gleams cluster` with a distance threshold parameter (e.g., 0.3) to perform hierarchical clustering on the embeddings. The algorithm groups spectra whose embeddings are close in the learned 32-dimensional space, producing cluster labels per spectrum where `-1` denotes noise and a minimum cluster size of 2 is enforced. Output includes cluster label assignments and medoid (cluster representative) indexes. The distance threshold controls cluster granularity and should be tuned based on the desired specificity of peptide grouping.

## Related tools

- **GLEAMS** (Provides the `gleams cluster` command to perform hierarchical clustering on embeddings and detects spectrum clusters of spectra generated by the same peptide.) — https://github.com/bittremieux/GLEAMS
- **Python** (Runtime environment (Python 3.8+) required to execute GLEAMS clustering commands and process embedding arrays.)

## Examples

```
gleams cluster --embed_name GLEAMS_embed --cluster_name GLEAMS_cluster --distance_threshold 0.3
```

## Evaluation signals

- Cluster size distribution is non-trivial: minimum 2 spectra per cluster is enforced, and the majority of clusters contain multiple spectra (not all singletons).
- Cluster label array has correct dimensions (n,) matching the number of input spectra, with integer values ≥ -1.
- Medoid indexes are valid row indices within the embedding array bounds (0 ≤ medoid_idx < n) and cluster medoids are always assigned to a valid cluster (not noise, label ≠ -1).
- Reproducibility: identical input embeddings and distance threshold produce identical cluster assignments across runs.
- Biological validation: manually inspected clusters contain spectra with consistent precursor m/z and fragmentation patterns consistent with the same peptide identity (when ground truth peptide annotations are available).

## Limitations

- Clustering quality depends critically on the quality and representativeness of the learned embeddings; embeddings trained on MassIVE-KB (30 million PSMs) may not generalize to spectra from very different ionization, instrument platforms, or organisms not well-represented in training data.
- Distance threshold is a hard parameter with no automatic selection method provided; users must manually tune based on desired cluster granularity, and no consensus guidance on threshold values for different application domains is documented.
- Minimum cluster size is fixed at 2; small peptides or rare variants may be split across multiple small clusters or merged with noise, and no adaptive clustering is performed.
- The method assumes spectra from the same peptide form a dense, separable region in 32-dimensional space; peptides with high intrinsic spectral heterogeneity (e.g., due to variable modifications or instrument noise) may be fragmented into multiple clusters.
- Git LFS bandwidth constraints may prevent installation; model weights (gleams_82c0124b.hdf5) must sometimes be downloaded manually from releases.

## Evidence

- [intro] GLEAMS embeds mass spectra into a 32-dimensional space where spectra from the same peptide cluster together: "GLEAMS encodes mass spectra as vectors of features and feeds them to a neural network to embed them into a 32-dimensional space in which spectra generated by the same peptide are close together"
- [intro] The clustering step detects spectrum clusters corresponding to spectra generated by the same peptide: "It then detects spectrum clusters of spectra generated by the same peptide"
- [readme] The gleams cluster command performs hierarchical clustering with a configurable distance threshold: "gleams cluster --embed_name GLEAMS_embed --cluster_name GLEAMS_cluster --distance_threshold 0.3"
- [readme] Clustering produces cluster labels per embedding and medoid indexes: "The output will be written to the `GLEAMS_cluster.npy` NumPy file with cluster labels per embedding (`-1` indicates noise, minimum cluster size 2). Additionally, a file `GLEAMS_cluster_medoids.npy`"
- [readme] Clustering follows spectrum embedding and produces 32-dimensional vector input: "After converting the MS/MS spectra to 32-dimensional embeddings, they can be clustered to group spectra with similar embeddings using the `gleams cluster` command."