Mass Spectrometry Cluster Detection

---
name: mass-spectrometry-cluster-detection
description: Use when you have 32-dimensional GLEAMS embeddings (output from the `gleams
  embed` step) and need to group spectra by their underlying peptide identity.
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3432
  edam_topics:
  - http://edamontology.org/topic_0121
  - http://edamontology.org/topic_3520
  tools:
  - GLEAMS
  - Python
  techniques:
  - LC-MS
  license_tier: open
  provenance_tier: literature
derived_from:
- doi: 10.1038/s41592-022-01496-1
  title: GLEAMS
evidence_spans:
- GLEAMS encodes mass spectra as vectors of features and feeds them to a neural network
- GLEAMS is a Learned Embedding for Annotating Mass Spectra. GLEAMS encodes mass spectra
  as vectors of features and feeds them to a neural network
- GLEAMS requires Python 3.8, a Linux operating system, and a CUDA-enabled GPU
claims: []
provenance:
  collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v2
  assembled_by: scripts/collect_metabolomics_collection.py
  sources:
  - build: coll_gleams_cq
    doi: 10.1038/s41592-022-01496-1
    title: GLEAMS
  dedup_kept_from: coll_gleams_cq
schema_version: 0.2.0
attribution:
  generator: AgenticScienceBuilder
  original_doi: 10.1038/s41592-022-01496-1
  all_source_dois:
  - 10.1038/s41592-022-01496-1
  zenodo_doi: 10.5281/zenodo.20794027
  curators: []
  promoter: Louis-Félix Nothias
  sponsor: CNRS & Université Côte d'Azur
---

# 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."