spectral-library-matching-annotation
Summary
Match experimental MS2 spectra against reference spectral libraries and retrieve compound annotations with confidence scores using deep learning-based candidate ranking. This skill is essential for identifying unknown organic pollutants in nontargeted mass spectrometry workflows where reference spectra are available in GNPS or similar databases.
When to use
Apply this skill when you have MS2 spectral data (precursor m/z, retention time, and fragment ion patterns) from UPLC-HRMS analysis of environmental or biological samples and need to assign compound identities by comparing against known reference spectra. Use it after peak detection and MS2 acquisition but before reporting final compound identifications, particularly when analyzing complex mixtures like pesticides, pollutants, or metabolites where multiple candidate structures may match a single precursor mass.
When NOT to use
- If raw UPLC-HRMS data has not yet been converted to mzML or batch-processed format — MSThunder requires pre-processed ion chromatograms and does not currently support offline raw data ingestion.
- If no reference spectral library or candidate formula is available — the matching step requires either a known molecular formula to predict structures or pre-existing reference spectra in GNPS/online databases.
- If the sample was acquired on a vendor instrument (ThermoFisher, Agilent) without prior conversion via MSConvert — MSThunder is compatible only with converted formats.
Inputs
- Batch-processed MS2 spectral data files (precursor m/z, retention time, fragment ion m/z and intensities)
- Candidate molecular formula (either system-predicted or user-specified)
- Reference spectral library (GNPS or equivalent database)
- MS1 spectrum at the target retention time
Outputs
- Ranked list of candidate structures (top 10) with confidence scores
- MS2-candidate spectrum matching result (if reference spectrum found in top 10)
- Compound name, SMILES notation, and molecular structure diagram
- Spectral library annotation metadata
How to apply
Load batch-processed MS2 data into the MSThunder interface specifying precursor m/z and retention time. For each precursor, the system retrieves candidate molecular formulas and executes structure prediction against the deep learning model trained on spectral library data. The workflow ranks candidate structures by a learned similarity score and returns the top 10 matches; if a reference spectrum is found among these candidates, the spectrum matching result (cosine similarity or equivalent metric) is displayed. Verify results by inspecting whether matched reference spectra show reasonable MS2 fragment patterns (neutral losses, base peaks) consistent with the proposed chemical structure, and cross-check high-confidence matches (top rank with reference spectrum hit) against chemical plausibility for the sample matrix.
Related tools
- MSThunder (Deep learning-based interface for spectral matching, structure prediction, and candidate ranking; executes MS2-to-reference spectrum matching and returns top-ranked compounds with confidence scores.) — https://github.com/LQZ0123/MSThunder
- GNPS (Online spectral library and reference database used to populate candidate structures and reference spectra for matching.)
- MSConvert (Converts vendor raw data (ThermoFisher, Agilent) to standardized format compatible with MSThunder preprocessing pipeline.)
Evaluation signals
- Top-ranked candidate structure appears in the top 10 matches and displays a reference spectrum match in the MS2-candidate panel.
- MS2 fragment pattern of the matched reference spectrum shows logical neutral losses and base peak assignments consistent with the proposed molecular structure (e.g., loss of water or CO₂ for polar compounds).
- Candidate ranking score is reproducible across multiple runs on the same precursor m/z and retention time; scores do not depend on UI rendering artifacts.
- Matched compound names are chemical plausible for the sample matrix (e.g., pesticide names for environmental water samples) and match entries in public chemical databases (PubChem).
- If a user replaces the system-predicted molecular formula with a corrected formula and re-runs prediction (double-click → enter formula → double-click Ranking), the new set of candidates re-ranks correctly without crashing.
Limitations
- Current version does not support offline processing of raw data; users must send raw UPLC-HRMS files to the development team ([redacted-email]) or upload to Zenodo/GNPS for centralized preprocessing and subsequent MSThunder analysis.
- Online processing capability for raw UPLC-HRMS data is under development and not yet available; currently requires manual file transfer and Linux-based conversion step.
- Matching accuracy depends on the completeness and quality of the reference spectral library; compounds absent from GNPS or other indexed databases cannot be identified even if precursor mass is correct.
- System requires Windows environment with 16 GB RAM and 2 GB NVIDIA GPU; performance on lower-spec hardware or alternative operating systems has not been validated.
- If candidate structure images fail to render in the GUI, users may need to lower the display resolution setting to view MS2-candidate spectra and structure diagrams.
Evidence
- [readme] MSThunder provide a deep learning-based nontargeted analytical framework for the accurate and rapid identification of unknown organic pollutants in water: "MSThunder provide a deep learning-based nontargeted analytical framework for the accurate and rapid identification of unknown organic pollutants in water."
- [readme] If a reference spectrum is found among the top 10 candidates, the spectrum matching result will be shown in MS2-candidate: "If a reference spectrum is found among the top 10 candidates, the spectrum matching result will be shown in MS2-candidate."
- [readme] Double-click the precursor formula to execute the structure prediction function for that molecular formula; the candidate score information will be displayed in Ranking: "Double-click the precursor formula to execute the structure prediction function for that molecular formula; the candidate score information will be displayed in Ranking."
- [readme] The current version is compatible with ThermoFisher, Agilent, and other vendors whose raw data can be converted via MSConvert: "The current version is compatible with ThermoFisher, Agilent, and other vendors whose raw data can be converted via MSConvert."
- [readme] Due to environment configuration issues, the current version does not yet support offline processing of raw data: "Due to environment configuration issues, the current version does not yet support offline processing of raw data."
1---2name: spectral-library-matching-annotation3description: Use when you have MS2 spectral data (precursor m/z, retention time, and fragment ion patterns) from UPLC-HRMS analysis of environmental or biological samples and need to assign compound identities by comparing against known reference spectra.4license: CC-BY-4.05---67# spectral-library-matching-annotation89## Summary1011Match experimental MS2 spectra against reference spectral libraries and retrieve compound annotations with confidence scores using deep learning-based candidate ranking. This skill is essential for identifying unknown organic pollutants in nontargeted mass spectrometry workflows where reference spectra are available in GNPS or similar databases.1213## When to use1415Apply this skill when you have MS2 spectral data (precursor m/z, retention time, and fragment ion patterns) from UPLC-HRMS analysis of environmental or biological samples and need to assign compound identities by comparing against known reference spectra. Use it after peak detection and MS2 acquisition but before reporting final compound identifications, particularly when analyzing complex mixtures like pesticides, pollutants, or metabolites where multiple candidate structures may match a single precursor mass.1617## When NOT to use1819- If raw UPLC-HRMS data has not yet been converted to mzML or batch-processed format — MSThunder requires pre-processed ion chromatograms and does not currently support offline raw data ingestion.20- If no reference spectral library or candidate formula is available — the matching step requires either a known molecular formula to predict structures or pre-existing reference spectra in GNPS/online databases.21- If the sample was acquired on a vendor instrument (ThermoFisher, Agilent) without prior conversion via MSConvert — MSThunder is compatible only with converted formats.2223## Inputs2425- Batch-processed MS2 spectral data files (precursor m/z, retention time, fragment ion m/z and intensities)26- Candidate molecular formula (either system-predicted or user-specified)27- Reference spectral library (GNPS or equivalent database)28- MS1 spectrum at the target retention time2930## Outputs3132- Ranked list of candidate structures (top 10) with confidence scores33- MS2-candidate spectrum matching result (if reference spectrum found in top 10)34- Compound name, SMILES notation, and molecular structure diagram35- Spectral library annotation metadata3637## How to apply3839Load batch-processed MS2 data into the MSThunder interface specifying precursor m/z and retention time. For each precursor, the system retrieves candidate molecular formulas and executes structure prediction against the deep learning model trained on spectral library data. The workflow ranks candidate structures by a learned similarity score and returns the top 10 matches; if a reference spectrum is found among these candidates, the spectrum matching result (cosine similarity or equivalent metric) is displayed. Verify results by inspecting whether matched reference spectra show reasonable MS2 fragment patterns (neutral losses, base peaks) consistent with the proposed chemical structure, and cross-check high-confidence matches (top rank with reference spectrum hit) against chemical plausibility for the sample matrix.4041## Related tools4243- **MSThunder** (Deep learning-based interface for spectral matching, structure prediction, and candidate ranking; executes MS2-to-reference spectrum matching and returns top-ranked compounds with confidence scores.) — https://github.com/LQZ0123/MSThunder44- **GNPS** (Online spectral library and reference database used to populate candidate structures and reference spectra for matching.)45- **MSConvert** (Converts vendor raw data (ThermoFisher, Agilent) to standardized format compatible with MSThunder preprocessing pipeline.)4647## Evaluation signals4849- Top-ranked candidate structure appears in the top 10 matches and displays a reference spectrum match in the MS2-candidate panel.50- MS2 fragment pattern of the matched reference spectrum shows logical neutral losses and base peak assignments consistent with the proposed molecular structure (e.g., loss of water or CO₂ for polar compounds).51- Candidate ranking score is reproducible across multiple runs on the same precursor m/z and retention time; scores do not depend on UI rendering artifacts.52- Matched compound names are chemical plausible for the sample matrix (e.g., pesticide names for environmental water samples) and match entries in public chemical databases (PubChem).53- If a user replaces the system-predicted molecular formula with a corrected formula and re-runs prediction (double-click → enter formula → double-click Ranking), the new set of candidates re-ranks correctly without crashing.5455## Limitations5657- Current version does not support offline processing of raw data; users must send raw UPLC-HRMS files to the development team ([redacted-email]) or upload to Zenodo/GNPS for centralized preprocessing and subsequent MSThunder analysis.58- Online processing capability for raw UPLC-HRMS data is under development and not yet available; currently requires manual file transfer and Linux-based conversion step.59- Matching accuracy depends on the completeness and quality of the reference spectral library; compounds absent from GNPS or other indexed databases cannot be identified even if precursor mass is correct.60- System requires Windows environment with 16 GB RAM and 2 GB NVIDIA GPU; performance on lower-spec hardware or alternative operating systems has not been validated.61- If candidate structure images fail to render in the GUI, users may need to lower the display resolution setting to view MS2-candidate spectra and structure diagrams.6263## Evidence6465- [readme] MSThunder provide a deep learning-based nontargeted analytical framework for the accurate and rapid identification of unknown organic pollutants in water: "MSThunder provide a deep learning-based nontargeted analytical framework for the accurate and rapid identification of unknown organic pollutants in water."66- [readme] If a reference spectrum is found among the top 10 candidates, the spectrum matching result will be shown in MS2-candidate: "If a reference spectrum is found among the top 10 candidates, the spectrum matching result will be shown in MS2-candidate."67- [readme] Double-click the precursor formula to execute the structure prediction function for that molecular formula; the candidate score information will be displayed in Ranking: "Double-click the precursor formula to execute the structure prediction function for that molecular formula; the candidate score information will be displayed in Ranking."68- [readme] The current version is compatible with ThermoFisher, Agilent, and other vendors whose raw data can be converted via MSConvert: "The current version is compatible with ThermoFisher, Agilent, and other vendors whose raw data can be converted via MSConvert."69- [readme] Due to environment configuration issues, the current version does not yet support offline processing of raw data: "Due to environment configuration issues, the current version does not yet support offline processing of raw data."
HolobiomicsLab 