Mass spectrum query processing

mass-spectrum-query-processing

Summary

Query mass spectral libraries using entropy-based similarity scoring via the Flash Entropy Search algorithm, which accelerates real-time matching of unknown spectra against large library collections. This skill enables rapid compound identification by computing entropy similarity scores between a query spectrum and indexed library entries.

When to use

Apply this skill when you have an unknown mass spectrum (as m/z and intensity arrays) and need to identify candidate compounds by matching against a mass spectral library. Use it specifically when you require rapid, real-time similarity ranking across multiple spectral libraries without pre-filtering by precursor m/z alone, or when dot product similarity has insufficient discriminative power for your compound identification task.

When NOT to use

• Your query spectra are already confidently assigned to compounds via orthogonal methods (e.g., retention time, reference standards); use this skill for de novo or confirmatory identification, not post-hoc validation.
• Your spectral library is very small (<100 spectra) or your turnaround-time budget does not constrain classical dot product similarity; classical methods may suffice and avoid added dependencies.
• Your library spectra lack consistent precursor_mz annotation or contain predominantly low-quality (low S/N) fragments; Flash Entropy Search assumes well-formed library data.

Inputs

• Query spectrum object with precursor_mz (float) and peaks (2D array of [m/z, intensity] pairs)
• Spectral library (list of dictionaries with required keys: precursor_mz, peaks; optional: id, metadata)
• Precursor m/z tolerance or mass range (implicit in indexing step)

Outputs

• Ranked list of library spectrum matches with entropy similarity scores
• Similarity score arrays for hybrid_search, identity_search, neutral_loss_search, and open_search modes
• Library spectrum identifiers and metadata associated with top-ranked matches

How to apply

First, format your query spectrum with precursor_mz and peaks (as [m/z, intensity] pairs) and load or build an index from library spectra using the FlashEntropySearch class in MSEntropy. Call the search() method with your query precursor_mz and peaks to compute entropy-based similarity scores across all indexed library spectra. The algorithm returns similarity scores for hybrid_search, identity_search, neutral_loss_search, and open_search modes—rank results by the relevant similarity metric in descending order. Select the hybrid_search or open_search score for general-purpose identification; use identity_search for exact mass matching or neutral_loss_search for fragmentation pathway analysis. Validate matches by examining the ranked library spectrum identifiers and metadata returned.

Related tools

• MSEntropy (Python package implementing Flash Entropy Search algorithm and spectral entropy calculation for library querying) — https://github.com/YuanyueLi/MSEntropy
• EntropySearch (Standalone GUI application for searching spectral files (.mgf, .msp, .mzML, .lbm2) against spectral libraries using entropy similarity) — https://github.com/YuanyueLi/EntropySearch
• FlashEntropySearch (Repository containing original algorithm source code, benchmark data, and implementation reference for the Flash Entropy Search manuscript) — https://github.com/YuanyueLi/FlashEntropySearch

Examples

from ms_entropy import FlashEntropySearch
import numpy as np
entropy_search = FlashEntropySearch()
spectral_library = entropy_search.build_index([{"id": "lib_1", "precursor_mz": 150.0, "peaks": [[100.0, 1.0], [101.0, 1.0]]}, {"id": "lib_2", "precursor_mz": 200.0, "peaks": np.array([[100.0, 1.0], [102.0, 1.0]], dtype=np.float32)}])
similarity = entropy_search.search(precursor_mz=150.0, peaks=np.array([[100.0, 1.0], [101.0, 1.0], [102.0, 1.0]], dtype=np.float32))

Evaluation signals

• Returned entropy similarity scores fall within the valid range [0, 1] for all four search modes (hybrid, identity, neutral_loss, open).
• Top-ranked library matches have higher entropy similarity scores than lower-ranked entries; score ranks are monotonically ordered.
• Query spectrum precursor_mz is within tolerance of matched library spectra precursor_mz (tolerance depends on instrument calibration; typically <0.01 Da for high-resolution MS).
• Returned library spectrum identifiers and metadata correspond to valid entries in the indexed spectral library (no orphaned or corrupted references).
• Computational runtime for a single query on a large library (>100,000 spectra) completes in seconds, demonstrating algorithmic acceleration vs. classical similarity computation.

Limitations

• The algorithm requires spectra to be formatted consistently with precursor_mz and peaks keys; malformed or missing precursor_mz values will cause indexing or search failures.
• Entropy similarity assumes sufficient spectral complexity; low-mass or low-intensity query spectra with few significant peaks may produce ambiguous or low-confidence matches.
• No changelog is available in the FlashEntropySearch repository, limiting visibility into version-to-version algorithmic or API changes.
• The Flash Entropy Search algorithm is currently implemented in Python only; C/C++, R, and JavaScript implementations of classical entropy/entropy similarity are available, but real-time library search acceleration is Python-exclusive.

Evidence

• [intro] Algorithm accelerates entropy similarity computation for library querying: "Flash entropy search to query all mass spectral libraries in real time"
• [intro] Entropy similarity outperforms dot product for compound identification: "Entropy similarity, which measured spectral similarity based on spectral entropy, has been shown to outperform dot product similarity in compound identification"
• [readme] Query workflow: load query spectrum, build index from library, search and rank results: "Step 1: Build the index from the library spectra entropy_search.build_index(spectral_library)

Step 2: Search the library

entropy_similarity = entropy_search.search( precursor_mz ="

• [readme] Output structure includes four similarity score modes: "{'hybrid_search': array([0.6666666 , 0.99999994, 0.99999994, 0.99999994], dtype=float32), 'identity_search': array([0.6666667, 0. , 0. , 0. ], dtype=float32),"
• [readme] Library spectrum input format and required keys: "Note that the precursor_mz and peaks keys are required, the reset of the keys are optional"
• [readme] GUI supports standard spectral file formats: "To search one spectral file against another spectral file or a spectral library, use the Entropy Search GUI. The GUI supports .mgf, .msp, .mzML, and .lbm2 file formats"