feature-occurrence-counting-across-spectra
Summary
Count the occurrence of MS2 peaks and neutral losses across all spectra within a metabolomics sample to generate a sample-level MS2 fingerprint. This aggregation enables retention-time-agnostic sample comparison and is particularly useful for chemodiverse datasets with poor feature overlap or strong retention time shifts.
When to use
When you have parsed MS2 spectra from a single metabolomics sample (via matchms or similar) and need to generate a sample-level feature vector that represents the chemical composition independently of chromatographic alignment. Use this when comparing samples acquired on different LC methods, mass spectrometers, or with significant retention time drift, or when features show poor overlap across samples.
When NOT to use
- Input is already a pre-computed feature table or fingerprint (avoid double-counting).
- Spectra have not yet been parsed or normalized (use matchms preprocessing first).
- Sample contains only a single MS2 spectrum (occurrence counting requires multiple spectra for meaningful aggregation).
Inputs
- MS2 spectra file (mzML, mzXML, msp, MGF, or JSON format)
- Sample identifier or batch of spectra from a single sample
Outputs
- MS2 fingerprint: dictionary or feature vector mapping peak m/z values to occurrence counts
- MS2 fingerprint: dictionary or feature vector mapping neutral loss values to occurrence counts
- Serialized fingerprint (JSON or CSV file) with peak/loss identifiers and their frequencies
How to apply
Load all MS2 spectra from the sample file using matchms to parse and normalize fragmentation data. Extract all m/z peak values from each spectrum and compute neutral losses by subtracting each peak m/z from its precursor m/z value. Iterate through all spectra in the sample and count the total occurrences of each unique peak m/z and neutral loss identifier, accumulating these counts in a dictionary or feature vector. Aggregate these counts such that each peak/loss identifier maps to its total frequency across the entire sample. Finally, serialize the resulting MS2 fingerprint (peak/loss identifiers with their occurrence counts) as a structured output (JSON or CSV) for downstream alignment and comparison steps.
Related tools
- matchms (Parses, normalizes, and extracts m/z peaks and metadata from raw MS2 spectra files in multiple formats (mzML, mzXML, msp, MGF, JSON)) — https://github.com/matchms/matchms
- spec2vec (Provides spectral embedding and similarity measures that build on MS2 fingerprints and neutral loss relationships for downstream sample comparison) — https://github.com/iomega/spec2vec
- MEMO (Implements the full MS2 fingerprint generation and sample vectorization workflow, including occurrence counting and aggregation) — https://github.com/mandelbrot-project/memo
- numpy (Provides efficient array operations for counting and aggregating peak/loss frequencies into feature vectors)
- Python (Core language for scripting the occurrence counting workflow; MEMO requires Python >= 3.8)
Examples
from matchms.importing_utils import load_from_json; from memo import fingerprint_from_spectra; spectra = load_from_json('sample.json'); fingerprint = fingerprint_from_spectra(spectra); import json; json.dump(fingerprint, open('ms2_fingerprint.json', 'w'))
Evaluation signals
- Verify that the count for each peak m/z or neutral loss is a positive integer ≥ 1 (no zero-occurrence features should be present in the fingerprint).
- Confirm that the sum of all occurrence counts equals the total number of MS2 spectra in the sample (each spectrum contributes peaks and losses).
- Check that neutral loss values are all positive and less than or equal to the precursor m/z (no negative or out-of-range losses).
- Validate that peak m/z values fall within the expected mass range for the MS instrument (e.g., 50–2000 m/z for typical metabolomics).
- Ensure the serialized fingerprint contains only non-redundant (unique) peak and loss identifiers with no duplicate keys in the output dictionary or feature vector.
Limitations
- Occurrence counting discards intensity and mass accuracy information from individual peaks, retaining only presence/absence and frequency.
- The method is retention-time agnostic by design but may conflate isobaric compounds that produce identical MS2 fragmentation patterns.
- Requires normalization and quality filtering of input spectra (e.g., removal of low-quality spectra) to avoid noise skewing fingerprint composition; filtering of peaks/losses from blank samples is recommended to reduce systematic background.
- Neutral loss calculation depends on accurate precursor m/z assignment; errors in precursor mass directly propagate to neutral loss counts.
Evidence
- [intro] The occurence of MS2 peaks and neutral losses (to the precursor) in each sample is counted and used to generate an MS2 fingerprint: "The occurence of MS2 peaks and neutral losses (to the precursor) in each sample is counted and used to generate an MS2 fingerprint"
- [other] Extract all m/z peaks from each MS2 spectrum and compute neutral losses by subtracting each peak m/z from the precursor m/z. Count the total occurrences of each unique peak m/z and neutral loss value across all spectra in the sample.: "Extract all m/z peaks from each MS2 spectrum and compute neutral losses by subtracting each peak m/z from the precursor m/z. Count the total occurrences of each unique peak m/z and neutral loss value"
- [other] MEMO is mainly built on
matchms_ and spec2vec_ packages for handling the MS2 spectra: "MEMO is mainly built on matchms_ and spec2vec_ packages for handling the MS2 spectra"
- [other] MEMO suits particularly well to compare chemodiverse samples, ie with a poor features overlap, or to compare samples with a strong RT shift: "MEMO suits particularly well to compare chemodiverse samples, i.e. with a poor features overlap, or to compare samples with a strong RT shift"
- [intro] different filtering (remove peaks/losses from blanks for example) and visualization techniques (MDS/PCoA, TMAP, Heatmap, ...) can be used: "different filtering (remove peaks/losses from blanks for example) and visualization techniques (MDS/PCoA, TMAP, Heatmap, ...) can be used"
1---2name: feature-occurrence-counting-across-spectra3description: Use when when you have parsed MS2 spectra from a single metabolomics sample (via matchms or similar) and need to generate a sample-level feature vector that represents the chemical composition independently of chromatographic alignment.4license: CC-BY-4.05---67# feature-occurrence-counting-across-spectra89## Summary1011Count the occurrence of MS2 peaks and neutral losses across all spectra within a metabolomics sample to generate a sample-level MS2 fingerprint. This aggregation enables retention-time-agnostic sample comparison and is particularly useful for chemodiverse datasets with poor feature overlap or strong retention time shifts.1213## When to use1415When you have parsed MS2 spectra from a single metabolomics sample (via matchms or similar) and need to generate a sample-level feature vector that represents the chemical composition independently of chromatographic alignment. Use this when comparing samples acquired on different LC methods, mass spectrometers, or with significant retention time drift, or when features show poor overlap across samples.1617## When NOT to use1819- Input is already a pre-computed feature table or fingerprint (avoid double-counting).20- Spectra have not yet been parsed or normalized (use matchms preprocessing first).21- Sample contains only a single MS2 spectrum (occurrence counting requires multiple spectra for meaningful aggregation).2223## Inputs2425- MS2 spectra file (mzML, mzXML, msp, MGF, or JSON format)26- Sample identifier or batch of spectra from a single sample2728## Outputs2930- MS2 fingerprint: dictionary or feature vector mapping peak m/z values to occurrence counts31- MS2 fingerprint: dictionary or feature vector mapping neutral loss values to occurrence counts32- Serialized fingerprint (JSON or CSV file) with peak/loss identifiers and their frequencies3334## How to apply3536Load all MS2 spectra from the sample file using matchms to parse and normalize fragmentation data. Extract all m/z peak values from each spectrum and compute neutral losses by subtracting each peak m/z from its precursor m/z value. Iterate through all spectra in the sample and count the total occurrences of each unique peak m/z and neutral loss identifier, accumulating these counts in a dictionary or feature vector. Aggregate these counts such that each peak/loss identifier maps to its total frequency across the entire sample. Finally, serialize the resulting MS2 fingerprint (peak/loss identifiers with their occurrence counts) as a structured output (JSON or CSV) for downstream alignment and comparison steps.3738## Related tools3940- **matchms** (Parses, normalizes, and extracts m/z peaks and metadata from raw MS2 spectra files in multiple formats (mzML, mzXML, msp, MGF, JSON)) — https://github.com/matchms/matchms41- **spec2vec** (Provides spectral embedding and similarity measures that build on MS2 fingerprints and neutral loss relationships for downstream sample comparison) — https://github.com/iomega/spec2vec42- **MEMO** (Implements the full MS2 fingerprint generation and sample vectorization workflow, including occurrence counting and aggregation) — https://github.com/mandelbrot-project/memo43- **numpy** (Provides efficient array operations for counting and aggregating peak/loss frequencies into feature vectors)44- **Python** (Core language for scripting the occurrence counting workflow; MEMO requires Python >= 3.8)4546## Examples4748```49from matchms.importing_utils import load_from_json; from memo import fingerprint_from_spectra; spectra = load_from_json('sample.json'); fingerprint = fingerprint_from_spectra(spectra); import json; json.dump(fingerprint, open('ms2_fingerprint.json', 'w'))50```5152## Evaluation signals5354- Verify that the count for each peak m/z or neutral loss is a positive integer ≥ 1 (no zero-occurrence features should be present in the fingerprint).55- Confirm that the sum of all occurrence counts equals the total number of MS2 spectra in the sample (each spectrum contributes peaks and losses).56- Check that neutral loss values are all positive and less than or equal to the precursor m/z (no negative or out-of-range losses).57- Validate that peak m/z values fall within the expected mass range for the MS instrument (e.g., 50–2000 m/z for typical metabolomics).58- Ensure the serialized fingerprint contains only non-redundant (unique) peak and loss identifiers with no duplicate keys in the output dictionary or feature vector.5960## Limitations6162- Occurrence counting discards intensity and mass accuracy information from individual peaks, retaining only presence/absence and frequency.63- The method is retention-time agnostic by design but may conflate isobaric compounds that produce identical MS2 fragmentation patterns.64- Requires normalization and quality filtering of input spectra (e.g., removal of low-quality spectra) to avoid noise skewing fingerprint composition; filtering of peaks/losses from blank samples is recommended to reduce systematic background.65- Neutral loss calculation depends on accurate precursor m/z assignment; errors in precursor mass directly propagate to neutral loss counts.6667## Evidence6869- [intro] The occurence of MS2 peaks and neutral losses (to the precursor) in each sample is counted and used to generate an *MS2 fingerprint*: "The occurence of MS2 peaks and neutral losses (to the precursor) in each sample is counted and used to generate an *MS2 fingerprint*"70- [other] Extract all m/z peaks from each MS2 spectrum and compute neutral losses by subtracting each peak m/z from the precursor m/z. Count the total occurrences of each unique peak m/z and neutral loss value across all spectra in the sample.: "Extract all m/z peaks from each MS2 spectrum and compute neutral losses by subtracting each peak m/z from the precursor m/z. Count the total occurrences of each unique peak m/z and neutral loss value"71- [other] MEMO is mainly built on `matchms`_ and `spec2vec`_ packages for handling the MS2 spectra: "MEMO is mainly built on `matchms`_ and `spec2vec`_ packages for handling the MS2 spectra"72- [other] MEMO suits particularly well to compare chemodiverse samples, ie with a poor features overlap, or to compare samples with a strong RT shift: "MEMO suits particularly well to compare chemodiverse samples, *i.e.* with a poor features overlap, or to compare samples with a strong RT shift"73- [intro] different filtering (remove peaks/losses from blanks for example) and visualization techniques (MDS/PCoA, TMAP, Heatmap, ...) can be used: "different filtering (remove peaks/losses from blanks for example) and visualization techniques (MDS/PCoA, TMAP, Heatmap, ...) can be used"
