Ms2 dereplication

MS2 spectral database dereplication

Summary

Identifies and ranks matching spectra from MS2 .mzML input files against reference spectral libraries using the Spectra R package, producing a ranked table of spectral matches with similarity scores and metadata. This is the first step in untargeted metabolomics annotation that filters noise and establishes spectral identity before compound structure prediction.

When to use

You have MS2 tandem mass spectrometry data in .mzML format and need to match unknown spectra against a reference library (GNPS, HMDB, MassBank) to identify which known compounds are present in your sample. Apply this skill when spectral similarity matching is a prerequisite for downstream compound annotation or when you want to prioritize high-confidence spectral hits before more computationally expensive structure prediction steps.

When NOT to use

• Input data is already in a format other than .mzML (e.g., .raw, .d, or pre-processed feature tables); use format conversion tools first.
• You have no reference spectral library available or your target compounds are novel/not present in public databases; in this case skip to in silico structure prediction.
• Your goal is qualitative presence/absence only and you do not need ranked similarity scores or metadata enrichment; simpler spectral matching approaches may suffice.

Inputs

• MS2 .mzML format data files (mass spectrometry data with fragmentation spectra)
• Reference spectral library objects in R format (e.g., gnps.rda, hmdb.rda, mbankNIST.rda)
• Precursor mass tolerance parameter (ppm, e.g., 15 ppm)

Outputs

• Spectral match results CSV file (e.g., spectral_results.csv) with columns: matched spectrum ID, reference library ID, similarity score, collision energy, and other metadata
• Per-spectrum matched candidate list ranked by similarity score
• Directory structure with per-library subdirectories (GNPS, HMDB, MassBank) containing detailed match information

How to apply

Load MS2 .mzML format data files into R using the Spectra package. Execute spectral database dereplication against reference spectral libraries (GNPS, HMDB, MassBank) using Spectra's matching functions with a precursor mass tolerance (typically 15 ppm as used in MAW). For each query spectrum, rank candidate matches by cosine similarity or other spectral similarity metrics. Generate and export a table of spectral matches with match scores, database identifiers, collision energy metadata, and supporting information. The matched spectra serve as input for subsequent compound database dereplication via SIRIUS or MetFrag.

Related tools

• Spectra (Performs spectral database matching and dereplication against reference libraries; core tool that loads .mzML files and ranks spectral similarity) — https://rformassspectrometry.github.io/Spectra/
• R (Runtime environment in which Spectra is executed and spectral matching workflow is orchestrated)
• GNPS (Reference spectral library database (pre-loaded as gnps.rda R object) against which query spectra are matched)
• HMDB (Reference spectral library database (pre-loaded as hmdb.rda R object) used for spectral matching)
• MassBank (Reference spectral library database (pre-loaded as mbankNIST.rda R object) used for spectral matching)

Examples

Rscript --no-save --no-restore --verbose Workflow_R_Script_all_MetFrag.r sample.mzML gnps.rda hmdb.rda mbankNIST.rda 15 TRUE

Evaluation signals

• Output CSV file has expected columns: reference library identifier, query spectrum ID, similarity/match score, and collision energy metadata; file is not empty and contains ≥1 matched spectrum per precursor mass queried.
• Spectral match scores (e.g., cosine similarity) fall within expected range (0–1 or 0–100%) and are sorted in descending order within each spectrum group.
• Each query spectrum has ≥1 matched candidate from at least one reference library; check that precursor mass tolerance (15 ppm) was correctly applied by verifying matched mass differences are within tolerance.
• Output directory structure mirrors reference library organization (GNPS/, HMDB/, MassBank/ subdirectories populated); verify no empty directories or missing metadata columns.
• Downstream compound database dereplication (SIRIUS/MetFrag) successfully accepts the spectral match output file as input without schema errors.

Limitations

• Matching quality depends on reference library coverage and spectral similarity threshold; novel or poorly ionized compounds may not be matched despite being present.
• Spectral noise, variable collision energies, and instrument differences can reduce matching sensitivity; recommend quality filtering of input spectra (signal-to-noise ratio, peak counts) before dereplication.
• The workflow uses pre-computed, static database snapshots (e.g., GNPS saved 2023-01-09, HMDB v5.0, MassBank 2022.12); updates to public databases require re-downloading and re-running the workflow.
• CWL version of MAW supports MetFrag downstream but SIRIUS integration is only available in Docker containers; this constrains deployment flexibility if you require SIRIUS.
• Large .mzML files (>10 precursor masses) may require HPC resources and SLURM batch submission; single-machine execution on large files is slow (≈2 minutes per precursor mass on 64 GB Ubuntu system).

Evidence

• [intro] performs spectral database dereplication using R Package Spectra and compound database dereplication using SIRIUS OR MetFrag: "performs spectral database dereplication using R Package Spectra and compound database dereplication using SIRIUS OR MetFrag"
• [other] workflow takes MS2 .mzML format data files as input in R and performs spectral database dereplication using the Spectra R package: "The workflow takes MS2 .mzML format data files as input in R and performs spectral database dereplication using the Spectra R package."
• [other] Execute spectral database dereplication against a reference spectral library using Spectra to identify and rank matching spectra: "Execute spectral database dereplication against a reference spectral library using Spectra to identify and rank matching spectra."
• [readme] 15 = ppm for spectral database dereplication precursor matches: "15 = ppm for spectral database dereplication precursor matches"
• [readme] with CWL, only MetFrag version of MAW is available at the moment: "with CWL, only MetFrag version of MAW is available at the moment"
• [readme] one precursor mass takes 2 minutes on an Ubuntu system with 64GB RAM to run Workflow_R_Script_all_MetFrag.r: "one precursor mass takes 2 minutes on an Ubuntu system with 64GB RAM to run Workflow_R_Script_all_MetFrag.r"