msfiddle 2.3.0

FIDDLE predicts molecular formulas from MS/MS spectra with deep learning.

Paper · Documentation · Try the demo on Hugging Face

Quick start

Install the msfiddle package, download the pre-trained models once, then predict formulas:

pip install "msfiddle[inference]"
msfiddle download
msfiddle predict --demo --result_path demo.csv        # 21 bundled example spectra

# your own spectra
msfiddle predict --test_data spectra.mgf --instrument_type orbitrap --result_path results.csv

Use --instrument_type qtof for Q-TOF data and --instrument_type timstof for timsTOF data. Each spectrum needs TITLE, PRECURSOR_MZ, PRECURSOR_TYPE and COLLISION_ENERGY. The results list ranked candidates per spectrum in Refined Formula (0), Refined Formula (1), … with their scores in Rescore (k).

When the true formulas are known (a SMILES or FORMULA field in each spectrum), add --eval to also report top-k accuracy, saved as results_eval.csv.

The documentation covers the Python API, BUDDY and SIRIUS integration, custom checkpoints, all output columns, and benchmark results.

Reproduce the paper

This repository also holds the research code for training and evaluation. Run everything from the repository root (FIDDLE/).

1. Create the environment with Anaconda (use environment_mac.yml on Apple Silicon):

conda env create -f environment.yml

2. (optional) Install BUDDY and SIRIUS for the comparison experiments. SIRIUS needs a free account; log in once as install_sirius.sh prints at the end.

bash running_scripts/install_buddy.sh
bash running_scripts/install_sirius.sh

3. Download the models into ./check_point/, where the scripts expect them:

msfiddle download -d ./check_point

The benchmark, chimeric and noise experiments use the released models; the chimeric and noise ones also need the data those models were trained on.

To train from scratch, see scripts/train_tcn_gpus_cl.py and scripts/train_rescore.py with the configs in msfiddle/config/.

Citation

If you use FIDDLE, please cite:

@article{hong2025fiddle,
  title={FIDDLE: a deep learning method for chemical formulas prediction from tandem mass spectra},
  author={Hong, Yuhui and Li, Sujun and Ye, Yuzhen and Tang, Haixu},
  journal={Nature Communications},
  volume={16},
  number={1},
  pages={11102},
  year={2025},
  publisher={Nature Publishing Group UK London}
}