# Ms Ms Spectrum Statistical Significance Testing

> Use when you have aligned fragment ion pairs from two MS/MS spectra (via maximum weight matching or other methods) and need to assign p-values or Z-scores to each matched pair to distinguish true biological/chemical relationships from random noise.

- Skill: `holobiomicslab/ms-ms-spectrum-statistical-significance-testing` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/ms-ms-spectrum-statistical-significance-testing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/ms-ms-spectrum-statistical-significance-testing/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/ms-ms-spectrum-statistical-significance-testing

---


# MS/MS spectrum statistical significance testing

## Summary

Compute statistical significance scores for fragment ion matches between pairs of tandem mass spectra using Laplacian embedding and null distribution permutation testing. This skill enables confidence-ranked alignment of MS/MS spectra robust to multiple chemical structure differences.

## When to use

Apply this skill when you have aligned fragment ion pairs from two MS/MS spectra (via maximum weight matching or other methods) and need to assign p-values or Z-scores to each matched pair to distinguish true biological/chemical relationships from random noise. Essential when comparing spectra from compounds with unknown or variable structural modifications.

## When NOT to use

- Spectra have not yet been aligned or matched; apply maximum weight matching first.
- Single-spectrum analysis; this skill requires pairwise comparison and intraspectral permutation baseline.
- Fragment ion pairs are already confirmed true matches by independent orthogonal validation; significance testing adds no additional confidence.

## Inputs

- Precursor m/z values (pmzs) for each spectrum
- Fragment m/z values (mzs) for each spectrum
- Fragment ion intensities
- Similarity matrix (S) of fragment ion similarity scores
- Maximum weight matching matrix (M) of aligned fragment pairs
- Spectrum identifiers and metadata

## Outputs

- Per-spectrum Z-scores or p-values for alignment significance
- Null distribution of intraspectral similarity scores
- Global p-value for the matched fragment ion set
- Matching ions report with mass deltas, similarity scores, and significance metrics

## How to apply

After constructing a similarity matrix from pairwise fragment m/z deltas and a maximum weight matching of fragment ion pairs across two spectra, compute a pro/con comparison matrix where symmetric matches score +1 and asymmetric matches score −1. Feed the similarity matrix, maximum weight matching, comparison matrix, and spectrum IDs into a Z-test that leverages an intraspectral null distribution generated by permuting intra- and inter-spectral fragment similarity scores. This null distribution reflects the expected distribution of fragment sibling relationships within a single spectrum, allowing the test to contextualize interspectral matches. The Z-test yields per-pair Z-scores and a global p-value for the overall spectral alignment.

## Related tools

- **SIMILE** (Python library implementing Laplacian embedding-based similarity measure, maximum weight matching, and Z-test for MS/MS spectrum significance estimation) — https://github.com/biorack/simile
- **Python** (Runtime and ecosystem (numpy, scipy, pandas) for numerical computation of similarity matrices, matching, and permutation testing)

## Examples

```
spec_scores, pval, null_dist = sml.z_test(S, M, C, spec_ids, return_dist=True, log_size=5); df = sml.matching_ions_report(S, M, C, mzs, pmzs)
```

## Evaluation signals

- Output p-values are in the range [0, 1] and correspond to the expected null distribution shape; global p-value is more conservative than individual pair p-values.
- Symmetric fragment ion matches (appearing in both forward and reverse spectrum comparisons) yield higher Z-scores and lower p-values than asymmetric matches.
- Matched fragment pairs with larger mass deltas or lower intra-spectral similarity frequencies yield more significant p-values when they appear in interspectral alignments.
- Permutation null distribution is unimodal and centered near zero; empirical p-value calculation is consistent across repeated random seeds.
- Matching ions report contains all matched pairs with no missing p-values or NaN scores; metadata columns (precursor mass, neutral loss, intensity) are populated and consistent with input spectra.

## Limitations

- Significance testing is most robust when spectra have sufficient fragment ion diversity; sparse spectra with few fragments may produce unreliable null distributions.
- The intraspectral permutation null distribution assumes that sibling relationships within a single spectrum are representative of true false-positive rates in interspectral comparison; this assumption may fail for highly biased or fragmentation-method-specific spectral collections.
- Multiple comparison correction is mentioned as ongoing research; current implementation does not automatically adjust p-values for multiple hypothesis tests when comparing many spectrum pairs simultaneously.
- Python 3.7 pinned requirement due to non-SIMILE bugs; compatibility with newer Python versions may require environment configuration.

## Evidence

- [readme] Laplacian embedding similarity measure and null distribution methodology: "Fragment ions are similar if the difference in mass between them is common. Fragment ions are similar if their ancestor and descendent fragment ions are similar."
- [readme] Pro/con comparison matrix construction and Z-test input: "Generate pro/con comparison matrix such that symmetric matches are 1 (pro) and asymmetric matches are -1 (con)"
- [readme] Null distribution generation mechanism: "leveraging intraspectral comparisons to add confidence to interspectral comparisons"
- [readme] Output artifacts including matching report: "Report back mass deltas and scores for simile comparison"
- [intro] Multiple comparison statistics and faster testing in V2: "Multiple comparison statistics, MUCH faster mass delta counting and significance testing"
- [intro] Robustness to structural diversity: "SIMILE is a Python library for interrelating fragmentation spectra with significance estimation and is robust to multiple differences in chemical structure"