msbuddy is developed for molecular formula analysis in MS-based small molecule 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 install a specific version, see PyPI release history.

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(# highly recommended to specify
                           ms_instr='orbitrap',  # supported: "qtof", "orbitrap" and "fticr"
                           # whether to consider halogen atoms FClBrI
                           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.

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'])

• generate molecular formulas from a neutral mass (mass_to_formula)
• generate molecular formulas from a charged m/z value (mz_to_formula)
• predict formula feasibility using a deep learning model (predict_formula_feasibility)
• 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)

See more in the documentation.

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 -details

for a single USI string (from FT-ICR, for example):

msbuddy -usi <usi_string> -output <output_folder> -ms fticr

or a csv file (template files) containing multiple USI strings (QTOF in this example):

msbuddy -csv <csv_file> -output <output_folder> -ms qtof -details

For 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 -hal

Run the following command to see the full list of options:

msbuddy --help

msbuddy Documentation

PyPI release

Change log

GitHub repository

S. 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 [email protected] or [email protected].