Mass Spectra Encoding Neural Network

---
name: mass-spectra-encoding-neural-network
description: Use when you have a collection of MS/MS spectra (in mzML or MGF format) from a proteomics experiment and need to group or retrieve spectra derived from the same peptide without prior peptide identification.
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
  - Conda
  techniques:
  - LC-MS
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
---

# Reconstruct the GLEAMS spectrum embedding step into a 32-dimensional space

## Summary

Use a pre-trained neural network encoder to transform tandem mass spectrometry (MS/MS) spectra into 32-dimensional vector embeddings where spectra from identical peptides cluster together. This enables efficient large-scale spectrum similarity detection and grouping.

## When to use

Apply this skill when you have a collection of MS/MS spectra (in mzML or MGF format) from a proteomics experiment and need to group or retrieve spectra derived from the same peptide without prior peptide identification. Use it when working with datasets of thousands to millions of spectra where pairwise similarity comparisons are computationally prohibitive.

## When NOT to use

- Input spectra are already in pre-computed embedding or feature vector form — re-encoding would be redundant.
- Your goal is peptide sequence identification or spectrum annotation; use a spectral library search tool or de novo sequencing method instead.
- You lack access to a CUDA-enabled GPU and Linux system; GLEAMS requires these hardware and OS constraints.

## Inputs

- MS/MS spectra file in mzML format
- MS/MS spectra file in MGF format
- Mass spectrum peak lists with m/z and intensity values

## Outputs

- NumPy array of shape (n, 32) containing 32-dimensional spectrum embeddings
- Parquet file with spectrum metadata and embedding coordinates
- Vector representation artifact file (.npy)

## How to apply

First, prepare your mass spectra input file in mzML or MGF format compatible with GLEAMS. Execute the `gleams embed` command on your spectra collection, which internally encodes each spectrum as a feature vector and passes it through the pre-trained 32-dimensional neural network encoder. The encoder learns a metric space where spectra generated by the same peptide have small Euclidean distances. Retrieve the output as a two-dimensional NumPy array (n × 32, where n is the number of input spectra) and an accompanying metadata table in Parquet format. Verify embedding quality by confirming that spectra from the same peptide are close in the 32-dimensional space before proceeding to clustering or downstream analysis.

## Related tools

- **GLEAMS** (Pre-trained neural network encoder that transforms raw mass spectra into 32-dimensional embeddings via learned feature representation) — https://github.com/bittremieux/GLEAMS
- **Python** (Runtime environment and scripting language required to execute GLEAMS (version 3.8 or later))
- **Conda** (Package and environment manager used to install compiler tools, GPU runtime dependencies, and GLEAMS)

## Examples

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

## Evaluation signals

- Output NumPy array has shape (n, 32) where n matches the number of input spectra; no missing or NaN values.
- Metadata Parquet file contains one row per spectrum with consistent row count matching the embedding array.
- Spectra from known identical peptides (same sequence, charge state, modification) exhibit small Euclidean distances (< 0.5) in the 32-dimensional space.
- Spectra from different peptides are separated by larger distances in embedding space, confirming discriminative power.
- Embedding computation completes without CUDA out-of-memory errors or LFS bandwidth failures.

## Limitations

- GLEAMS requires Python 3.8, a Linux operating system, and a CUDA-enabled GPU; it cannot run on CPU or Windows/macOS natively.
- Model weights are distributed via Git LFS; bandwidth quota exhaustion may occur during high-volume downloads, requiring manual workaround (clone without LFS, download weights separately).
- Embeddings are specific to the pre-trained model; retraining on new data requires access to the full 30 million PSM training set or significant custom proteomics data.
- The 32-dimensional space was optimized for human proteome spectra in the MassIVE-KB dataset; performance on non-human organisms or non-HCD fragmentation methods is not characterized.

## 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`"
- [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] This is caused by many people downloading GLEAMS recently, running out of Git LFS bandwith used to download the model weights.: "running out of Git LFS bandwith used to download the model weights"
- [readme] GLEAMS was trained on 30 million PSMs from the MassIVE-KB (v1) dataset.: "GLEAMS was trained on 30 million PSMs from the MassIVE-KB (v1) dataset"