Precursor m z based filtering

precursor-m-z-based-filtering

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

Summary

Filter and match MS/MS spectra by precursor mass-to-charge ratio (m/z) to reduce the search space during spectral library lookup and improve annotation specificity. This skill is essential when matching unknown query spectra against large spectral libraries or databases where exact precursor m/z alignment is a prerequisite for confident compound identification.

When to use

Apply this skill when you have an unknown MS/MS query spectrum with a known or measured precursor m/z value and need to search a spectral library (local or public: GNPS, MASSBANK, DrugBANK) to annotate the compound. Use precursor m/z filtering as a gating criterion before computing spectral similarity scores, especially when library size is large or when false-positive annotation risk is high due to similar fragmentation patterns across unrelated compounds.

When NOT to use

• Precursor m/z is unknown or unavailable from the query spectrum (e.g., for MS1 survey scans without MS/MS fragmentation data).
• You are performing analog or related-compound searches where metabolic derivatives or adducts with different precursor m/z are expected and desirable matches.
• Input is already a pre-filtered, low-complexity spectral subset (e.g., a single-compound reference standard) where m/z-based gating adds no discriminative value.

Inputs

• query MS/MS spectrum (two-column matrix: m/z and intensity pairs)
• precursor m/z value (float, e.g., 369.232)
• spectral library (GNPS-style RData object, local mzML/mzXML, or public database reference)
• m/z tolerance window (numeric, default in MergeION is implicit)

Outputs

• filtered candidate spectra list (subset of library matching precursor m/z ± tolerance)
• ranked match results with cosine similarity scores (or spectral dot-product)
• annotated hits with compound metadata (name, molecular formula, INCHI, accession ID)

How to apply

Extract the precursor m/z value from your query spectrum (e.g., 369.232 for Cinnarizine in the MergeION quick-start example). Set the parameter use_prec = TRUE to enforce precursor mass matching. Define an appropriate m/z tolerance window (MergeION default behavior applies this internally during library_query). The algorithm will pre-filter library candidate spectra to retain only those whose precursor m/z falls within the tolerance window of your query precursor m/z before computing cosine similarity or other spectral dot-product metrics. This step dramatically reduces computational cost and noise by eliminating chemically implausible matches. Rank filtered matches by similarity score and apply a minimum similarity threshold (e.g., min_score = 0.7) to identify high-confidence annotations.

Related tools

• MergeION2 (implements library_query() function with use_prec parameter to enforce precursor m/z filtering during spectral library search) — https://github.com/daniellyz/MergeION2
• GNPS (public spectral library source for precursor m/z-based matching)
• MASSBANK (public spectral library source for precursor m/z-based matching)
• DrugBANK (public spectral library source for precursor m/z-based matching of drug compounds)

Examples

params.query.sp = list(prec_mz = 369.232, use_prec = T, polarity = "Positive", method = "Cosine", min_frag_match = 6, min_score = 0); search_result = library_query(input_library = library1c, query_spectrum = query.sp, params.query.sp = params.query.sp)

Evaluation signals

• Verify that all returned candidates have precursor m/z within the specified tolerance window of the query precursor m/z (e.g., ±0.01 Da or ±5 ppm).
• Confirm that the top-ranked match (highest cosine similarity) corresponds to the known or expected compound when validating on standards (e.g., Cinnarizine at cosine ≥ 0.95).
• Inspect the mirror plot visualization between query and matched library spectrum to confirm fragmentation pattern alignment, not just precursor m/z agreement.
• Validate that use_prec = TRUE reduces false-positive matches compared to use_prec = FALSE in benchmark datasets.
• Check that the number of filtered candidates is substantially smaller than the full library size, confirming that precursor m/z filtering successfully reduced search space.

Limitations

• Precursor m/z filtering may fail or produce no hits if the query precursor m/z is miscalibrated, contains systematic instrument error, or is not present in the target library database.
• ESI-MS/MS spectra in MergeION's pre-compiled library are currently limited to positive ion mode only; negative ion mode queries will not match.
• The method assumes precursor m/z precision and stability; highly variable precursor m/z (e.g., due to poor mass calibration in low-resolution instruments) may yield false negatives if tolerance is set too tight.
• Precursor m/z alone cannot distinguish isobars (e.g., isomeric compounds with identical precursor mass); spectral similarity scoring is necessary as a second-stage filter.

Evidence

• [readme] Parameters to check: prec_mz (precursor mass) and use_prec (forces precursor mass match): "Only important parameters to check are the prec_mz, which indicates the precursor mass, and use_prec, which forces precursor mass match in the search output by setting to TRUE"
• [intro] Library search algorithms compute similarity between query and library spectra: "Apply library search algorithm to compute similarity scores (e.g., cosine similarity or spectral dot-product) between query spectrum and candidate library spectra"
• [readme] Precursor m/z is a required input for spectral library lookup: "query.sp = read.csv(...); params.query.sp = list(prec_mz = 369.232, use_prec = T, ...)"
• [intro] Ranking and filtering matched spectra by similarity threshold: "Rank and filter matched spectra by similarity threshold to identify best-matching library entries"
• [readme] High-confidence match example with cosine similarity score: "the Cosine spectral similarity is very high at 0.95"