Ms2 fingerprint distance calculation

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"