Ms Ms Spectrum Statistical Significance Testing

---
name: ms-ms-spectrum-statistical-significance-testing
description: 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.
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3799
  edam_topics:
  - http://edamontology.org/topic_0121
  - http://edamontology.org/topic_3520
  tools:
  - SIMILE
  - Python
  techniques:
  - LC-MS
  license_tier: open
  provenance_tier: literature
derived_from:
- doi: 10.1038/s41467-022-30118-9
  title: SIMILE
evidence_spans:
- SIMILE (Significant Interrelation of MS/MS Ions via Laplacian Embedding) is a Python
  library
- is a Python library for interrelating fragmentation spectra with significance estimation
claims: []
provenance:
  collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v2
  assembled_by: scripts/collect_metabolomics_collection.py
  sources:
  - build: coll_simile_cq
    doi: 10.1038/s41467-022-30118-9
    title: SIMILE
  dedup_kept_from: coll_simile_cq
schema_version: 0.2.0
attribution:
  generator: AgenticScienceBuilder
  original_doi: 10.1038/s41467-022-30118-9
  all_source_dois:
  - 10.1038/s41467-022-30118-9
  zenodo_doi: 10.5281/zenodo.20794027
  curators: []
  promoter: Louis-Félix Nothias
  sponsor: CNRS & Université Côte d'Azur
---

# 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"