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