fair-software.nl <https://fair-software.nl/>_ recommendations:

Code quality checks:

.. image:: readthedocs/_static/matchms_header.png :target: readthedocs/_static/matchms.png :align: left :alt: matchms

Matchms is a versatile open-source Python package developed for importing, processing, cleaning, and comparing mass spectrometry data (MS/MS). It facilitates the implementation of straightforward, reproducible workflows, transforming raw data from common mass spectra file formats into pre- and post-processed spectral data, and enabling large-scale spectral similarity comparisons.

The software supports a range of popular spectral data formats, including mzML, mzXML, msp, metabolomics-USI, MGF, and JSON. Matchms offers an array of tools for metadata cleaning and validation, alongside basic peak filtering, to ensure data accuracy and integrity. A key feature of matchms is its ability to apply various pairwise similarity measures for comparing extensive amounts of spectra. This encompasses not only common Cosine-related scores but also molecular fingerprint-based comparisons and other metadata-related assessments.

One of the strengths of matchms is its extensibility, allowing users to integrate custom similarity measures. Notable examples of spectrum similarity measures tailored for Matchms include Spec2Vec <https://github.com/iomega/spec2vec>_ and MS2DeepScore <https://github.com/matchms/ms2deepscore>_. Additionally, Matchms enhances efficiency by using faster similarity measures for initial pre-selection and supports storing results in sparse data formats, enabling the comparison of several hundred thousands of spectra. This combination of features positions Matchms as a comprehensive tool for mass spectrometry data analysis.

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

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, https://doi.org/10.21105/joss.02411

de Jonge NF, Hecht H, Michael Strobel, Mingxun Wang, van der Hooft JJJ, Huber F. (2024). Reproducible MS/MS library cleaning pipeline in matchms. Journal of Cheminformatics, 2024, https://jcheminf.biomedcentral.com/articles/10.1186/s13321-024-00878-1

.. |GitHub Badge| image:: https://img.shields.io/badge/github-repo-000.svg?logo=github&labelColor=gray&color=blue :target: https://github.com/matchms/matchms :alt: GitHub Badge

.. |License Badge| image:: https://img.shields.io/github/license/matchms/matchms :target: https://github.com/matchms/matchms :alt: License Badge

.. |Conda Badge| image:: https://anaconda.org/bioconda/matchms/badges/version.svg :target: https://anaconda.org/bioconda/matchms :alt: Conda Badge

.. |Pypi Badge| image:: https://img.shields.io/pypi/v/matchms?color=blue :target: https://pypi.org/project/matchms/ :alt: Pypi Badge

.. |Research Software Directory Badge| image:: https://img.shields.io/badge/rsd-matchms-00a3e3.svg :target: https://www.research-software.nl/software/matchms :alt: Research Software Directory Badge

.. |Zenodo Badge| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.3859772.svg :target: https://doi.org/10.5281/zenodo.3859772 :alt: Zenodo Badge

.. |JOSS Badge| image:: https://joss.theoj.org/papers/10.21105/joss.02411/status.svg :target: https://doi.org/10.21105/joss.02411 :alt: JOSS Badge

.. |CII Best Practices Badge| image:: https://bestpractices.coreinfrastructure.org/projects/3792/badge :target: https://bestpractices.coreinfrastructure.org/projects/3792 :alt: CII Best Practices Badge

.. |Howfairis Badge| image:: https://img.shields.io/badge/fair--software.eu-%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F-green :target: https://fair-software.eu :alt: Howfairis badge

.. |CI First Code Checks| image:: https://github.com/matchms/matchms/actions/workflows/CI_first_code_check.yml/badge.svg :alt: Continuous integration workflow :target: https://github.com/matchms/matchms/actions/workflows/CI_first_code_check.yml

.. |CI Build| image:: https://github.com/matchms/matchms/actions/workflows/CI_build.yml/badge.svg :alt: Continuous integration workflow :target: https://github.com/matchms/matchms/actions/workflows/CI_build.yml

.. |ReadTheDocs Badge| image:: https://readthedocs.org/projects/matchms/badge/?version=latest :alt: Documentation Status :target: https://matchms.readthedocs.io/en/latest/?badge=latest

.. |Sonarcloud Quality Gate Badge| image:: https://sonarcloud.io/api/project_badges/measure?project=matchms_matchms&metric=alert_status :target: https://sonarcloud.io/dashboard?id=matchms_matchms :alt: Sonarcloud Quality Gate

.. |Sonarcloud Coverage Badge| image:: https://sonarcloud.io/api/project_badges/measure?project=matchms_matchms&metric=coverage :target: https://sonarcloud.io/component_measures?id=matchms_matchms&metric=Coverage&view=list :alt: Sonarcloud Coverage

Latest changes (matchms >= 0.18.0)

Pipeline class

To make typical matchms workflows (data import, processing, score computations) more accessible to users, matchms now offers a Pipeline class to handle complex workflows. This also allows to create, import, export, or modify workflows using yaml files. See code examples below (and soon: updated tutorial).

Sparse scores array

We realized that many matchms-based workflows aim to compare many-to-many spectra whereby not all pairs and scores are equally important. Often, for instance, it will be about searching similar or related spectra/compounds. This also means that often not all scores need to be stored (or computed). For this reason, we now shifted to a sparse handling of scores in matchms (that means: only storing actually computed, non-null values).

.. image:: readthedocs/_static/matchms_sketch.png :target: readthedocs/_static/matchms_sketch.png :align: left :alt: matchms code design

Documentation for users

For more extensive documentation see our readthedocs <https://matchms.readthedocs.io/en/latest/>, our matchms introduction tutorial <https://blog.esciencecenter.nl/build-your-own-mass-spectrometry-analysis-pipeline-in-python-using-matchms-part-i-d96c718c68ee> or the user documentation <https://matchms.github.io/matchms-docs/intro.html>_.

Installation

Prerequisites:

Python 3.10 - 3.13, (higher versions should work as well, but are not yet tested systematically)
Anaconda (recommended)

We recommend installing matchms in a new virtual environment to avoid dependency clashes

.. code-block:: console

conda create --name matchms python=3.12 conda activate matchms conda install --channel bioconda --channel conda-forge matchms

matchms ecosystem -> additional functionalities

Additional packages can complement Matchms functionalities.
To date, we are aware of:

Spec2Vec <https://github.com/iomega/spec2vec>_ an alternative machine-learning spectral similarity score that can 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 <https://github.com/matchms/ms2deepscore>_ a supervised, deep-learning based spectral similarity score that can 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 <https://github.com/matchms/matchmsextras>_ contains additional functions to create networks based on spectral similarities, run spectrum searchers against PubChem, or additional plotting methods.
MS2Query <https://github.com/iomega/ms2query>_ Reliable and fast MS/MS spectral-based analogue search, running on top of matchms.
memo <https://github.com/mandelbrot-project/memo>_ a method allowing a Retention Time (RT) agnostic alignment of metabolomics samples using the fragmentation spectra (MS2) of their constituents.
RIAssigner <https://github.com/RECETOX/RIAssigner>_ a tool for retention index calculation for gas chromatography - mass spectrometry (GC-MS) data.
MSMetaEnhancer <https://github.com/RECETOX/MSMetaEnhancer>_ is a Python package to collect mass spectral library metadata using various web services and computational chemistry packages.
SimMS <https://github.com/PangeAI/SimMS>_ is a python package with fast GPU-based implementations of common similarity classes such as CudaCosineGreedy, and CudaModifiedCosine.

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

Ecosystem compatibility

.. compatibility matrix start

.. list-table:: :header-rows: 1

- NumPy Version
- spec2vec Status
- ms2deepscore Status
- ms2query Status
- .. image:: https://img.shields.io/badge/numpy-1.25-lightgrey?logo=numpy :alt: numpy
- .. image:: https://img.shields.io/badge/spec2vec-0.9.1-green
- .. image:: https://img.shields.io/badge/ms2deepscore-2.7.2-green
- .. image:: https://img.shields.io/badge/ms2query-1.5.4-red
- .. image:: https://img.shields.io/badge/numpy-2.1-lightgrey?logo=numpy :alt: numpy
- .. image:: https://img.shields.io/badge/spec2vec-0.9.1-green
- .. image:: https://img.shields.io/badge/ms2deepscore-2.7.2-green

Matchms

Install / Use

README

Pipeline class

Sparse scores array

Installation

matchms ecosystem -> additional functionalities

Ecosystem compatibility