Spectral Peak Binning And Vectorization

---
name: spectral-peak-binning-and-vectorization
description: Use when you have raw MS/MS spectra with variable numbers of peaks at continuous m/z values and need to feed them to a neural network (e.g., Siamese network for similarity prediction) that requires fixed-size vector input.
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3632
  edam_topics:
  - http://edamontology.org/topic_0121
  - http://edamontology.org/topic_3370
  tools:
  - matchms
  - Python
  - ms2deepscore
  - Python (NumPy, TensorFlow/PyTorch)
derived_from:
- doi: 10.1186/s13321-021-00558-4
  title: MS2DeepScore
evidence_spans:
- Metadata was cleaned and checked using matchms [18] version 0.8.2, which included cleaning compound names
- Our MS2DeepScore Python library offers two types of data generators
- Our MS2DeepScore Python library
claims: []
provenance:
  collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v1
  assembled_by: scripts/collect_metabolomics_collection.py
  sources:
  - build: coll_ms2deepscore
    doi: 10.1186/s13321-021-00558-4
    title: MS2DeepScore
  dedup_kept_from: coll_ms2deepscore
schema_version: 0.2.0
---

# spectral-peak-binning-and-vectorization

## Summary

Convert a raw tandem mass spectrum (peaks at arbitrary m/z locations with varying intensities) into a fixed-dimensional numerical vector by binning peaks into equally-spaced m/z windows and applying intensity transformation. This preprocessing step prepares MS/MS spectra for neural network input and enables downstream similarity scoring.

## When to use

You have raw MS/MS spectra with variable numbers of peaks at continuous m/z values and need to feed them to a neural network (e.g., Siamese network for similarity prediction) that requires fixed-size vector input. Use this when spectra originate from GNPS, MassBank, or other repositories and must be standardized to a 10,000-dimensional representation covering the 10–1000 m/z range.

## When NOT to use

- Input spectrum has already been converted to a fixed-size vector or feature representation.
- You are working with ion mobility, drift time, or retention time data rather than m/z-based fragmentation spectra.
- The m/z range of your spectra extends substantially below 10 or above 1000; binning will lose or truncate out-of-range peaks.
- You require lossless reconstruction of original peak positions and intensities; binning to 10,000 discrete bins introduces quantization error.

## Inputs

- raw MS/MS spectrum object with peaks (m/z values and intensity pairs)
- spectrum metadata including maximum peak intensity for normalization

## Outputs

- binned spectrum vector (10,000 or 9,948 dimensions, float32/float64)
- square-root-transformed intensity values in [0, ~1] range

## How to apply

First, filter the spectrum by removing peaks with intensities < 0.1% of the maximum peak intensity and retaining only the 1,000 highest-intensity peaks to reduce noise and computational burden. Square-root-transform all remaining peak intensities to avoid over-weighting the highest peaks. Bin the transformed peaks into 10,000 equally-spaced bins spanning m/z 10–1000 (each bin ~0.099 m/z wide). Assign each peak to the nearest bin and record its square-root-transformed intensity in that bin (setting zero-intensity bins to 0). The output is a 9,948-dimensional vector (after filtering to active m/z range) that can be passed directly to a dense neural network layer for embedding computation.

## Related tools

- **matchms** (Metadata cleaning, peak filtering, and spectrum I/O for preparing raw MS/MS data before binning) — https://github.com/matchms/matchms
- **ms2deepscore** (Applies binning as part of the data preparation pipeline before passing vectors to the Siamese network base network) — https://github.com/matchms/ms2deepscore
- **Python (NumPy, TensorFlow/PyTorch)** (Implementation of binning logic, intensity transformation, and vector construction)

## Examples

```
```python
import numpy as np
from matchms.filtering import normalize_intensities, remove_peaks_below_threshold, select_top_n_peaks

# Load and clean spectrum using matchms
spectrum = normalize_intensities(spectrum)
spectrum = remove_peaks_below_threshold(spectrum, threshold=0.001)  # 0.1% of max
spectrum = select_top_n_peaks(spectrum, n=1000)

# Bin into 10,000 bins (10–1000 m/z)
mz_array = np.sqrt(spectrum.peaks.mz)
intensity_array = np.sqrt(spectrum.peaks.intensity)
binned_spectrum = np.zeros(10000)
bins = np.digitize(mz_array, bins=np.linspace(10, 1000, 10001)) - 1
for i, b in enumerate(bins):
    if 0 <= b < 10000:
        binned_spectrum[b] = max(binned_spectrum[b], intensity_array[i])
```
```

## Evaluation signals

- Output vector has exactly 10,000 dimensions (or 9,948 after m/z filtering) with no NaN or Inf values.
- All non-zero bin values are in range [0, ~1] after square-root transformation (verify by checking max/min of non-zero entries).
- Peaks outside m/z 10–1000 are either truncated or handled consistently; no peaks appear in bins outside the designated range.
- Spectral energy is conserved: sum of binned intensities correlates strongly with sum of original (transformed) peak intensities (r > 0.99).
- When applied to a reference spectrum multiple times, output vector remains identical (deterministic binning), and t-SNE/UMAP visualization of embeddings derived from binned vectors shows meaningful chemical clusters (validated against molecular fingerprint Tanimoto scores).

## Limitations

- Binning to 10,000 fixed bins across m/z 10–1000 assumes all spectra fall within this range; spectra with m/z < 10 or > 1000 will have peaks truncated or lost.
- The square-root transformation reduces but does not eliminate the dominance of high-intensity peaks; low-abundance diagnostic peaks may be further suppressed.
- Binning introduces quantization error; two peaks within the same bin are indistinguishable in the vector representation.
- The method is not suitable for very sparse spectra (few peaks) or spectra with unusual isotope patterns, as binning may obscure fine structural detail.
- No explicit handling of peptide cross-linking, neutral loss pathways, or multi-stage MS/MS cascades; the method treats all m/z regions uniformly.

## Evidence

- [methods] Spectrum peaks were binned in 10,000 equally-sized bins ranging from 10 to 1000 m/z: "Spectrum peaks were binned in 10,000 equally-sized bins ranging from 10 to 1000 m/z"
- [methods] The spectra underwent basic filtering to remove excessive amounts of peaks, by removing peaks with intensities < 0.1% of the maximum peak intensity and limiting the maximum number of peaks to the 1000 highest intensity peaks: "The spectra underwent basic filtering to remove excessive amounts of peaks, by removing peaks with intensities < 0.1% of the maximum peak intensity and limiting the maximum number of peaks to the"
- [methods] Peak intensities were square root transformed to avoid a too strong focus on the highest intensity peaks only: "Peak intensities were square root transformed to avoid a too strong focus on the highest intensity peaks only"
- [other] Load a binned MS/MS spectrum vector (9948-dimensional, with peaks binned into 10–1000 m/z range at 10,000 equally-spaced bins, square-root-transformed intensities): "Load a binned MS/MS spectrum vector (9948-dimensional, with peaks binned into 10–1000 m/z range at 10,000 equally-spaced bins, square-root-transformed intensities)"
- [readme] To calculate chemical similarity scores, MS2DeepScore first calculates an embedding (vector) representing each spectrum.: "To calculate chemical similarity scores, MS2DeepScore first calculates an embedding (vector) representing each spectrum."