Metadata-Version: 2.4
Name: msfiddle
Version: 2.2.0
Summary: A package for predicting chemical formulas from tandem mass spectra
Home-page: https://github.com/JosieHong/FIDDLE
Author: Yuhui Hong
Author-email: josieexception@outlook.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<2.0.0,>=1.20.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: tqdm>=4.60.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: scipy>=1.8.0
Requires-Dist: pyarrow>=10.0.0
Requires-Dist: rdkit>=2022.03.5
Requires-Dist: molmass
Requires-Dist: pyteomics
Provides-Extra: inference
Requires-Dist: torch; extra == "inference"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# FIDDLE

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.19181279-blue)](https://doi.org/10.5281/zenodo.19181279)
[![Release](https://img.shields.io/github/v/release/JosieHong/FIDDLE?label=Release)](https://github.com/JosieHong/FIDDLE/releases)

[<img src="https://raw.githubusercontent.com/JosieHong/FIDDLE/main/img/fiddle_logo.png" align="right" width="220">](https://github.com/JosieHong/FIDDLE)

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, plus the [`msfiddle`](https://pypi.org/project/msfiddle/) PyPI package (in [`./msfiddle/`](https://github.com/JosieHong/FIDDLE/tree/main/msfiddle)) for inference-only use.

- **Paper:** [Nature Communications (2025)](https://www.nature.com/articles/s41467-025-66060-9)
- **CLI and Python API:** `pip install "msfiddle[inference]"` — see the [package docs](https://msfiddle.readthedocs.io)
- **Try this demo!** [FIDDLE on Hugging Face](https://huggingface.co/spaces/J0siee/FIDDLE)

<br clear="right"/>

> **Breaking change (v2.0.0):** The rescore model has been redesigned (Siamese architecture), see details in [CHANGELOG.md](https://github.com/JosieHong/FIDDLE/blob/main/CHANGELOG.md).

## Set up

### Requirements

1. Install [Anaconda](https://docs.anaconda.com/anaconda/install/), if not already installed.

2. Create the environment with the necessary packages:

```bash
conda env create -f environment.yml
```

On Apple Silicon (macOS ARM64), use `environment_mac.yml` instead.

3. (optional) Install [BUDDY](https://github.com/Philipbear/msbuddy) and [SIRIUS](https://v6.docs.sirius-ms.io/) following the respective installation instructions provided in each tool's documentation. 

### Pre-trained Model Weights

To use the pre-trained models, please use the following scripts to download the weights from the [release page](https://github.com/JosieHong/FIDDLE/releases/tag/v2.2.0) and place them in the `./check_point/` directory:

- **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 prediction model on Q-TOF spectra
  - `fiddle_rescore_qtof.pt`: rescore model on Q-TOF spectra

```bash
bash ./running_scripts/download_models.sh
```

## Usage

The input format is `mgf`, where `title`, `precursor_mz`, `precursor_type`, `collision_energy` fields are required. Here, we sampled 21 spectra from the EMBL-MCF 2.0 dataset as an example.

```mgf
BEGIN IONS
TITLE=EMBL_MCF_2_0_HRMS_Library000531
PEPMASS=129.01941
CHARGE=1-
PRECURSOR_TYPE=[M-H]-
PRECURSOR_MZ=129.01941
COLLISION_ENERGY=50.0
SMILES=[H]OC(=O)C([H])=C(C(=O)O[H])C([H])([H])[H]
FORMULA=C5H6O4
THEORETICAL_PRECURSOR_MZ=129.018785
PPM=4.844255818912111
SIMULATED_PRECURSOR_MZ=129.02032113281717
41.2041 0.410228
55.7698 0.503672
56.8647 0.461943
85.0296 100.0
129.0196 8.036902
END IONS
```

**Run FIDDLE!**

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

If you'd like to integrate the results from SIRIUS and BUDDY, please organize the results in the format shown in `./msfiddle/demo/buddy_output.csv` and `./msfiddle/demo/sirius_output.csv`, and provide them to run FIDDLE:

```bash
python scripts/run_fiddle.py --test_data ./msfiddle/demo/input_msms.mgf \
                    --config_path ./msfiddle/config/fiddle_tcn_orbitrap.yml \
                    --resume_path ./check_point/fiddle_tcn_orbitrap.pt \
                    --rescore_resume_path ./check_point/fiddle_rescore_orbitrap.pt \
                    --buddy_path ./msfiddle/demo/output_buddy.csv \
                    --sirius_path ./msfiddle/demo/output_sirius.csv \
                    --result_path ./msfiddle/demo/output_fiddle_all.csv --device 0
```

See [`scripts/test_caffeine.py`](https://github.com/JosieHong/FIDDLE/blob/main/scripts/test_caffeine.py) for a worked example running FIDDLE on a caffeine Orbitrap spectrum fetched live from GNPS.

## Reproduce paper results

All scripts should be run from the repository root (`FIDDLE/`).

| Script | Description |
|---|---|
| `running_scripts/experiments_test_benchmark.sh` | Evaluate on external benchmarks (CASMI 2016, CASMI 2017, EMBL-MCF 2.0) |
| `running_scripts/experiments_test_nist23.sh` | Evaluate on NIST23 |
| `running_scripts/experiments_test_chimeric.sh` | Evaluate on chimeric spectra |
| `running_scripts/experiments_test_noised.sh` | Evaluate under noise conditions |
| `running_scripts/experiments_ablation_study.sh` | Run ablation study |
| `running_scripts/experiments_demo.sh` | Run demo experiment |
| `running_scripts/train_released_models.sh` | Train TCN and rescore models for both Orbitrap and Q-TOF |

For training from scratch, see the train scripts (`scripts/train_tcn_gpus.py`, `scripts/train_tcn_gpus_cl.py`, `scripts/train_rescore.py`) and the corresponding config files in `./msfiddle/config/`.

## Citation

```
@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}
}
```
