# Ms Ms Spectrum Prediction

> Use when 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.

- Skill: `holobiomicslab/ms-ms-spectrum-prediction` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/ms-ms-spectrum-prediction`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/ms-ms-spectrum-prediction/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/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"