Similarity score computation

Similarity-Score Computation for EI Mass Spectral Library Search

License: restricted — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution. <!-- asb-license-banner -->

Summary

Compute normalized similarity scores between a query electron ionization mass spectrum and library entries using the Identity (EI Normal) or Similarity (EI Simple) algorithm. This skill enables ranking of potential compound matches in spectral databases by their computed similarity to the query spectrum.

When to use

When you have a query electron ionization mass spectrum (m/z and intensity pairs) and need to identify the most similar spectra from an MSP-formatted spectral library. Apply this skill when your research goal is to find candidate compound identifications ranked by spectral similarity rather than exact matching.

When NOT to use

• Input library is not in MSP format or is already in a pre-parsed internal representation
• Query spectrum is from a different ionization method (e.g., ESI, APCI) — the Identity/Similarity algorithms are designed specifically for electron ionization
• You require exact nominal mass matches without intensity-weighted similarity scoring

Inputs

• Query electron ionization mass spectrum (m/z-intensity pairs)
• MSP-formatted spectral library file

Outputs

• Ranked table of library matches with computed similarity scores
• Match metadata (library entry identifier, compound name, score)

How to apply

Load the query EI mass spectrum and parse the spectral library from an MSP file. Apply the Identity (EI Normal) algorithm or Similarity (EI Simple) algorithm to compute similarity scores between the query spectrum and each library entry. The algorithm normalizes peak intensities and matches m/z values according to its specification. Rank library entries by descending similarity score to produce a scored match table. Select the algorithm based on your matching stringency requirements: Identity (EI Normal) typically applies stricter criteria for peak matching than Similarity (EI Simple).

Related tools

• mssearchr (Implements custom Identity (EI Normal) and Similarity (EI Simple) algorithms for spectral similarity scoring and MSP file I/O) — https://github.com/AndreySamokhin/mssearchr
• R (Host language and runtime environment for mssearchr package execution)
• NIST API (Alternative library search backend via external nistms$.exe integration)

Evaluation signals

• Similarity scores are in a normalized range (typically 0–1 or 0–1000) with no missing or invalid values
• All library entries produce a score; no entries are silently skipped
• Ranked output is sorted in descending order by similarity score
• Top-ranked match has been manually verified against known reference spectra or a ground-truth compound identifier
• Score distributions and magnitude ranges match expected algorithm behavior (e.g., Identity scores are generally lower/stricter than Similarity scores for the same query-library pair)

Limitations

• Algorithm is specific to electron ionization mass spectra; not applicable to other ionization techniques
• Similarity score alone does not guarantee correct compound identification; additional validation against retention time, molecular weight, or orthogonal methods is recommended
• Performance and accuracy depend on the quality and completeness of the MSP library; sparse or poorly-curated libraries will yield low-confidence matches
• No changelog is publicly available, limiting traceability of algorithm revisions or bug fixes between package versions

Evidence

• [other] Task workflow step describing the core algorithm application: "Apply the Identity (EI Normal) algorithm to compute similarity scores between the query spectrum and each library entry, normalizing peak intensities and matching m/z values according to the"
• [readme] Tool capabilities statement from README: "custom implementation of the Identity (EI Normal) algorithm; custom implementation of the Similarity (EI Simple) algorithm; reading/writing msp files"
• [intro] Article finding on mssearchr purpose and scope: "The mssearchr package provides tools for conducting library searches against electron ionization mass spectral databases"