Research question and scope
A spectrum can support a candidate annotation without uniquely identifying a compound. matchms imports, processes and compares tandem spectra; MS2DeepScore predicts chemical similarity from spectral pairs using a trained model; SIRIUS supports molecular-formula and candidate-structure workflows; GNPS2 provides hosted library and networking workflows. These outputs answer different questions.
Prerequisites
Prepare spectra in a format accepted by the chosen tool, such as MGF where documented. For each spectrum preserve sample/source ID, precursor m/z, adduct, polarity, collision energy, instrument context, acquisition date and raw-file reference. Check data rights and privacy before uploading anything to a hosted service. Record software versions, model weights, library release and score settings.
Workflow
- Inspect spectra and metadata for missing precursor or inconsistent polarity/adduct. Select and record peak-cleaning and mass-tolerance rules before comparing spectra.
- In a local branch, import and clean with matchms, then compute a declared similarity metric. If using MS2DeepScore, record the exact pretrained model and its training-domain caveats; its predicted chemical similarity is not a structure identification. The official example documents model loading and a matchms pipeline.
- In separate branches, submit suitable spectra to SIRIUS for formula/candidate ranking and, if allowed, to GNPS2 for library search or molecular networking. Record inputs and job IDs, and read each service’s current account, data-sharing and license terms. Do not imply SIRIUS and GNPS2 results have been automatically reconciled. No analysis was run for this article.
How to interpret and check the output
For every candidate, retain the originating spectrum, matched peaks and tolerances, precursor/adduct assumptions, tool and model version, library identity, score and rank. A high similarity score indicates similarity under a method, not a unique structure. Formula and structure ranks are hypotheses; standards, retention behavior and independent experimental evidence are needed for stronger identification.
Limits and common errors
Different ionization modes, collision energies and noisy or chimeric spectra can make comparisons misleading. A model trained on other chemical space may extrapolate poorly. SIRIUS includes hosted services whose stated use conditions differ from its downloadable code; GNPS2 is a web platform. Check current terms before sending private spectra and keep an offline-only branch if data cannot leave the lab.
Related ChemAI Atlas pages
Resources: Matchms, MS2DeepScore, SIRIUS, GNPS. Related guide: Dataset Provenance and Licensing for Chemistry AI.
Primary sources
- https://matchms.readthedocs.io/en/latest/ (official source; accessed 2026-10-13)
- https://github.com/matchms/ms2deepscore (official source; accessed 2026-10-13)
- https://github.com/sirius-ms/sirius/blob/stable/README.md (official source; accessed 2026-10-13)
- https://gnps2.org/homepage (official source; accessed 2026-10-13)
- https://ccms-ucsd.github.io/GNPSDocumentation/networking/ (official source; accessed 2026-10-13)