Skip to main content

Molecular formula annotation for MS-based small molecule analysis.

Project description

msbuddy

Maintainer PyPI docs Generic badge

Sample Image

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/.

Installation

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.

Python usage

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.

Other API functions

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

Links

msbuddy documentation

PyPI release

Change log

GitHub repository

Citation

S. Xing et al. BUDDY: molecular formula discovery via bottom-up MS/MS interrogation. Nature Methods 2023. DOI: 10.1038/s41592-023-01850-x

License

This work is licensed under the Apache License 2.0.

Contact

Please contact the msbuddy developer & maintainer Shipei Xing via s1xing@health.ucsd.edu or philipxsp@hotmail.com.

Project details


Download files

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

Source Distribution

msbuddy-0.3.8.tar.gz (46.8 kB view details)

Uploaded Source

Built Distribution

msbuddy-0.3.8-py3-none-any.whl (51.7 kB view details)

Uploaded Python 3

File details

Details for the file msbuddy-0.3.8.tar.gz.

File metadata

  • Download URL: msbuddy-0.3.8.tar.gz
  • Upload date:
  • Size: 46.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.8.18

File hashes

Hashes for msbuddy-0.3.8.tar.gz
Algorithm Hash digest
SHA256 c520d263b4f344fb2f9dc4ceaf71d2c63600d49a6a48118bc0b6a533c039048f
MD5 eddd92b8710e0497f85f66ce68306e12
BLAKE2b-256 86f03946c1c7ec4dbacad8585a082d975035fd0ddc3bed4e41aee29ab437385b

See more details on using hashes here.

File details

Details for the file msbuddy-0.3.8-py3-none-any.whl.

File metadata

  • Download URL: msbuddy-0.3.8-py3-none-any.whl
  • Upload date:
  • Size: 51.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.8.18

File hashes

Hashes for msbuddy-0.3.8-py3-none-any.whl
Algorithm Hash digest
SHA256 389caaa56bf876c4b55e6d406b86fe6a2dc42f10cc79f5f3987d9f974570a96f
MD5 a853a9cf5261d36b584ef782d9c93f32
BLAKE2b-256 48300a3a49e0bfa44f051561d4550126256842391e0f2361fee19cc12564b785

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page