Skip to main content

Python library for fuzzy comparison of mass spectrum data and other Python objects

Project description


Matchms is an open-source Python package to import, process, clean, and compare mass spectrometry data (MS/MS). It allows to implement and run an easy-to-follow, easy-to-reproduce workflow from raw mass spectra to pre- and post-processed spectral data. Spectral data can be imported from common formats such mzML, mzXML, msp, metabolomics-USI, MGF, or json (e.g. GNPS-syle json files). Matchms then provides filters for metadata cleaning and checking, as well as for basic peak filtering. Finally, matchms was build to import and apply different similarity measures to compare large amounts of spectra. This includes common Cosine scores, but can also easily be extended by custom measures. Example for spectrum similarity measures that were designed to work in matchms are Spec2Vec and MS2DeepScore.

If you use matchms in your research, please cite the following software paper:

F Huber, S. Verhoeven, C. Meijer, H. Spreeuw, E. M. Villanueva Castilla, C. Geng, J.J.J. van der Hooft, S. Rogers, A. Belloum, F. Diblen, J.H. Spaaks, (2020). matchms - processing and similarity evaluation of mass spectrometry data. Journal of Open Source Software, 5(52), 2411,

  Badges recommendations  
1. Code repository GitHub Badge
2. License License Badge
3. Community Registry Conda Badge Pypi Badge Research Software Directory Badge
4. Enable Citation JOSS Badge Zenodo Badge
5. Checklists CII Best Practices Badge Howfairis badge
Code quality checks  
Continuous integration Continuous integration workflow
Documentation Documentation Status
Code Quality Sonarcloud Quality Gate Sonarcloud Coverage

Latest changes (matchms >= 0.11.0)

Matchms now allows proper logging. Matchms functions and method report unexpected or undesired behavior as logging WARNING, and additional information as INFO. The default logging level is set to WARNING. If you want to output additional logging messages, you can lower the logging level to INFO using set_matchms_logger_level:

from matchms import set_matchms_logger_level


If you want to suppress logging warnings, you can also raise the logging level to ERROR by:


To write logging entries to a local file, you can do the following:

from matchms.logging_functions import add_logging_to_file

add_logging_to_file("sample.log", loglevel="INFO")

If you want to write the logging messages to a local file while silencing the stream of such messages, you can do the following:

from matchms.logging_functions import add_logging_to_file

add_logging_to_file("sample.log", loglevel="INFO",

Latest changes (matchms >= 0.10.0)

  • 2 new filters in matchms.filtering: add_retention_time() and add_retention_index(), to consistently add retention time/index to the spectrum metadata
  • Hashes! Spectrum-objects now allow to compute different hashes:
from matchms.importing import load_from_mgf

# Read spectrums from a MGF formatted file, for other formats see
spectrums = list(load_from_mgf("tests/pesticides.mgf"))

# Spectrum hashes are generated based on MS/MS peak m/z and intensities
# Those will change if any processing step affects the peaks.
spectrum_hashes = [s.spectrum_hash() for s in spectrums]
# Metadata hashes are generated based on the spectrum metadata
# Those will change if any processing step affects the metadata.
metadata_hashes = [s.metadata_hash() for s in spectrums]
# `hash(spectrum)` will return a hash that is a combination of spectrum and metadata hash
# Those will hence change if any processing step affects the peaks and/or the metadata.
hashes = [hash(s) for s in spectrums]

Documentation for users

For more extensive documentation see our readthedocs and our matchms introduction tutorial.



  • Python 3.7, 3.8 or 3.9
  • Anaconda (recommended)

We recommend installing matchms from Anaconda Cloud with

# install matchms in a new virtual environment to avoid dependency clashes
conda create --name matchms python=3.8
conda activate matchms
conda install --channel bioconda --channel conda-forge matchms

Alternatively, matchms can also be installed using pip but users will then either have to install rdkit on their own or won’t be able to use the entire functionality. Without rdkit installed several filter functions related to processing and cleaning chemical metadata will not run. To install matchms with pip simply run

pip install matchms

matchms ecosystem -> additional functionalities

Matchms functionalities can be complemented by additional packages. To date we are aware of:

  • Spec2Vec an alternative machine-learning spectral similarity score that can simply be installed by pip install spec2vec and be imported as from spec2vec import Spec2Vec following the same API as the scores in matchms.similarity.
  • MS2DeepScore a supervised, deep-learning based spectral similarity score that can simply be installed by pip install ms2deepscore and be imported as from ms2deepscore import MS2DeepScore following the same API as the scores in matchms.similarity.
  • matchmsextras which contains additional functions to create networks based on spectral similarities, to run spectrum searchers against PubChem, or additional plotting methods.
  • memo a method allowing a Retention Time (RT) agnostic alignment of metabolomics samples using the fragmentation spectra (MS2) of their consituents.

(if you know of any other packages that are fully compatible with matchms, let us know!)


To get started with matchms, we recommend following our matchms introduction tutorial.

Alternatively, here below is a small example of using matchms to calculate the Cosine score between mass Spectrums in the tests/pesticides.mgf file.

from matchms.importing import load_from_mgf
from matchms.filtering import default_filters
from matchms.filtering import normalize_intensities
from matchms import calculate_scores
from matchms.similarity import CosineGreedy

# Read spectrums from a MGF formatted file, for other formats see
file = load_from_mgf("tests/pesticides.mgf")

# Apply filters to clean and enhance each spectrum
spectrums = []
for spectrum in file:
    # Apply default filter to standardize ion mode, correct charge and more.
    # Default filter is fully explained at .
    spectrum = default_filters(spectrum)
    # Scale peak intensities to maximum of 1
    spectrum = normalize_intensities(spectrum)

# Calculate Cosine similarity scores between all spectrums
# For other similarity score methods see .
scores = calculate_scores(references=spectrums,

# Print the calculated scores for each spectrum pair
for score in scores:
    (reference, query, score) = score
    # Ignore scores between same spectrum and
    # pairs which have less than 20 peaks in common
    if reference is not query and score["matches"] >= 20:
        print(f"Reference scan id: {reference.metadata['scans']}")
        print(f"Query scan id: {query.metadata['scans']}")
        print(f"Score: {score['score']:.4f}")
        print(f"Number of matching peaks: {score['matches']}")

Glossary of terms

Term Description
adduct / addition product During ionization in a mass spectrometer, the molecules of the injected compound break apart into fragments. When fragments combine into a new compound, this is known as an addition product, or adduct. Wikipedia
GNPS Knowledge base for sharing of mass spectrometry data (link).
InChI / INCHI InChI is short for International Chemical Identifier. InChIs are useful in retrieving information associated with a certain molecule from a database.
InChIKey / InChI key / INCHIKEY An identifier for molecules. For example, the InChI key for carbon dioxide is InChIKey=CURLTUGMZLYLDI-UHFFFAOYSA-N (yes, it includes the substring InChIKey=).
MGF File / Mascot Generic Format A plan ASCII file format to store peak list data from a mass spectrometry experiment. Links:,
parent mass / parent_mass Actual mass (in Dalton) of the original compound prior to fragmentation. It can be recalculated from the precursor m/z by taking into account the charge state and proton/electron masses.
precursor m/z / precursor_mz Mass-to-charge ratio of the compound targeted for fragmentation.
SMILES A line notation for describing the structure of chemical species using short ASCII strings. For example, water is encoded as O[H]O, carbon dioxide is encoded as O=C=O, etc. SMILES-encoded species may be converted to InChIKey using a resolver like this one. The Wikipedia entry for SMILES is here.

Documentation for developers


To install matchms, do:

git clone
cd matchms
conda create --name matchms-dev python=3.8
conda activate matchms-dev
# Install rdkit using conda, rest of dependencies can be installed with pip
conda install -c conda-forge rdkit
python -m pip install --upgrade pip
pip install --editable .[dev]

Run the linter with:


Automatically fix incorrectly sorted imports:

isort --recursive .

Files will be changed in place and need to be committed manually.

Run tests (including coverage) with:


Conda package

The conda packaging is handled by a recipe at Bioconda.

Publishing to PyPI will trigger the creation of a pull request on the bioconda recipes repository Once the PR is merged the new version of matchms will appear on



Flowchart of matchms workflow. Reference and query spectrums are filtered using the same set of set filters (here: filter A and filter B). Once filtered, every reference spectrum is compared to every query spectrum using the matchms.Scores object.


If you want to contribute to the development of matchms, have a look at the contribution guidelines.


Copyright (c) 2021, Netherlands eScience Center

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.


This package was created with Cookiecutter and the NLeSC/python-template.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for matchms, version 0.12.0
Filename, size File type Python version Upload date Hashes
Filename, size matchms-0.12.0.tar.gz (60.1 kB) File type Source Python version None Upload date Hashes View
Filename, size matchms-0.12.0-py3-none-any.whl (87.3 kB) File type Wheel Python version py3 Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page