Embedding Space Dimensionality Reduction

---
name: embedding-space-dimensionality-reduction
description: Use when when you have a collection of MS/MS spectra (in mzML or MGF
  format) and need to group or retrieve spectra from the same peptide, or when you
  need to perform large-scale similarity comparisons across millions of spectra without
  working directly in the original high-dimensional peak space.
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3935
  edam_topics:
  - http://edamontology.org/topic_0121
  - http://edamontology.org/topic_3520
  tools:
  - GLEAMS
  - Python
  - Conda
  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
- Create a Conda environment and install the necessary compiler tools and GPU runtime
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
---

# Embed mass spectra into low-dimensional vector space

## Summary

Convert MS/MS spectra into fixed-dimensional dense vector representations using a pre-trained neural network encoder, enabling efficient similarity-based clustering and retrieval. GLEAMS embeds spectra into a 32-dimensional space where peptide-identical spectra cluster together.

## When to use

When you have a collection of MS/MS spectra (in mzML or MGF format) and need to group or retrieve spectra from the same peptide, or when you need to perform large-scale similarity comparisons across millions of spectra without working directly in the original high-dimensional peak space. Use this skill when peak-level matching would be computationally prohibitive and you want spectra with similar fragmentation patterns to occupy nearby regions of a learned metric space.

## When NOT to use

- Spectra are already in an embedded or reduced representation; re-embedding may introduce unnecessary information loss.
- Input is not in mzML or MGF format and format conversion is not feasible.
- You require interpretability of individual dimensions; GLEAMS embeddings are learned end-to-end and dimensions are not directly interpretable as chemical features.

## Inputs

- MS/MS spectra in mzML format
- MS/MS spectra in MGF format
- Peak files containing MS/MS fragmentation patterns

## Outputs

- NumPy array of dimension n × 32 (n spectra, 32 embedding dimensions)
- Parquet file containing spectrum metadata and embeddings
- GLEAMS embedding vectors (.npy file)

## How to apply

Prepare mass spectra in a peak file format (mzML or MGF) compatible with GLEAMS. Execute the `gleams embed` command on the input spectra files; the pre-trained neural network encoder will convert each spectrum into a 32-dimensional feature vector, producing a NumPy array (n × 32, where n is the number of spectra) and accompanying metadata in Parquet format. The embedding is learned such that spectra generated by the same peptide are positioned close together in this space. Evaluate success by confirming that spectra with high cosine similarity in the embedding space correspond to known identical or near-identical peptide identifications, and by verifying that the output files contain the expected dimensionality and row count matching input spectra.

## Related tools

- **GLEAMS** (Neural network encoder that transforms mass spectra into 32-dimensional embeddings via pre-trained weights; executes both embed and cluster subcommands) — https://github.com/bittremieux/GLEAMS
- **Python** (Runtime environment required to execute GLEAMS (Python 3.8+))
- **Conda** (Environment manager to install compiler tools, GPU runtime (CUDA), and GLEAMS dependencies)

## Examples

```
gleams embed *.mzML --embed_name GLEAMS_embed
```

## Evaluation signals

- Output NumPy array has shape n × 32, where n equals the number of input spectra; missing or extra rows indicate input read failures.
- All embedding values are numeric (float32 or float64); NaN or Inf values indicate corruption or numerical instability.
- Parquet metadata file contains one row per spectrum with consistent row count to the embedding array.
- Spectra assigned to the same cluster (via `gleams cluster` on the embeddings with a distance threshold) share the same or highly similar peptide sequence identifications from external annotations.
- Euclidean or cosine distance between embeddings of replicate spectra (same peptide, different charge states or collision energies) is significantly smaller than distances to unrelated peptides.

## Limitations

- GLEAMS requires a Linux operating system and a CUDA-enabled GPU; CPU-only execution is not supported and will fail.
- The pre-trained model was trained on 30 million PSMs from the MassIVE-KB human proteome dataset; generalization to non-human organisms or atypical fragmentation modes (e.g., electron transfer dissociation, EDD) is not validated in the paper.
- Installation can fail if the Git LFS bandwidth quota is exhausted; manual download of model weights (gleams_82c0124b.hdf5) is necessary as a workaround.
- The 32-dimensional embedding space is a fixed-size bottleneck; spectra with highly unusual fragmentation patterns may not be accurately represented.
- Clustering on embeddings with hierarchical clustering and distance threshold is a separate step; the embedding itself does not produce cluster labels, only vectors.

## Evidence

- [intro] 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.: "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"
- [readme] GLEAMS provides the `gleams embed` command to convert MS/MS spectra in peak files to 32-dimensional embeddings.: "GLEAMS provides the `gleams embed` command to convert MS/MS spectra in peak files to 32-dimensional embeddings"
- [readme] This will read the MS/MS spectra from all matched mzML files and export the results to a two-dimensional NumPy array of dimension n x 32 in file `GLEAMS_embed.npy`, with n the number of MS/MS spectra read from the mzML files.: "export the results to a two-dimensional NumPy array of dimension n x 32 in file `GLEAMS_embed.npy`, with n the number of MS/MS spectra read from the mzML files"
- [readme] GLEAMS requires Python 3.8, a Linux operating system, and a CUDA-enabled GPU.: "GLEAMS requires Python 3.8, a Linux operating system, and a CUDA-enabled GPU"
- [readme] Create a Conda environment and install the necessary compiler tools and GPU runtime: "Create a Conda environment and install the necessary compiler tools and GPU runtime"