Exact Mass Database Matching

exact-mass-database-matching

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

Summary

Match detected metabolite features to xenobiotic reaction databases by computing exact monoisotopic mass and comparing against reference metabolite masses. This skill enables high-throughput annotation of reaction-derived metabolites in untargeted MS data by reducing candidate space through mass accuracy.

When to use

After feature detection and alignment on raw MS data, when you have a list of unknown feature m/z values and need to assign them to known xenobiotic metabolites or their predicted biotransformation products. Apply this skill when mass spectrometry accuracy is sufficient (typically <5 ppm for high-resolution instruments) and you have access to a curated xenobiotic reaction database (e.g., one derived from Biotransformer predictions).

When NOT to use

• Input is already a fully annotated metabolite table with confirmed identities — skip to pathway analysis.
• Mass spectrometer accuracy is poor (>10 ppm or unit-resolution only) and no orthogonal confirmation method (MS/MS, RT standards) is available.
• Xenobiotic database is unavailable or does not cover the metabolites of interest (e.g., studying endogenous lipids instead of drug metabolites).

Inputs

• aligned feature table with m/z values and retention time
• raw MS/MS fragmentation spectra (NetCDF or mzML format)
• xenobiotic reaction database or biotransformation predictions from Biotransformer
• chemical formula reference table or structure library

Outputs

• annotated feature table with matched metabolite identities
• reaction pathway assignments and biotransformation metadata
• mass match quality scores (e.g., ppm error, entropy, similarity rank)

How to apply

Calculate exact monoisotopic mass for each detected feature using OrgMassSpecR, which computes theoretical m/z from chemical formulas or from empirical peak m/z. Compare each feature mass against the xenobiotic reaction database with a mass tolerance appropriate to your instrument accuracy (the CMDN pipeline is compatible with MSDial ver. 4.80 for feature input). Use CluMSID's cluster-based annotation propagation to assign metabolite identities to features that fall within the mass tolerance window. Validate matches by cross-referencing with fragmentation pattern similarity (via MSMSsim) and spectral entropy (via msentropy) to increase confidence in annotations before export. The workflow assumes features are pre-aligned and represent distinct metabolic entities.

Related tools

• OrgMassSpecR (Calculates exact monoisotopic mass and performs database mass matching for annotated features)
• CluMSID (Clusters features and propagates metabolite annotations across aligned features with similar mass and fragmentation patterns)
• MSMSsim (Computes fragmentation pattern similarity scores between unknown features and reference spectra to validate mass-based matches)
• msentropy (Calculates spectral entropy to assess fragment complexity and confidence in match assignments)
• MSDial (Performs feature detection and alignment prior to exact mass matching; compatible version 4.80)
• Biotransformer (Generates predicted xenobiotic biotransformation products and reaction database for mass matching reference)

Evaluation signals

• Mass error between observed and annotated feature m/z is within instrument accuracy (typically <5 ppm for high-resolution MS).
• Annotated features show coherent cluster assignments with similar fragmentation patterns (MSMSsim score and spectral entropy consistent across matched features).
• Reaction pathway metadata assigned to features is chemically plausible (e.g., Phase I oxidation, Phase II conjugation) and traceable to Biotransformer or literature predictions.
• Manual inspection of top-ranked matches confirms that highest-scoring annotations correspond to expected metabolites of known xenobiotics in the experiment.
• Proportion of annotated features is consistent with expected xenobiotic metabolism complexity (typically 5–20 metabolites per parent compound in controlled studies).

Limitations

• Exact mass matching alone cannot distinguish isomers or isobars with identical m/z; MS/MS fragmentation pattern similarity is required for disambiguation.
• Annotation accuracy depends on database completeness; if predicted metabolites from Biotransformer are absent or incorrect, matches will fail or be spurious.
• Mass tolerance is critical and instrument-dependent; poorly calibrated instruments or drifting mass accuracy will increase false negatives and false positives.
• The CMDN pipeline requires ten R packages; compatibility issues or version mismatches can prevent reproducible execution across computing environments.

Evidence

• [other] Annotate metabolites by matching aligned features to xenobiotic reaction databases using OrgMassSpecR for exact mass calculation and CluMSID for cluster-based annotation propagation.: "Annotate metabolites by matching aligned features to xenobiotic reaction databases using OrgMassSpecR for exact mass calculation and CluMSID for cluster-based annotation propagation"
• [other] CMDN pipeline requires installation of ten R packages and is compatible with MSDial (ver. 4.80) and Biotransformer 3.0.: "The CMDN pipeline requires installation of ten R packages (tidyverse, CluMSID, CluMSIDdata, grid, OrgMassSpecR, pheatmap, reshape2, MSMSsim, msentropy, readxl) and is compatible with MSDial (ver."
• [readme] CMDN is a top-down untargeted metabolomics-based MS data processing framework for high-throughput and automated annotation of reaction-derived xenobiotic metabolites.: "Compound metabolite discovery network (CMDN) is an "top-down" untargeted metabolomics-based MS data processing framework to enable high-throughput and automated annotation of reaction-derived"
• [other] Apply MSMSsim to compute fragmentation pattern similarity scores and msentropy to assess fragment complexity and confidence for match validation.: "Apply MSMSsim to compute fragmentation pattern similarity scores between unknown features and reference spectra. Calculate spectral entropy using msentropy to assess fragment complexity and confidence"