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