Molecular Formula Prediction From Fragmentation

---
name: molecular-formula-prediction-from-fragmentation
description: Use when you have MS/MS fragmentation spectra (from Orbitrap or Q-TOF instruments) in MGF format with known precursor m/z, adduct type, and collision energy, and you need to generate ranked molecular formula candidates.
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3632
  edam_topics:
  - http://edamontology.org/topic_0121
  - http://edamontology.org/topic_3520
  tools:
  - msfiddle
  - FIDDLE
  - BUDDY
  - SIRIUS
derived_from:
- doi: 10.1038/s41467-025-66060-9
  title: fiddle
evidence_spans:
- 'CLI and Python API: [msfiddle](https://github.com/josiehong/msfiddle)'
claims: []
provenance:
  collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v1
  assembled_by: scripts/collect_metabolomics_collection.py
  sources:
  - build: coll_fiddle
    doi: 10.1038/s41467-025-66060-9
    title: fiddle
  dedup_kept_from: coll_fiddle
schema_version: 0.2.0
---

# molecular-formula-prediction-from-fragmentation

## Summary

Use a pre-trained deep learning model (FIDDLE) to predict molecular formulas from tandem mass spectra (MS/MS), leveraging a Siamese rescore architecture to rank formula candidates by confidence score. This skill is essential when you have fragmentation spectra and need to narrow the chemical search space by eliminating implausible molecular formulas before structure elucidation.

## When to use

You have MS/MS fragmentation spectra (from Orbitrap or Q-TOF instruments) in MGF format with known precursor m/z, adduct type, and collision energy, and you need to generate ranked molecular formula candidates. This is especially valuable when upstream tools (SIRIUS, BUDDY) produce many candidates and you need to rescore or refine them, or when you have no candidate list and need initial formula hypotheses.

## When NOT to use

- Spectra are from instruments not trained on (FIDDLE is validated on Orbitrap and Q-TOF; performance on other types is unknown).
- MGF input lacks required fields (PRECURSOR_MZ, PRECURSOR_TYPE, COLLISION_ENERGY); the pipeline will fail or produce unreliable predictions.
- You need to predict molecular structures, not formulas; FIDDLE outputs formulas only and cannot disambiguate isomers.

## Inputs

- MGF file with MS/MS spectra (TITLE, PRECURSOR_MZ, PRECURSOR_TYPE, COLLISION_ENERGY required)
- Pre-trained FIDDLE v2.0.0 model checkpoint (tcn and rescore .pt files)
- Instrument type designation (orbitrap or qtof)

## Outputs

- CSV table with one row per spectrum: ID, precursor mass, initial predicted formula, refined formula candidates (top-5), rescore confidence scores (0–1), predicted atom/H/C counts
- Optionally: JSON or structured Python list of candidate dictionaries (formula, score, mass, metadata)

## How to apply

Load the FIDDLE v2.0.0 pre-trained checkpoint (available from zenodo.org/record/19181279 or via msfiddle-download-models) matching your instrument type (orbitrap or qtof). Prepare input spectra in MGF format with required fields: TITLE, PRECURSOR_MZ, PRECURSOR_TYPE (e.g., '[M+H]+'), COLLISION_ENERGY, and peak m/z–intensity pairs. Execute the inference pipeline via the msfiddle Python API (MsFiddlePredictor.predict_batch) or CLI (msfiddle --test_data). The TCN encoder generates an initial formula prediction; the Siamese rescore model then rescores refined formula candidates (generated by mass-based perturbations) using learned similarity to ground-truth spectra. Output is a CSV table with columns: predicted formula, predicted mass, atom count, H/C count, and top-k refined candidates ranked by rescore confidence (0–1). Validate by confirming output contains at least one ranked formula per spectrum and that rescore scores fall within [0, 1].

## Related tools

- **msfiddle** (Python API and CLI for FIDDLE inference; loads checkpoints and runs batch/single-spectrum predictions) — https://github.com/josiehong/msfiddle
- **FIDDLE** (Research codebase containing model training, evaluation, and reproduction scripts; hosts pre-trained checkpoints) — https://github.com/JosieHong/FIDDLE
- **BUDDY** (Optional upstream tool for generating alternative formula candidates; output can be rescored by FIDDLE rescore model) — https://github.com/Philipbear/msbuddy
- **SIRIUS** (Optional upstream tool for generating alternative formula candidates; output can be rescored by FIDDLE rescore model) — https://v6.docs.sirius-ms.io/

## Examples

```
msfiddle --test_data /path/to/data.mgf --instrument_type orbitrap --result_path /path/to/results.csv --device 0
```

## Evaluation signals

- Output CSV is well-formed with one row per input spectrum and required columns (ID, Mass, Pred Formula, Refined Formula 0–4, Rescore 0–4).
- Rescore confidence scores for top-5 candidates are in range [0.0, 1.0] and monotonically decrease or stay equal across ranks.
- Predicted formula mass (calculated from atom counts) matches predicted mass column within <1 ppm tolerance.
- When ground-truth formula is known (from GNPS metadata or external dataset), check if true formula ranks in top-1, top-3, or top-5 (benchmark-specific metric).
- For caffeine (C8H10N4O2, m/z 195.088), FIDDLE should return it as top candidate or within top-5 on GNPS orbitrap spectra; absence suggests model loading or input format error.

## Limitations

- Performance is instrument-specific: separate checkpoints for Orbitrap and Q-TOF; cross-instrument transfer is not validated.
- Prediction accuracy depends on spectrum quality and fragmentation pattern; low-intensity or noise-dominated spectra may yield unreliable candidates.
- The rescore model is trained on ground-truth formulas; it rescores candidates within a chemical validity space but cannot discover entirely novel formulas outside the training domain.
- Collision energy must be provided and should match the training distribution (typically 10–100 eV for Orbitrap); unknown or extreme CE values may degrade performance.
- FIDDLE v2.0.0 introduces a breaking change (Siamese rescore architecture); checkpoints from v1.x are incompatible; all usage must pin to v2.0.0 or later.

## 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."
- [readme] The rescore model has been redesigned with a Siamese architecture in v2.0.0.: "The rescore model has been redesigned (Siamese architecture), see details in [CHANGELOG.md](./CHANGELOG.md)."
- [readme] Required MGF fields are TITLE, PRECURSOR_MZ, PRECURSOR_TYPE, and COLLISION_ENERGY.: "The required MGF fields are `TITLE`, `PRECURSOR_MZ`, `PRECURSOR_TYPE`, and `COLLISION_ENERGY`"
- [readme] Output CSV includes predicted formula, refined candidates (top-5), and rescore confidence scores.: "Key columns include: `ID`, `Mass`, `Pred Formula`, `Refined Formula (0..4)`, `Refined Mass (0..4)`, `Rescore (0..4)`"
- [readme] MsFiddlePredictor enables reuse of loaded models for efficient batched prediction.: "For repeated or batched prediction, reuse `MsFiddlePredictor` so checkpoints are loaded once"
- [readme] The test_caffeine.py script demonstrates running FIDDLE on a caffeine Orbitrap spectrum fetched live from GNPS.: "See [`test_caffeine.py`](./test_caffeine.py) for a worked example running FIDDLE on a caffeine Orbitrap spectrum fetched live from GNPS."
- [readme] Pre-trained checkpoint assets are reused across msfiddle 2.x releases using FIDDLE v2.0.0.: "All `msfiddle` 2.x releases reuse the FIDDLE `v2.0.0` checkpoint assets."