Package: matchms
fair-software.nlrecommendations:Code quality checks: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 includeSpec2VecandMS2DeepScore. 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.02411de Jonge NF, Hecht H, van der Hooft JJJ, Huber F. (2023). Reproducible MS/MS library cleaning pipeline in matchms. ChemRxiv. Cambridge: Cambridge Open Engage; 2023,https://doi.org/10.26434/chemrxiv-2023-l44cmLatest changes (matchms >= 0.18.0)Pipeline classTo make typical matchms workflows (data import, processing, score computations) more accessible to users, matchms now offers aPipelineclass 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 arrayWe 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).Documentation for usersFor more extensive documentationsee our readthedocsand ourmatchms introduction tutorial.InstallationPrerequisites:Python 3.8 - 3.11, (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 clashesconda create --name matchms python=3.9
conda activate matchms
conda install --channel bioconda --channel conda-forge matchmsAlternatively, matchms can also be installed usingpip. In the most basic version matchms will then come withoutrdkitso that several filter functions related to processing and cleaning chemical metadata will not run. To includerdkitinstall matchms asmatchms[chemistry]:pip install matchms  # simple install w/o rdkit
pip install matchms[chemistry]  # full install including rdkitmatchms ecosystem -> additional functionalitiesMatchms functionalities can be complemented by additional packages.
To date, we are aware of:Spec2Vecan alternative machine-learning spectral similarity score that can simply be installed bypip install spec2vecand be imported asfrom spec2vec import Spec2Vecfollowing the same API as the scores inmatchms.similarity.MS2DeepScorea supervised, deep-learning based spectral similarity score that can simply be installed bypip install ms2deepscoreand be imported asfrom ms2deepscore import MS2DeepScorefollowing the same API as the scores inmatchms.similarity.matchmsextraswhich contains additional functions to create networks based on spectral similarities, to run spectrum searchers againstPubChem, or additional plotting methods.MS2QueryReliable and fast MS/MS spectral-based analogue search, running on top of matchms.memoa method allowing a Retention Time (RT) agnostic alignment of metabolomics samples using the fragmentation spectra (MS2) of their constituents.RIAssignera tool for retention index calculation for gas chromatography - mass spectrometry (GC-MS) data.MSMetaEnhanceris a python package to collect mass spectral library metadata using various web services and computational chemistry packages.(if you know of any other packages that are fully compatible with matchms, let us know!)IntroductionTo get started with matchms, we recommend following ourmatchms introduction tutorial.Below is an example of using default filter steps for cleaning spectra,
followed by calculating the Cosine score between mass Spectrums in thetests/testdata/pesticides.mgffile.frommatchms.PipelineimportPipeline,create_workflowworkflow=create_workflow(yaml_file_name="my_config_file.yaml",# The workflow will be stored in a yaml file, this can be used to rerun your workflow or to share it with others.score_computations=[["cosinegreedy",{"tolerance":1.0}]],)pipeline=Pipeline(workflow)pipeline.logging_file="my_pipeline.log"# for pipeline and logging messagepipeline.run("tests/testdata/pesticides.mgf")Below is a more advanced code example showing how you can make a specific pipeline for your needs.importosfrommatchms.PipelineimportPipeline,create_workflowfrommatchms.filtering.default_pipelinesimportDEFAULT_FILTERS,LIBRARY_CLEANINGresults_folder="./results"os.makedirs(results_folder,exist_ok=True)workflow=create_workflow(yaml_file_name=os.path.join(results_folder,"my_config_file.yaml"),# The workflow will be stored in a yaml file.query_filters=DEFAULT_FILTERS,reference_filters=LIBRARY_CLEANING+["add_fingerprint"],score_computations=[["precursormzmatch",{"tolerance":100.0}],["cosinegreedy",{"tolerance":1.0}],["filter_by_range",{"name":"CosineGreedy_score","low":0.2}]],)pipeline=Pipeline(workflow)pipeline.logging_file=os.path.join(results_folder,"my_pipeline.log")# for pipeline and logging messagepipeline.logging_level="WARNING"# To define the verbosety of the loggingpipeline.run("tests/testdata/pesticides.mgf","my_reference_library.mgf",cleaned_query_file=os.path.join(results_folder,"cleaned_query_spectra.mgf"),cleaned_reference_file=os.path.join(results_folder,"cleaned_library_spectra.mgf"))# choose your own filesAlternatively, in particular, if you need more room to add custom functions and steps, the individual steps can run without using the matchmsPipeline:frommatchms.importingimportload_from_mgffrommatchms.filteringimportdefault_filters,normalize_intensitiesfrommatchmsimportcalculate_scoresfrommatchms.similarityimportCosineGreedy# Read spectrums from a MGF formatted file, for other formats see https://matchms.readthedocs.io/en/latest/api/matchms.importing.htmlfile=load_from_mgf("tests/testdata/pesticides.mgf")# Apply filters to clean and enhance each spectrumspectrums=[]forspectruminfile:# Apply default filter to standardize ion mode, correct charge and more.# Default filter is fully explained at https://matchms.readthedocs.io/en/latest/api/matchms.filtering.html .spectrum=default_filters(spectrum)# Scale peak intensities to maximum of 1spectrum=normalize_intensities(spectrum)spectrums.append(spectrum)# Calculate Cosine similarity scores between all spectrums# For other similarity score methods see https://matchms.readthedocs.io/en/latest/api/matchms.similarity.html .scores=calculate_scores(references=spectrums,queries=spectrums,similarity_function=CosineGreedy())# Matchms allows to get the best matches for any query using scores_by_queryquery=spectrums[15]# just an examplebest_matches=scores.scores_by_query(query,'CosineGreedy_score',sort=True)# Print the calculated scores for each spectrum pairfor(reference,score)inbest_matches[:10]:# Ignore scores between same spectraifreferenceisnotquery:print(f"Reference scan id:{reference.metadata['scans']}")print(f"Query scan id:{query.metadata['scans']}")print(f"Score:{score[0]:.4f}")print(f"Number of matching peaks:{score[1]}")print("----------------------------")Different spectrum similarity scoresMatchms comes with numerous different scoring methods inmatchms.similarityand can further seamlessly work withSpec2VecorMS2DeepScore.Code example:frommatchms.importingimportload_from_usiimportmatchms.filteringasmsfiltersimportmatchms.similarityasmssimusi1="mzspec:GNPS:GNPS-LIBRARY:accession:CCMSLIB00000424840"usi2="mzspec:MSV000086109:BD5_dil2x_BD5_01_57213:scan:760"mz_tolerance=0.1spectrum1=load_from_usi(usi1)spectrum1=msfilters.select_by_mz(spectrum1,0,spectrum1.get("precursor_mz"))spectrum1=msfilters.remove_peaks_around_precursor_mz(spectrum1,mz_tolerance=0.1)spectrum2=load_from_usi(usi2)spectrum2=msfilters.select_by_mz(spectrum2,0,spectrum1.get("precursor_mz"))spectrum2=msfilters.remove_peaks_around_precursor_mz(spectrum2,mz_tolerance=0.1)# Compute scores:similarity_cosine=mssim.CosineGreedy(tolerance=mz_tolerance).pair(spectrum1,spectrum2)similarity_modified_cosine=mssim.ModifiedCosine(tolerance=mz_tolerance).pair(spectrum1,spectrum2)similarity_neutral_losses=mssim.NeutralLossesCosine(tolerance=mz_tolerance).pair(spectrum1,spectrum2)print(f"similarity_cosine:{similarity_cosine}")print(f"similarity_modified_cosine:{similarity_modified_cosine}")print(f"similarity_neutral_losses:{similarity_neutral_losses}")spectrum1.plot_against(spectrum2)Documentation for developersInstallationTo install matchms, do:git clone https://github.com/matchms/matchms.git
cd matchms
conda create --name matchms-dev python=3.8
conda activate matchms-dev#Installrdkitusingconda,restofdependenciescanbeinstalledwithpipconda install -c conda-forge rdkit
python -m pip install --upgrade pip
pip install --editable .[dev]  # if this won't work try "poetry install"Run the linter with:prospectorAutomatically fix incorrectly sorted imports:isort .Files will be changed in place and need to be committed manually. If you only want to inspect the isort suggestions then simply run:isort --check-only --diff .Run tests (including coverage) with:pytestConda packageThe conda packaging is handled by arecipe at Bioconda.Publishing to PyPI will trigger the creation of apull request on the bioconda recipes repositoryOnce the PR is merged the new version of matchms will appear onhttps://anaconda.org/bioconda/matchmsFlowchartFlowchart 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.ContributingIf you want to contribute to the development of matchms,
have a look at thecontribution guidelines.LicenseCopyright (c) 2023, Düsseldorf University of Applied Sciences & Netherlands eScience CenterLicensed 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 athttp://www.apache.org/licenses/LICENSE-2.0Unless 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.CreditsThis package was created withCookiecutterand theNLeSC/python-template.