spectral-peak-word-embedding-representation
Summary
Convert mass spectrometry fragment peaks and neutral losses into word tokens suitable for Word2Vec embedding, enabling learned representation of fragmental relationships. This representation bridges spectral data and natural language processing to capture structural similarity patterns in MS/MS spectra.
When to use
When you have MS/MS spectra (LC-MS or equivalent positive ionization mode data) that you intend to embed using Word2Vec or similar distributional semantic models, or when you need to prepare spectral data for training similarity models that learn peak co-occurrence patterns rather than relying on cosine-based peak matching alone.
When NOT to use
- Input spectra contain fewer than 10 fragment peaks (filter these before tokenization)
- Data is GC-MS where neutral losses are not reliably measured; Spec2Vec was only demonstrated on LC-MS
- You require deterministic, directly interpretable peak alignment (cosine or modified cosine scores are more transparent)
Inputs
- MS/MS spectra (mzML, mzXML, msp, MGF, or JSON format)
- Normalized spectrum object with peaks (m/z, intensity pairs) and precursor m/z
- Peak intensity matrix (relative intensities normalized to [0, 1] range)
Outputs
- Spectrum-as-document representation (list of peak and loss word tokens per spectrum)
- Ordered token sequence suitable for Word2Vec gensim.models.Word2Vec input
- Peak vocabulary with token-to-m/z mapping for later embedding lookups
How to apply
For each spectrum, normalize peak intensities to a maximum of 1.0. Convert each peak to a word token using the format '[redacted-email]' (binned to 2 decimal places in m/z space). Add neutral loss words by computing precursor m/z minus each peak m/z, retaining only losses in the range 5.0–200.0 Da, formatted as '[redacted-email]'. Filter peaks by intensity (relative intensity ≥ 0.01 of max) and by parent mass scaling (retain at most 0.5 × parent_mass peaks per spectrum). This tokenization transforms each spectrum into a 'document' (ordered sequence of words) that preserves both fragmental identity and neutral loss patterns, which Word2Vec then learns as a co-occurrence space. The binning precision and mass range cutoffs are justified to balance model generalization against sparsity.
Related tools
- matchms (Provides spectral data structures, I/O loaders (mzML, MGF, msp), peak filtering, and intensity normalization functions used to prepare spectra before tokenization) — https://github.com/matchms/matchms
- gensim (Implements Word2Vec model training and word embedding lookups on the tokenized peak and loss sequences)
- spec2vec (Wraps this tokenization workflow and applies trained Word2Vec embeddings to compute spectral similarity scores based on learned peak relationships) — https://github.com/iomega/spec2vec
- NumPy (Used for intensity normalization and numerical operations on peak arrays)
- Numba (Provides JIT-compiled functions for fast computation of missing-fraction statistics and embedding aggregations across large spectra collections)
Examples
from matchms import Spectrum; from spec2vec import Spec2VecParallel; import gensim; spectra = [Spectrum(mz=np.array([100.1, 200.2, 300.3]), intensities=np.array([0.5, 1.0, 0.3]), metadata={'precursor_mz': 400.4})]; documents = [[f'peak@{mz:.2f}' for mz in s.mz] + [f'loss@{(s.metadata["precursor_mz"] - mz):.2f}' for mz in s.mz if 5.0 <= (s.metadata["precursor_mz"] - mz) <= 200.0] for s in spectra]; model = gensim.models.Word2Vec(documents, window=10, min_count=1, epochs=15)
Evaluation signals
- Every spectrum in the tokenized corpus contains at least 1 peak word token (spectra with <10 original peaks are filtered out; retained spectra should have ≥1 token after binning and filtering)
- Peak word vocabulary size grows monotonically with the number of unique m/z values in the input dataset; no negative vocabulary counts
- Missing-fraction metric (1 − Σ√w_i for known words / Σ√w_i for all words) computed on the held-out test set reaches ≈97% coverage when the Word2Vec model is trained on a large corpus (e.g., AllPositive dataset, 95,320 spectra, 15 epochs)
- Each loss word token falls strictly in the range 5.0–200.0 Da; losses outside this range are absent from the output
- Peak intensity normalization is correctly applied: max intensity per spectrum equals 1.0, all others ≤ 1.0; relative peak filtering (intensity < 0.01) removes the expected proportion of low-intensity peaks
Limitations
- GC-MS data are not supported; neutral losses are typically not measured in GC-MS, reducing the utility of this tokenization scheme (only LC-MS demonstrated)
- Tokenization binning to 2 decimal places (m/z precision) may lose fine structural detail and may merge nearby peaks; alternative binning strategies are not explored in the article
- Unknown peaks (word tokens) not present in the trained Word2Vec model are excluded from similarity computation; this requires a model trained on a representative corpus; retraining may be necessary for experimental data with insufficient feature overlap to the training set
- Spectra with fewer than 10 fragment peaks are filtered before tokenization, discarding potentially informative low-complexity spectra
- No guidance provided on optimal loss-mass range (5.0–200.0 Da) selection for datasets with unusual precursor mass distributions
Evidence
- [methods] After processing, spectra are converted to documents. For this, every peak is represented by a word that contains its position up to a defined decimal precision ("[redacted-email]"): "After processing, spectra are converted to documents. For this, every peak is represented by a word that contains its position up to a defined decimal precision ("[redacted-email]")"
- [methods] In addition to all peaks of a spectrum, neutral losses between 5.0 and 200.0 Da were added as "[redacted-email]". Neutral losses are calculated as precursor − peak: "In addition to all peaks of a spectrum, neutral losses between 5.0 and 200.0 Da were added as "[redacted-email]". Neutral losses are calculated as precursor − peak"
- [other] For each spectrum, convert peaks to words with format '[redacted-email]' (2-decimal binning) and add neutral losses (5.0–200.0 Da) as '[redacted-email]' words. Normalize peak intensities to maximum = 1 for each spectrum.: "For each spectrum, convert peaks to words with format '[redacted-email]' (2-decimal binning) and add neutral losses (5.0–200.0 Da) as '[redacted-email]' words. Normalize peak intensities to maximum = 1 for"
- [methods] the maximum number of kept peaks per spectrum was set to scale linearly with the estimated parent mass: max(n_peaks) = 0.5 × parentmass: "the maximum number of kept peaks per spectrum was set to scale linearly with the estimated parent mass: max(n_peaks) = 0.5 × parentmass"
- [methods] For both the cosine and modified cosine score calculations we ignored all peaks with relative intensities <0.01 compared to the highest intensity peak: "For both the cosine and modified cosine score calculations we ignored all peaks with relative intensities <0.01 compared to the highest intensity peak"
- [readme] Spec2Vec does so for mass fragments and neutral losses in MS/MS spectra. The spectral similarity score is based on spectral embeddings learnt from the fragmental relationships within a large set of spectral data.: "Spec2Vec does so for mass fragments and neutral losses in MS/MS spectra. The spectral similarity score is based on spectral embeddings learnt from the fragmental relationships within a large set of"
1---2name: spectral-peak-word-embedding-representation3description: Use when when you have MS/MS spectra (LC-MS or equivalent positive ionization mode data) that you intend to embed using Word2Vec or similar distributional semantic models, or when you need to prepare spectral data for training similarity models that learn peak co-occurrence patterns rather than.4license: CC-BY-4.05---67# spectral-peak-word-embedding-representation89## Summary1011Convert mass spectrometry fragment peaks and neutral losses into word tokens suitable for Word2Vec embedding, enabling learned representation of fragmental relationships. This representation bridges spectral data and natural language processing to capture structural similarity patterns in MS/MS spectra.1213## When to use1415When you have MS/MS spectra (LC-MS or equivalent positive ionization mode data) that you intend to embed using Word2Vec or similar distributional semantic models, or when you need to prepare spectral data for training similarity models that learn peak co-occurrence patterns rather than relying on cosine-based peak matching alone.1617## When NOT to use1819- Input spectra contain fewer than 10 fragment peaks (filter these before tokenization)20- Data is GC-MS where neutral losses are not reliably measured; Spec2Vec was only demonstrated on LC-MS21- You require deterministic, directly interpretable peak alignment (cosine or modified cosine scores are more transparent)2223## Inputs2425- MS/MS spectra (mzML, mzXML, msp, MGF, or JSON format)26- Normalized spectrum object with peaks (m/z, intensity pairs) and precursor m/z27- Peak intensity matrix (relative intensities normalized to [0, 1] range)2829## Outputs3031- Spectrum-as-document representation (list of peak and loss word tokens per spectrum)32- Ordered token sequence suitable for Word2Vec gensim.models.Word2Vec input33- Peak vocabulary with token-to-m/z mapping for later embedding lookups3435## How to apply3637For each spectrum, normalize peak intensities to a maximum of 1.0. Convert each peak to a word token using the format '[redacted-email]' (binned to 2 decimal places in m/z space). Add neutral loss words by computing precursor m/z minus each peak m/z, retaining only losses in the range 5.0–200.0 Da, formatted as '[redacted-email]'. Filter peaks by intensity (relative intensity ≥ 0.01 of max) and by parent mass scaling (retain at most 0.5 × parent_mass peaks per spectrum). This tokenization transforms each spectrum into a 'document' (ordered sequence of words) that preserves both fragmental identity and neutral loss patterns, which Word2Vec then learns as a co-occurrence space. The binning precision and mass range cutoffs are justified to balance model generalization against sparsity.3839## Related tools4041- **matchms** (Provides spectral data structures, I/O loaders (mzML, MGF, msp), peak filtering, and intensity normalization functions used to prepare spectra before tokenization) — https://github.com/matchms/matchms42- **gensim** (Implements Word2Vec model training and word embedding lookups on the tokenized peak and loss sequences)43- **spec2vec** (Wraps this tokenization workflow and applies trained Word2Vec embeddings to compute spectral similarity scores based on learned peak relationships) — https://github.com/iomega/spec2vec44- **NumPy** (Used for intensity normalization and numerical operations on peak arrays)45- **Numba** (Provides JIT-compiled functions for fast computation of missing-fraction statistics and embedding aggregations across large spectra collections)4647## Examples4849```50from matchms import Spectrum; from spec2vec import Spec2VecParallel; import gensim; spectra = [Spectrum(mz=np.array([100.1, 200.2, 300.3]), intensities=np.array([0.5, 1.0, 0.3]), metadata={'precursor_mz': 400.4})]; documents = [[f'peak@{mz:.2f}' for mz in s.mz] + [f'loss@{(s.metadata["precursor_mz"] - mz):.2f}' for mz in s.mz if 5.0 <= (s.metadata["precursor_mz"] - mz) <= 200.0] for s in spectra]; model = gensim.models.Word2Vec(documents, window=10, min_count=1, epochs=15)51```5253## Evaluation signals5455- Every spectrum in the tokenized corpus contains at least 1 peak word token (spectra with <10 original peaks are filtered out; retained spectra should have ≥1 token after binning and filtering)56- Peak word vocabulary size grows monotonically with the number of unique m/z values in the input dataset; no negative vocabulary counts57- Missing-fraction metric (1 − Σ√w_i for known words / Σ√w_i for all words) computed on the held-out test set reaches ≈97% coverage when the Word2Vec model is trained on a large corpus (e.g., AllPositive dataset, 95,320 spectra, 15 epochs)58- Each loss word token falls strictly in the range 5.0–200.0 Da; losses outside this range are absent from the output59- Peak intensity normalization is correctly applied: max intensity per spectrum equals 1.0, all others ≤ 1.0; relative peak filtering (intensity < 0.01) removes the expected proportion of low-intensity peaks6061## Limitations6263- GC-MS data are not supported; neutral losses are typically not measured in GC-MS, reducing the utility of this tokenization scheme (only LC-MS demonstrated)64- Tokenization binning to 2 decimal places (m/z precision) may lose fine structural detail and may merge nearby peaks; alternative binning strategies are not explored in the article65- Unknown peaks (word tokens) not present in the trained Word2Vec model are excluded from similarity computation; this requires a model trained on a representative corpus; retraining may be necessary for experimental data with insufficient feature overlap to the training set66- Spectra with fewer than 10 fragment peaks are filtered before tokenization, discarding potentially informative low-complexity spectra67- No guidance provided on optimal loss-mass range (5.0–200.0 Da) selection for datasets with unusual precursor mass distributions6869## Evidence7071- [methods] After processing, spectra are converted to documents. For this, every peak is represented by a word that contains its position up to a defined decimal precision ("[redacted-email]"): "After processing, spectra are converted to documents. For this, every peak is represented by a word that contains its position up to a defined decimal precision ("[redacted-email]")"72- [methods] In addition to all peaks of a spectrum, neutral losses between 5.0 and 200.0 Da were added as "[redacted-email]". Neutral losses are calculated as precursor − peak: "In addition to all peaks of a spectrum, neutral losses between 5.0 and 200.0 Da were added as "[redacted-email]". Neutral losses are calculated as precursor − peak"73- [other] For each spectrum, convert peaks to words with format '[redacted-email]' (2-decimal binning) and add neutral losses (5.0–200.0 Da) as '[redacted-email]' words. Normalize peak intensities to maximum = 1 for each spectrum.: "For each spectrum, convert peaks to words with format '[redacted-email]' (2-decimal binning) and add neutral losses (5.0–200.0 Da) as '[redacted-email]' words. Normalize peak intensities to maximum = 1 for"74- [methods] the maximum number of kept peaks per spectrum was set to scale linearly with the estimated parent mass: max(n_peaks) = 0.5 × parentmass: "the maximum number of kept peaks per spectrum was set to scale linearly with the estimated parent mass: max(n_peaks) = 0.5 × parentmass"75- [methods] For both the cosine and modified cosine score calculations we ignored all peaks with relative intensities <0.01 compared to the highest intensity peak: "For both the cosine and modified cosine score calculations we ignored all peaks with relative intensities <0.01 compared to the highest intensity peak"76- [readme] Spec2Vec does so for mass fragments and neutral losses in MS/MS spectra. The spectral similarity score is based on spectral embeddings learnt from the fragmental relationships within a large set of spectral data.: "Spec2Vec does so for mass fragments and neutral losses in MS/MS spectra. The spectral similarity score is based on spectral embeddings learnt from the fragmental relationships within a large set of"
HolobiomicsLab