ms2deepscore

ms2deepscore provides a Siamese neural network that is trained to predict molecular structural similarities (Tanimoto scores) from pairs of mass spectrometry spectra.

The library provides intuitive classes to prepare data, train a Siamese model, and compute similarities between pairs of spectra.

In addition to the prediction of a structural similarity, MS2DeepScore can also make use of Monte-Carlo dropout to assess the model's uncertainty.

Reference

If you use MS2DeepScore for your research, please cite the following:

"MS2DeepScore - a novel deep learning similarity measure to compare tandem mass spectra" Florian Huber, Sven van der Burg, Justin J.J. van der Hooft, Lars Ridder, 13, Article number: 84 (2021), Journal of Cheminformatics, doi: https://doi.org/10.1186/s13321-021-00558-4

If you use MS2Deepscore 2.0 or higher please also cite: Reliable cross-ion mode chemical similarity prediction between MS2 spectra Niek de Jonge, David Joas, Lem-Joe Truong, Justin J.J. van der Hooft, Florian Huber bioRxiv 2024.03.25.586580; doi: https://doi.org/10.1101/2024.03.25.586580

Setup

Requirements

Python 3.10, 3.11, 3.12 (higher will likely work but is not tested systematically).

Installation

Installation is expected to take 10-20 minutes.

Prepare environment

We recommend creating an Anaconda environment with

conda create --name ms2deepscore python=3.9 conda activate ms2deepscore pip install ms2deepscore

Or, via conda: conda create --name ms2deepscore python=3.9 conda activate ms2deepscore conda install --channel bioconda --channel conda-forge matchms pip install ms2deepscore

Alternatively, simply install in the environment of your choice by pip install ms2deepscore

Getting started: How to prepare data, train a model, and compute similarities.

We recommend to run the complete tutorial in notebooks/MS2DeepScore_tutorial.ipynb for a more extensive fully-working example on test data. The expected run time on a laptop is less than 5 minutes, including automatic model and dummy data download. Alternatively there are some example scripts below. If you are not familiar with matchms yet, then we also recommand our tutorial on how to get started using matchms.

1) Compute spectral similarities

We provide a model which was trained on > 500,000 MS/MS combined spectra from GNPS, Mona, MassBank and MSnLib. This model can be downloaded from from zenodo here. Only the ms2deepscore_model.pt is needed. The model works for spectra in both positive and negative ionization modes and even predictions across ionization modes can be made by this model.

To compute the similarities between spectra of your choice you can run the code below. There is a small example dataset available in the folder "./tests/resources/pesticidesprocessed.mgf". Alternatively you can of course use your own spectra, most common formats are supported, e.g. msp, mzml, mgf, mzxml, json, usi. ```python from ms2deepscore.models import loadmodel from matchms.Pipeline import Pipeline, createworkflow from matchms.filtering.defaultpipelines import DEFAULT_FILTERS from ms2deepscore import MS2DeepScore

modelfilename = "ms2deepscoremodel.pt" spectrumfile_name = "pesticides.mgf"

load in the ms2deepscore model

model = loadmodel(modelfile_name)

pipeline = Pipeline(createworkflow(queryfilters=DEFAULTFILTERS, scorecomputations=[[MS2DeepScore, {"model": model}]])) report = pipeline.run(spectrumfilename) similaritymatrix = pipeline.scores.toarray() ``` The resulting similarity matrix, is a numpy array containing all the MS2DeepScore predicitons between all spectra.

2 Create embeddings

To calculate chemical similarity scores MS2DeepScore first calculates an embedding (vector) representing each spectrum. This intermediate product can also be used to visualize spectra in "chemical space" by using a dimensionality reduction technique, like UMAP.

```python cleanedspectra = pipeline.spectraqueries

ms2dsmodel = MS2DeepScore(model) ms2dsembeddings = ms2dsmodel.getembeddingarray(cleanedspectra) ``` The tutorial shows how to use these embeddings to create an interactive UMAP with overlaying smiles.

3) Train your own MS2DeepScore model

Training your own model is only recommended if you have some familiarity with machine learning. You can train a new model on a dataset of your choice. That, however, should preferentially contain a substantial amount of spectra to learn relevant features, say > 100,000 spectra of sufficiently diverse types. Alternatively you can add your in house spectra to an already available public library, for instance the data used for training the default MS2DeepScore model. To train your own model you can run the code below. Please first ensure cleaning your spectra. We recommend using the cleaning pipeline in matchms.

```python from ms2deepscore import SettingsMS2Deepscore from ms2deepscore.wrapperfunctions.trainingwrapperfunctions import trainms2deepscore_wrapper

spectrumfile = "./combinedlibraries.mgf"

The settins below use default training settings and use precursor mz and ionmode as additional metadata input.

Have a look in the SettingsMS2Deepscore class to check other hyperparameters.

settings = SettingsMS2Deepscore( additionalmetadata=[("CategoricalToBinary", {"metadatafield": "ionmode", "entriesbecomingone": "positive", "entriesbecomingzero": "negative"}), ("StandardScaler", {"metadatafield": "precursormz", "mean": 0, "standard_deviation": 1000})],)

trainms2deepscorewrapper(spectrumfile, settings, validationsplit_fraction=20) ```

Contributing

We welcome contributions to the development of ms2deepscore! Have a look at the contribution guidelines.