# Laplacian Embedding Spectral Alignment

> Use when you have two or more MS/MS fragmentation spectra (with precursor m/z, fragment m/z values, and intensities) and need to identify which fragment ions match across spectra while quantifying the statistical confidence of those matches.

- Skill: `holobiomicslab/laplacian-embedding-spectral-alignment` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/laplacian-embedding-spectral-alignment`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/laplacian-embedding-spectral-alignment/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/laplacian-embedding-spectral-alignment

---


# laplacian-embedding-spectral-alignment

## Summary

Apply Laplacian embedding to compute fragment ion similarity and statistical significance when aligning pairs of MS/MS fragmentation spectra. This skill captures both local mass difference patterns (shortest-path distance) and global spectral graph structure (average commute time) to enable robust matching across chemical structure variants.

## When to use

You have two or more MS/MS fragmentation spectra (with precursor m/z, fragment m/z values, and intensities) and need to identify which fragment ions match across spectra while quantifying the statistical confidence of those matches. Use this skill when simple mass tolerance-based matching is insufficient and you need to account for structural relationships between fragment ions (ancestors, descendants, and siblings).

## When NOT to use

- Input spectra contain fewer than 3–4 fragment ions per spectrum; Laplacian embedding requires sufficient graph structure to capture meaningful ancestor/descendant relationships.
- You only need simple binary present/absent matching without significance estimation; use naive mass tolerance filtering instead.
- Fragment ions are already grouped into known chemical families; Laplacian embedding is designed to discover these relationships de novo from mass differences.

## Inputs

- MS/MS fragmentation spectrum pair (precursor m/z, fragment m/z array, intensity array for each spectrum)
- Mass tolerance (ppm or Da) for m/z difference matching
- Optional: precursor-based neutral loss counts

## Outputs

- Matching ions report (tabulated fragment pairs with alignment scores, mass deltas, p-values/Z-scores, and metadata)
- Similarity matrix (S) of fragment ion relationships
- Maximum weight matching matrix (M)
- Comparison matrix (C) indicating symmetric (1) vs. asymmetric (-1) matches
- Spectral similarity scores with p-values and null distribution

## How to apply

First, parse the two input MS/MS spectra to extract precursor mass, fragment m/z values, and intensities. Compute a similarity matrix from pairwise mass differences (m/z deltas) between all fragment ion pairs across the two spectra using row-normalized transition probabilities of mass difference frequencies. Convert this transition matrix to the pseudo-inverse of its normalized Laplacian, which captures both shortest-path distance (property a: common mass differences) and average commute time distance (property b: structural relatedness through ancestors and descendants). Apply maximum weight matching to identify the optimal set of fragment ion pairs that maximize alignment score. Finally, perform statistical significance testing via z-test on the matched pairs using a null distribution generated by permuting intra- and inter-spectral fragment similarity scores, yielding p-values or Z-scores for each match.

## Related tools

- **SIMILE** (Python library implementing Laplacian embedding similarity matrix construction, maximum weight matching, and z-test significance calculation for fragment ion alignment) — https://github.com/biorack/simile
- **Python** (Runtime environment; SIMILE depends on numpy, scipy, and pandas for matrix operations and statistical testing)

## Examples

```
import simile as sml; S, spec_ids = sml.similarity_matrix(mzs, pmzs=pmzs, tolerance=0.1); M = sml.multiple_match(S, spec_ids); C = sml.sym_compare(M, spec_ids); spec_scores, pval, null_dist = sml.z_test(S, M, C, spec_ids, return_dist=True); df = sml.matching_ions_report(S, M, C, mzs, pmzs)
```

## Evaluation signals

- Matched fragment pairs report is non-empty and each pair has a mass delta consistent with known neutral losses or fragment fragmentation pathways (e.g., 18 Da for H₂O loss, 44 Da for CO₂).
- Symmetric matches (C = 1) outnumber asymmetric matches (C = −1) for true positive alignments; p-values for symmetric matches are significantly smaller than for random permutations.
- Z-scores and p-values follow expected distributions under the null hypothesis (histogram of p-values is uniform [0, 1] for true negatives, left-skewed for true positives).
- Maximum weight matching output includes all high-confidence fragment pairs identified by manual or reference spectral libraries; no expected pairs are missing.
- Null distribution generated by permutation is visibly distinct from observed spectral similarity scores, confirming that the matching is not due to chance.

## Limitations

- Laplacian embedding requires sufficient fragmentation complexity (minimum ~3–4 fragment ions per spectrum); sparse spectra may yield unreliable significance estimates.
- The method assumes that fragment ion similarity is driven by mass difference frequency and structural graph properties; it may fail for non-standard fragmentation pathways or heavily modified peptides where mass differences are atypical.
- Multiple comparison correction is required when testing many spectrum pairs simultaneously; the README notes that 'current research in multiple comparison is exploring using the asymmetry of the SIMILE max weight matrix as an alternative'.
- Python 3.7 pinning due to non-SIMILE bugs may limit compatibility with newer dependency versions.

## Evidence

- [readme] Fragment ions are similar if the difference in mass between them is common.: "Fragment ions are similar if the difference in mass between them is common."
- [readme] Fragment ions are similar if their ancestor and descendent fragment ions are similar.: "Fragment ions are similar if their ancesetor and descendent fragment ions are similar."
- [readme] This corresponds to an 'average commute time' distance between fragment ions with the following intuition: If instead of taking the shortest path between x and y we instead meander about according to the transition matrix, how long will it take to wander from x to y and back to x on average?: "This corresponds to an 'average commute time' distance between fragment ions with the following intuition: If instead of taking the shortest path between x and y we instead meander about according to"
- [intro] Maximum weight matching is used instead of original monotonic alignment method with improved performance.: "Maximum weight matching is used instead of original monotonic alignment method with improved performance"
- [readme] Taking this line of reasoning to its natural conclusion yields a null distibution generated by permuting intra and inter spectral fragment similarity scores to yield p-values.: "Taking this line of reasoning to its natural conclusion yields a null distibution generated by permuting intra and inter spectral fragment similarity scores to yield p-values."
- [other] Compute pairwise mass differences (m/z deltas) between all fragment ions across the two spectra.: "Compute pairwise mass differences (m/z deltas) between all fragment ions across the two spectra."
- [other] Generate a matching ions report tabulating all matched fragment pairs, their scores, mass deltas, and significance metrics with associated metadata.: "Generate a matching ions report tabulating all matched fragment pairs, their scores, mass deltas, and significance metrics with associated metadata."