Ms2 Fingerprint Distance Calculation

---
name: ms2-fingerprint-distance-calculation
description: Use when after MS2 fingerprints have been generated by counting MS2 peaks and neutral losses in each sample, and you have aligned them into a MemoMatrix (sample-by-fingerprint matrix).
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3365
  edam_topics:
  - http://edamontology.org/topic_3172
  - http://edamontology.org/topic_0091
  tools:
  - Python 3.8
  - numpy
  - scikit-bio
  - MEMO
  - memo-ms
  - matchms
derived_from:
- doi: 10.3389/fbinf.2022.842964
  title: memo
evidence_spans:
- conda create --name memo python=3.8
- pip install numpy
- conda install -c conda-forge scikit-bio
claims: []
provenance:
  collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v1
  assembled_by: scripts/collect_metabolomics_collection.py
  sources:
  - build: coll_memo
    doi: 10.3389/fbinf.2022.842964
    title: memo
  dedup_kept_from: coll_memo
schema_version: 0.2.0
---

# ms2-fingerprint-distance-calculation

## Summary

Compute pairwise sample distances from MS2 fingerprint vectors to quantify dissimilarity between metabolomics samples in a sample-by-fingerprint matrix. This step produces a distance matrix that serves as input for downstream dimensionality reduction (MDS/PCoA) and sample comparison visualization.

## When to use

After MS2 fingerprints have been generated by counting MS2 peaks and neutral losses in each sample, and you have aligned them into a MemoMatrix (sample-by-fingerprint matrix). Use this skill when you need to compare multiple samples and want to measure pairwise dissimilarity before visualizing sample relationships in low-dimensional space.

## When NOT to use

- Your input is already a pre-computed distance matrix — skip to MDS/PCoA directly.
- Fingerprints have not yet been aligned or are in raw, unaligned format — align them first.
- You are working with individual MS/MS spectra rather than aggregated sample fingerprints — use spectrum-to-spectrum similarity measures instead (e.g., matchms cosine similarity).

## Inputs

- MemoMatrix file (sample-by-fingerprint matrix in tabular or HDF5 format)
- aligned MS2 fingerprint vectors (rows = samples, columns = MS2 peak/neutral loss features)

## Outputs

- pairwise distance matrix (n_samples × n_samples)
- distance matrix in condensed (upper triangle) or square format, suitable for MDS/PCoA input

## How to apply

Load the MemoMatrix file (sample-by-fingerprint matrix) using memo-ms, then compute pairwise sample distances from the fingerprint vectors using distance metrics appropriate for sparse count data (e.g., Euclidean, Bray-Curtis, or cosine distance). The resulting distance matrix has dimensions (n_samples × n_samples) and quantifies dissimilarity between all sample pairs. Choose the distance metric based on the nature of your fingerprint data: Euclidean distance works well for normalized vectors, while Bray-Curtis or cosine distance are suited for count-based fingerprints. This distance matrix becomes the input for MDS or PCoA dimensionality reduction, allowing visual comparison of samples in 2D space.

## Related tools

- **MEMO** (MS2-based sample vectorization framework that encapsulates fingerprint generation and distance computation) — https://github.com/mandelbrot-project/memo
- **memo-ms** (Python package for loading and manipulating MemoMatrix files and computing fingerprint distances) — https://pypi.org/project/memo-ms/
- **scikit-bio** (Provides distance metric implementations (e.g., Bray-Curtis, Euclidean) for pairwise sample comparisons) — https://scikit-bio.org/
- **numpy** (Numerical library for matrix operations and distance computation from fingerprint vectors) — https://numpy.org/
- **matchms** (Underlying library for MS/MS spectrum handling that supports MEMO's fingerprint generation) — https://github.com/matchms/matchms

## Examples

```
from memo_ms import MemoMatrix; from scipy.spatial.distance import pdist, squareform; import numpy as np; mm = MemoMatrix.load('sample_fingerprints.csv'); fingerprints = mm.values; distances = squareform(pdist(fingerprints, metric='euclidean'))
```

## Evaluation signals

- Distance matrix is symmetric and has zero diagonal (d[i,i] = 0)
- All distances are non-negative (≥ 0) and respect the metric properties of the chosen distance function
- Distance matrix shape matches (n_samples, n_samples) where n_samples is the number of rows in the input MemoMatrix
- Distances are bounded appropriately for the metric (e.g., 0–1 for normalized cosine distance, 0–2 for Euclidean on unit vectors)
- Samples with identical or very similar MS2 fingerprints yield small distances; samples from different groups or chemical backgrounds yield larger distances

## Limitations

- Distance computation is sensitive to the choice of metric; no single metric is optimal for all MS2 fingerprint comparisons — Euclidean and Bray-Curtis yield different insights.
- MS2 fingerprints based on peak/neutral loss counts may be biased toward high-abundance samples; normalization of fingerprints before distance calculation is recommended.
- Sparse or incomplete fingerprints (e.g., samples with very few detected MS2 features) may produce unreliable distance estimates.
- Large sample sets (n > 10,000) incur quadratic memory and time costs for full distance matrix computation; consider approximate methods or subset sampling for scalability.

## Evidence

- [other] Compute pairwise sample distances from the fingerprint vectors: "Compute pairwise sample distances from the fingerprint vectors."
- [other] Load the MemoMatrix file (sample-by-fingerprint matrix) using memo-ms: "Load the MemoMatrix file (sample-by-fingerprint matrix) using memo-ms."
- [intro] MS2 fingerprints generated by counting occurrences of peaks and neutral losses: "The occurence of MS2 peaks and neutral losses (to the precursor) in each sample is counted and used to generate an *MS2 fingerprint* of the sample"
- [intro] Fingerprints can be aligned to compare different samples: "These fingerprints can in a second stage be aligned to compare different samples"
- [other] MEMO applies MDS/PCoA techniques to aligned MS2 fingerprints to generate low-dimensional embeddings: "MEMO applies MDS/PCoA visualization techniques to aligned MS2 fingerprints to generate low-dimensional embeddings that enable visual comparison of different samples"