msbuddy is developed for molecular formula analysis in MS-based small molecule (<1500 Da) studies.
msbuddy is able to provide formula annotations for queries:
- with or without MS1 isotopic pattern
- with or without MS/MS spectra
- in either positive or negative ionization mode
The minimum requirement for a msbuddy query is a single m/z value and its ionization polarity.
Official documentation is available at https://msbuddy.readthedocs.io/en/latest/.
msbuddy is available on PyPI, you can install the latest version via pip:
pip install msbuddy
To perform formula annotation, you also have to install the lightgbm package.
pip install lightgbm
Note: Python 3.9 or later is required.
Quick start (docs)
As a quick start, we here load a mgf file and annotate the molecular formula for each query.
All the configurations are specified in the MsbuddyConfig class.
Parallel computing is supported.
from msbuddy import Msbuddy, MsbuddyConfig
# instantiate a MsbuddyConfig object
msb_config = MsbuddyConfig(ms_instr='orbitrap', # supported: "qtof", "orbitrap", "fticr" or None
# custom MS1 and MS2 tolerance will be used if None
ppm=True, # use ppm for mass tolerance
ms1_tol=5, # MS1 tolerance in ppm or Da
ms2_tol=10, # MS2 tolerance in ppm or Da
halogen=False)
# instantiate a Msbuddy object
msb_engine = Msbuddy(msb_config)
# load data, here we use a mgf file as an example
msb_engine.load_mgf('input_file.mgf')
# annotate molecular formula
msb_engine.annotate_formula()
# retrieve the annotation result summary
result = msb_engine.get_summary()See demo mgf file.
One of the following fields is recommended to be included, which will be used as the query identifier: TITLE, FEATURE_ID, SPECTRUMID, or SPECTRUM_ID.
MS/MS spectra can be loaded via their USIs if they are publicly available:
# you can load multiple USIs at once
msb_engine.load_usi(['mzspec:GNPS:GNPS-LIBRARY:accession:CCMSLIB00003740036',
'mzspec:GNPS:GNPS-LIBRARY:accession:CCMSLIB00003740037'])Here is a test case on Google Colab.
- parse a formula string (e.g., C6H12O6, 2H2O, C5H7NO2.HCl) (read_formula_str)
- assign subformulas for an MS/MS with a given precursor formula (assign_subformula)
- enumerate all possible subformulas of a given precursor formula (enumerate_subform_arr)
- generate molecular formulas from a neutral mass (mass_to_formula)
- generate molecular formulas from a charged m/z (mz_to_formula)
See more in the documentation.
Command-line tool (docs)
msbuddy can also be used as a command-line tool.
Result summary will be generated in a tsv file.
More detailed annotation results can be written with the -details option (or -d for short).
Here is an example command for a mgf file from Orbitrap:
msbuddy -mgf <mgf_file> -output <output_folder> -ms orbitrap -detailsfor a single USI string (from FT-ICR, for example):
msbuddy -usi <usi_string> -output <output_folder> -ms fticror a csv file (template files) containing multiple USI strings (QTOF in this example):
msbuddy -csv <csv_file> -output <output_folder> -ms qtof -detailsFor mgf file or csv file, you can omit the -output option, and results will be written in the same folder as the input file.
Here is an example of processing a mgf file from Orbitrap (-ms orbitrap) in parallel (-p) using 12 cores (-n_cpu 12). Detailed results are written (-d).
Halogen atoms (FClBrI) are also considered (-hal).
msbuddy -mgf <mgf_file> -ms orbitrap -p -n_cpu 12 -d -halRun the following command to see the full list of options:
msbuddy --helpS. Xing et al. BUDDY: molecular formula discovery via bottom-up MS/MS interrogation. Nature Methods 2023. DOI: 10.1038/s41592-023-01850-x
This work is licensed under the Apache License 2.0.
Please contact the msbuddy developer & maintainer Shipei Xing via s1xing@health.ucsd.edu or philipxsp@hotmail.com.