Ms Ms Spectrum Prediction

MS/MS Spectrum Prediction

Summary

Use deep learning (FIDDLE v2.0.0 with Siamese-architecture rescore model) to predict molecular formulas from tandem mass spectra (MS/MS), producing ranked formula candidates with confidence scores. This skill is essential when you need to identify unknown compounds from high-resolution MS/MS data without prior structure knowledge.

When to use

You have MS/MS spectra (in MGF format) with required metadata fields (TITLE, PRECURSOR_MZ, PRECURSOR_TYPE, COLLISION_ENERGY) and need to predict candidate molecular formulas ranked by confidence. Apply this skill when working with Orbitrap or Q-TOF instruments and when integration with external tools (BUDDY, SIRIUS) is optional but beneficial for refining candidates.

When NOT to use

• Input spectra lack required MGF metadata fields (PRECURSOR_MZ, PRECURSOR_TYPE, COLLISION_ENERGY) — preprocessing to standardize headers is needed first.
• MS/MS data are from instruments not covered by pre-trained models (only Orbitrap and Q-TOF supported); retraining on instrument-specific data is required.
• You have already-identified compounds and only need library matching or validation — use spectral library search instead of de novo prediction.

Inputs

• MGF file with MS/MS spectra (required fields: TITLE, PRECURSOR_MZ, PRECURSOR_TYPE, COLLISION_ENERGY)
• Pre-trained FIDDLE model checkpoints (TCN and rescore, instrument-specific)
• Configuration YAML file (instrument and model architecture specifications)
• Optional: BUDDY output CSV or SIRIUS formula results for candidate refinement

Outputs

• CSV file with one row per spectrum, including columns: ID, Mass, Pred Formula, Pred Mass, Pred Atom Num, Pred H/C Num, Refined Formula (0..4), Refined Mass (0..4), Rescore (0..4)
• Ranked molecular formula candidates with confidence scores
• Neutral mass and predicted atom/H-C counts per spectrum

How to apply

Load the MS/MS spectra via MGF input file format and select the appropriate instrument-specific pre-trained checkpoint (Orbitrap or Q-TOF). Execute the FIDDLE TCN formula-prediction model followed by the Siamese-architecture rescore model (v2.0.0) to generate initial predictions and confidence-ranked refinements. The rescore model re-ranks candidates using learned relationships between spectra and formula properties, producing standardized Rescore (k) output columns for top-5 candidates. Export results to CSV with columns including ID, predicted formula, mass, atom count, H/C count, and ranked refined formulas with associated confidence scores. Validate by checking that output columns are properly labeled, rescore values fall in valid confidence ranges [0–1], and formula masses match theoretical predictions within instrument-specific ppm tolerance.

Related tools

• FIDDLE (Deep learning framework for predicting molecular formulas from MS/MS spectra; contains research codebase for model training, evaluation, and inference) — https://github.com/JosieHong/FIDDLE
• msfiddle (CLI and Python API wrapper for FIDDLE; handles model download, prediction batching, and output CSV formatting) — https://github.com/josiehong/msfiddle
• BUDDY (Optional companion tool for generating candidate formulas; results can be integrated with FIDDLE predictions to refine ranking)
• SIRIUS (Optional companion tool for formula identification; outputs can be combined with FIDDLE rescore model to re-rank candidates)

Examples

python run_fiddle.py --test_data ./demo/input_msms.mgf --config_path ./config/fiddle_tcn_orbitrap.yml --resume_path ./check_point/fiddle_tcn_orbitrap.pt --rescore_resume_path ./check_point/fiddle_rescore_orbitrap.pt --result_path ./demo/output_fiddle.csv --device 0

Evaluation signals

• Output CSV contains all required columns (ID, Pred Formula, Rescore (0..4)) with no missing or NaN values for valid spectra.
• Rescore (k) confidence values are numeric, in range [0, 1], and ranked in descending order for each spectrum (top-1 score ≥ top-2 ≥ ... ≥ top-5).
• Predicted formula masses match theoretical masses within instrument tolerance (typically ±5 ppm for Orbitrap, ±10 ppm for Q-TOF); validate using Pred Mass vs. theoretical neutral mass.
• Refined formulas (0..4) are chemically valid (positive atom counts, obey valence rules); cross-check against Hill system notation or molecular weight ranges.
• When BUDDY or SIRIUS candidates are provided, verify that FIDDLE's top-1 rescore candidate is among the input candidates (indicating successful re-ranking) or check Spearman correlation of FIDDLE rescore ranks vs. input tool ranks to confirm integration.

Limitations

• Model performance depends on instrument type and collision energy; predictions are optimized for Orbitrap and Q-TOF with standard CID/HCD. Unknown or non-standard collision energies may degrade accuracy.
• Siamese rescore architecture in v2.0.0 is a breaking change; model checkpoints from FIDDLE v1.x are not compatible; v2.0.0 checkpoint assets must be explicitly downloaded.
• MGF input requires complete metadata (PRECURSOR_TYPE, COLLISION_ENERGY); missing fields cause parsing errors or silent skipping depending on workflow.
• Top-k predictions (default k=5) are heuristic refinements; true formula may rank lower if spectrum is noisy, chimeric, or from an out-of-distribution sample pool.
• External tool integration (BUDDY, SIRIUS) expects native/original output formats; deprecated msfiddle-normalized CSV formats are no longer supported and emit DeprecationWarning.

Evidence

• [readme] FIDDLE is a deep learning method for predicting molecular formulas from MS/MS spectra: "FIDDLE is a deep learning method for predicting molecular formulas from MS/MS spectra. This repository contains the full research codebase for model training, evaluation, and paper reproduction."
• [readme] Siamese architecture redesign in v2.0.0 for rescore model: "Breaking change (v2.0.0): The rescore model has been redesigned (Siamese architecture), see details in CHANGELOG.md"
• [readme] Required MGF fields for input: "The required MGF fields are TITLE, PRECURSOR_MZ, PRECURSOR_TYPE, and COLLISION_ENERGY"
• [readme] Output CSV columns including Rescore (k) scores: "Rescore (0..4): Confidence scores for the default top-5 refined candidates."
• [readme] Workflow steps for running FIDDLE on caffeine test spectrum: "See test_caffeine.py for a worked example running FIDDLE on a caffeine Orbitrap spectrum fetched live from GNPS."
• [readme] Integration with BUDDY and SIRIUS for candidate refinement: "If you'd like to integrate the results from SIRIUS and BUDDY, please organize the results in the format shown in ./demo/buddy_output.csv and ./demo/sirius_output.csv, and provide them to run FIDDLE"
• [readme] Instrument-specific model checkpoints: "Orbitrap models: fiddle_tcn_orbitrap.pt: formula prediction model on Orbitrap spectra; fiddle_rescore_orbitrap.pt: rescore model on Orbitrap spectra. Q-TOF models: fiddle_tcn_qtof.pt: formula"