Spectrum Embedding Clustering

---
name: spectrum-embedding-clustering
description: Use when after embedding MS/MS spectra into 32-dimensional GLEAMS vectors,
  when you need to group spectra by the same peptide origin.
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
---

# spectrum-embedding-clustering

## Summary

Group mass spectra by peptide identity using hierarchical clustering on learned 32-dimensional embeddings. This skill detects spectrum clusters where spectra from the same peptide are proximal in embedding space, enabling efficient large-scale peptide-centric analysis.

## When to use

Apply this skill after embedding MS/MS spectra into 32-dimensional GLEAMS vectors, when you need to group spectra by the same peptide origin. Use it to organize millions of spectra into peptide-level clusters for downstream annotation or comparative analysis, especially when working with large, heterogeneous spectral datasets where direct spectrum-to-spectrum comparison is computationally prohibitive.

## When NOT to use

- Spectra have not been embedded into 32-dimensional GLEAMS vectors; use gleams embed first.
- You need to perform de novo peptide sequencing or spectrum annotation; clustering alone does not assign sequences—only groups spectra by similarity.
- Input embeddings were generated by a different embedding method (non-GLEAMS); clustering is optimized for GLEAMS embedding geometry and may not generalize well.

## Inputs

- 32-dimensional embedding NumPy array (n × 32, output from gleams embed command)
- Distance threshold parameter (float, typically 0.1–0.5)

## Outputs

- Cluster label array (NumPy file, one integer label per spectrum; -1 for noise)
- Medoid indices array (NumPy file, spectrum indices representing each cluster)
- Cluster metadata table (optional, mapping spectrum IDs to cluster assignments)

## How to apply

Load the 32-dimensional embedding NumPy array (n × 32, where n is the number of spectra) and execute hierarchical clustering with a specified distance threshold (e.g., 0.3). The clustering algorithm groups embeddings such that spectra from the same peptide fall into the same cluster. Set the distance threshold empirically based on your specificity requirements; lower thresholds yield tighter clusters. Output cluster assignments and medoid indices (representative spectra per cluster). Clusters labeled '-1' are noise; only clusters with minimum size 2 are retained. Validate by inspecting whether spectra in the same cluster share consistent precursor m/z and retention time properties.

## Related tools

- **GLEAMS** (Performs hierarchical clustering on 32-dimensional embeddings via gleams cluster command to group spectra by peptide identity) — https://github.com/bittremieux/GLEAMS
- **Python** (Required runtime environment (Python 3.8+) for GLEAMS clustering operations)

## Examples

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

## Evaluation signals

- Output cluster labels are integers or -1 (noise); all assigned spectra have valid cluster IDs ≥ 0.
- Minimum cluster size is 2; no clusters contain only a single spectrum (except noise, marked -1).
- Medoid indices are valid array indices within the range [0, n) and correspond to spectra in each cluster.
- Spectra within the same cluster have embedding-space distances below the specified distance threshold; cross-cluster distances exceed it.
- Visual inspection: sample spectra from the same cluster exhibit similar peak patterns and consistent precursor mass/charge and retention time properties.

## Limitations

- Clustering performance depends critically on embedding quality; poor or incomplete embeddings will yield spurious clusters.
- Distance threshold is user-specified and must be tuned empirically; no single threshold is universally optimal across all datasets.
- The method requires a CUDA-enabled GPU and Linux OS; not available on Windows or macOS without containerization.
- Clustering does not assign peptide sequences; it only groups spectra by learned similarity. Sequence assignment requires additional annotation steps (e.g., spectral library search).
- Minimum cluster size of 2 excludes singleton spectra, which may represent rare modifications or contaminants; these are labeled noise (-1).

## Evidence

- [intro] It then detects spectrum clusters of spectra generated by the same peptide: "It then detects spectrum clusters of spectra generated by the same peptide"
- [readme] 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.: "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."
- [readme] This will perform hierarchical clustering on the embeddings with the given distance threshold. The output will be written to the `GLEAMS_cluster.npy` NumPy file with cluster labels per embedding (`-1` indicates noise, minimum cluster size 2).: "This will perform hierarchical clustering on the embeddings with the given distance threshold. The output will be written to the `GLEAMS_cluster.npy` NumPy file with cluster labels per embedding"
- [intro] spectra generated by the same peptide are close together: "spectra generated by the same peptide are close together"
- [readme] gleams cluster --embed_name GLEAMS_embed --cluster_name GLEAMS_cluster --distance_threshold 0.3: "gleams cluster --embed_name GLEAMS_embed --cluster_name GLEAMS_cluster --distance_threshold 0.3"