Molecular formula annotation for MS-based small molecule analysis.
Project description
msbuddy
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
- 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 -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
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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | c520d263b4f344fb2f9dc4ceaf71d2c63600d49a6a48118bc0b6a533c039048f |
|
MD5 | eddd92b8710e0497f85f66ce68306e12 |
|
BLAKE2b-256 | 86f03946c1c7ec4dbacad8585a082d975035fd0ddc3bed4e41aee29ab437385b |
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | 389caaa56bf876c4b55e6d406b86fe6a2dc42f10cc79f5f3987d9f974570a96f |
|
MD5 | a853a9cf5261d36b584ef782d9c93f32 |
|
BLAKE2b-256 | 48300a3a49e0bfa44f051561d4550126256842391e0f2361fee19cc12564b785 |