Spectral signal detection

spectral-signal-detection

Summary

Match predicted candidate metabolites against mass spectrometry spectral features using mass accuracy and intensity thresholds to identify which metabolites are present in mzML data. This skill detects actual chemical signals corresponding to in silico predictions.

When to use

You have mzML mass spectrometry data and a list of predicted candidate metabolites (with known mass-to-charge ratios and retention times) for a drug of interest, and you need to determine which candidates actually appear in the observed spectra rather than treating all predictions as equally likely.

When NOT to use

• Input is already a curated list of identified metabolites (detection has already been performed)
• mzML data is unprocessed and contains significant noise without prior peak-picking or baseline correction
• Predicted candidates lack chemical formula or theoretical m/z values needed for mass matching

Inputs

• mzML mass spectrometry data file (raw or peak-picked)
• TSV or configuration file containing predicted candidate metabolites with chemical formulas and theoretical m/z values
• Configuration parameters specifying mass accuracy tolerance, intensity thresholds, and retention time windows

Outputs

• Detection report (TSV format) listing matched metabolites with observed m/z, theoretical m/z, mass error, intensity, and retention time
• Feature extraction matrix (spectral features detected in the mzML data)
• Visualization-ready data for metabolite figures (via MetApp or similar)

How to apply

Load the mzML file into R and extract observed spectral features (m/z values, intensities, retention times). For each predicted candidate metabolite, calculate or retrieve its theoretical mass-to-charge ratio. Compare observed m/z values against predicted candidates using a mass accuracy threshold (typically parts-per-million tolerance) and minimum intensity thresholds to filter noise. Retain only candidates whose theoretical m/z and expected retention time (if available) align with detected features above the intensity cutoff. Generate a detection report listing matched candidates and their correspondence to observed signals, filtering out candidates that lack supporting spectral evidence.

Related tools

• MetIDfyR (R script that implements spectral-signal-detection by parsing mzML files, calculating theoretical m/z values from drug formulas, and matching predicted candidates against observed spectral features) — https://github.com/agnesbrnb/MetIDfyR
• MSnbase (R package dependency used to read and parse mzML mass spectrometry data files)
• Rdisop (R package dependency used to compute molecular mass and elemental composition from chemical formulas)
• MetApp (Shiny application for visualizing and validating detected metabolites, generating PDF reports of matched signals) — https://github.com/GIELCH/MetApp

Examples

Rscript MetIDfyR.R -i input/lgd_DIA_peak-picked.tsv -o LGD4033_results -c input/config_LGD.R

Evaluation signals

• All matched candidates have observed m/z within the specified mass accuracy tolerance (parts-per-million) of their theoretical m/z
• Matched candidates' signal intensities exceed the configured intensity threshold, filtering genuine signals from noise
• Detection report contains no candidates whose theoretical properties cannot be explained by the input chemical formulas or configuration
• When re-running with stricter mass accuracy or intensity thresholds, the number of matched candidates decreases monotonically
• Visual inspection of matched candidate spectra via MetApp shows clear peaks corresponding to reported m/z values and intensities

Limitations

• Requires peak-picked mzML data; raw, unprocessed spectra may yield false negatives due to noise and baseline drift
• Mass accuracy threshold must be tuned for the instrument's resolution; inappropriate tolerances cause false positives or missed detections
• Retention time matching is optional and depends on availability of chromatographic data in the mzML file or external standards
• Does not distinguish between isomeric candidates or confirm structural identity; matching relies on mass and intensity alone
• Performance depends on the quality and completeness of the predicted candidate list; true metabolites not in the prediction set will not be detected

Evidence

• [other] Match candidate metabolites against detected features using mass accuracy and intensity thresholds.: "Match candidate metabolites against detected features using mass accuracy and intensity thresholds."
• [other] MetIDfyR is an R script that detects metabolites in mass spectrometry data (mzML format) by operating on the raw chemical formula of the drug of interest as input.: "MetIDfyR is an R script that detects metabolites in mass spectrometry data (mzML format) by operating on the raw chemical formula of the drug of interest as input."
• [readme] predict and detect metabolites in mass spectrometry data (mzML) based on the raw formula of the drug of interest: "predict and detect metabolites in mass spectrometry data (mzML) based on the raw formula of the drug of interest"
• [other] Parse predicted candidate metabolites and their chemical properties (mass-to-charge ratios, retention times if available).: "Parse predicted candidate metabolites and their chemical properties (mass-to-charge ratios, retention times if available)."
• [other] Extract spectral features from the mzML data.: "Extract spectral features from the mzML data."