Metadata-Version: 2.4
Name: msfiddle
Version: 2.2.1
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

<p align="center">
  <a href="https://github.com/JosieHong/FIDDLE">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/JosieHong/FIDDLE/main/img/fiddle-logo-dark@2x.png">
      <img src="https://raw.githubusercontent.com/JosieHong/FIDDLE/main/img/fiddle-logo-light@2x.png" alt="FIDDLE" width="480">
    </picture>
  </a>
</p>

[![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)

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

**[Paper](https://www.nature.com/articles/s41467-025-66060-9)** · **[Documentation](https://msfiddle.readthedocs.io)** · **[Try the demo on Hugging Face](https://huggingface.co/spaces/J0siee/FIDDLE)**

## Quick start

Install the [`msfiddle`](https://pypi.org/project/msfiddle/) package, download the pre-trained models once, then predict formulas:

```bash
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. 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](https://msfiddle.readthedocs.io) covers the Python API, BUDDY and SIRIUS integration, custom checkpoints, and all output columns.

## 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](https://docs.anaconda.com/anaconda/install/) (use `environment_mac.yml` on Apple Silicon):

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

2. (optional) Install [BUDDY](https://github.com/Philipbear/msbuddy) and [SIRIUS](https://v6.docs.sirius-ms.io/) for the comparison experiments.

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

```bash
msfiddle download -d ./check_point
```

| Script | Description |
|---|---|
| `running_scripts/train_release_v2.2.sh` | Build the data and train the release models (TCN and rescore, Q-TOF and Orbitrap) |
| `running_scripts/experiments_test_benchmark.sh` | Evaluate on external benchmarks (CASMI 2016, CASMI 2017, EMBL-MCF 2.0) |
| `running_scripts/experiments_test_nist23.sh` | Train and evaluate with compounds new in NIST23 held out |
| `running_scripts/experiments_test_chimeric.sh` | Evaluate on chimeric spectra |
| `running_scripts/experiments_test_noised.sh` | Evaluate on spectra with added noise peaks |

The benchmark, chimeric and noise experiments use the released models; the chimeric and noise ones also need the data built by `train_release_v2.2.sh`.

To train from scratch, see `scripts/train_tcn_gpus.py`, `scripts/train_tcn_gpus_cl.py` and `scripts/train_rescore.py` with the configs in [`msfiddle/config/`](https://github.com/JosieHong/FIDDLE/tree/main/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}
}
```
