msbuddy

https://msbuddy.readthedocs.io/en/latest/
Admin
msbuddy is a Python tool for molecular formula annotation and candidate space shrinkage in mass...
Tokens:27,367
Snippets:172
Trust Score:9.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### MsbuddyConfig example usage

Source: https://msbuddy.readthedocs.io/en/latest/_sources/pyapi.rst.txt

Shows how to create a MsbuddyConfig object with custom settings and pass it to a Msbuddy instance.

```python
from msbuddy import Msbuddy, MsbuddyConfig

# create a MsbuddyConfig object
msb_config = MsbuddyConfig(
    ms_instr="orbitrap",
    halogen=True,
    timeout_secs=100)

# create a Msuddy object with the specified configuration
msb_engine = Msbuddy(msb_config)
```

--------------------------------

### Install msbuddy with pip

Source: https://msbuddy.readthedocs.io/en/latest/cmdapi.html

Install the msbuddy package using pip. This is required before using the command-line interface.

```bash
pip install msbuddy

```

--------------------------------

### Example usage of Msbuddy class

Source: https://msbuddy.readthedocs.io/en/latest/pyapi.html

Shows how to create a Msbuddy object with default configuration, load data from an MGF file, add custom data, clear data, and update configuration with custom parameters.

```python
from msbuddy import Msbuddy

# create a Msbuddy object with default configuration
engine = Msbuddy()

# load some data here
engine.load_mgf("demo.mgf")
# add custom data (List[MetaFeature])
engine.add_data(...)

# clear data
engine.clear_data()

# update configuration
engine.update_config(ms_instr="fticr", halogen=True, timeout_secs=100)
```

--------------------------------

### Install lightgbm dependency

Source: https://msbuddy.readthedocs.io/en/latest/_sources/install.rst.txt

Installs the lightgbm package, required for formula annotation.

```bash
pip install lightgbm
```

--------------------------------

### mass_to_formula example usage

Source: https://msbuddy.readthedocs.io/en/latest/pyapi.html

Example usage of the mass_to_formula function. Creates a Msbuddy object, converts a mass of 300.0000 to a formula with specified parameters, and prints the results.

```python
from msbuddy import Msbuddy

# create a Msbuddy object
engine = Msbuddy()

# convert mass to formula
formula_list = engine.mass_to_formula(300.0000, 10, True, True, 0.0, True)

# print results
for f in formula_list:
   print(f.formula, f.mass_error, f.mass_error_ppm)

```

--------------------------------

### mz_to_formula example usage

Source: https://msbuddy.readthedocs.io/en/latest/pyapi.html

Example usage of the mz_to_formula function. Creates a Msbuddy object, converts an m/z value of 300.0000 with adduct [M+H]+ to a formula, and prints the results.

```python
from msbuddy import Msbuddy

# create a Msbuddy object
engine = Msbuddy()

# convert mz to formula
formula_list = engine.mz_to_formula(300.0000, "[M+H]+", 10, True, True, 0.0, True)

# print results
for f in formula_list:
   print(f.formula, f.mass_error, f.mass_error_ppm)

```

--------------------------------

### Clone msbuddy source repository

Source: https://msbuddy.readthedocs.io/en/latest/_sources/install.rst.txt

Clones the msbuddy repository from GitHub to install from source.

```bash
git clone https://github.com/Philipbear/msbuddy.git
```

--------------------------------

### Basic msbuddy workflow: load mgf, annotate formula, get summary

Source: https://msbuddy.readthedocs.io/en/latest/_sources/quickstart.rst.txt

Loads MS/MS spectra from a mgf file, annotates molecular formulas, and retrieves a summary. Requires a MsbuddyConfig with instrument type (e.g., 'orbitrap'), tolerance settings, and optional halogen. The result is a list of dictionaries with keys like 'identifier', 'mz', 'rt', 'adduct', and formula ranks.

```python
from msbuddy import Msbuddy, MsbuddyConfig

# create 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
                                               # highly recommended to fill in the instrument type
                          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=True,
                          timeout_secs=200)

# instantiate a Msbuddy object with the parameter set
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
results = msb_engine.get_summary()

# print the result, results is a list of dictionaries
for individual_result in results:
    for key, value in individual_result.items():
        print(key, value)
```

--------------------------------

### assign_subformula example

Source: https://msbuddy.readthedocs.io/en/latest/pyapi.html

Assigns subformulas to an MS/MS spectrum given a precursor formula and adduct. Uses a DBE cutoff and applies soft SENIOR rules. The precursor formula must only contain CHNOPSFClBrINaK.

```python
from msbuddy import assign_subformula

subformla_list = assign_subformula([107.05, 149.02, 209.04, 221.04, 230.96],
                                   precursor_formula="C15H16O5", adduct="[M+H]+",
                                   ms2_tol=0.02, ppm=False, dbe_cutoff=0.0)

```

--------------------------------

### Retrieve annotation result summary with msb_engine.get_summary()

Source: https://msbuddy.readthedocs.io/en/latest/dataout.html

Use this snippet to access the top 5 formula annotation results after running msbuddy. It returns the result summary as shown in the Quick Start session.

```python
# retrieve the annotation result summary
results = msb_engine.get_summary()

```

--------------------------------

### Msbuddy

Source: https://msbuddy.readthedocs.io/en/latest/_sources/pyapi.rst.txt

The Msbuddy class is the main entry point for formula annotation. It provides methods to load data, add custom data, clear data, update configuration, perform formula annotation, and get summaries.

```APIDOC
## Msbuddy

### Description
The Msbuddy class is the main entry point for formula annotation. It provides methods to load data, add custom data, clear data, update configuration, perform formula annotation, and get summaries.

### Methods

#### load_mgf

##### Description
Loads data from an MGF file.

##### Parameters
- **file_path** (str) - Required - Path to the MGF file.

##### Returns
None

#### add_data

##### Description
Adds custom data as a list of MetaFeature objects.

##### Parameters
- **data** (List[MetaFeature]) - Required - List of MetaFeature objects to add.

##### Returns
None

#### clear_data

##### Description
Clears all loaded data.

##### Returns
None

#### update_config

##### Description
Updates the configuration of the Msbuddy object.

##### Parameters
- **ms_instr** (str) - Optional - Mass spectrometry instrument type.
- **halogen** (bool) - Optional - Whether to consider halogen elements.
- **timeout_secs** (float) - Optional - Timeout in seconds for each query.

##### Returns
None

#### annotate_formula

##### Description
Performs formula annotation for loaded data.

##### Returns
None. The candidate_formula_list attribute of each MetaFeature object in the data attribute will be updated.

#### get_summary

##### Description
Summarizes the annotation results.

##### Returns
A list of Python dictionaries. Each dictionary contains summary information for a single MetaFeature object.

### Example Usage

```python
from msbuddy import Msbuddy

# create a Msbuddy object with default configuration
engine = Msbuddy()

# load some data here
engine.load_mgf("demo.mgf")
# add custom data (List[MetaFeature])
engine.add_data(...)

# clear data
engine.clear_data()

# update configuration
engine.update_config(ms_instr="fticr", halogen=True, timeout_secs=100)
```
```

--------------------------------

### Enable parallel computing with CPU count

Source: https://msbuddy.readthedocs.io/en/latest/_sources/quickstart.rst.txt

Enables parallel computing by setting parallel=True and n_cpu. Must be run inside an if __name__ == '__main__': block. The example shows the required structure; other code remains the same.

```python
if __name__ == '__main__':
    from msbuddy import Msbuddy, MsbuddyConfig
    # create a MsbuddyConfig object
    msb_config = MsbuddyConfig(ms_instr="orbitrap", # supported: "qtof", "orbitrap" and "fticr"
                                                    # highly recommended to fill in the instrument type
                               halogen=True,
                               parallel=True, # enable parallel computing
                               n_cpu=12) # number of CPUs to be used
    ...(other code remains the same)
```

--------------------------------

### Load MGF, annotate formulas, and print summary

Source: https://msbuddy.readthedocs.io/en/latest/quickstart.html

Creates a MsbuddyConfig with orbitrap instrument, ppm tolerances, halogen enabled, and a 200-second timeout. Instantiates Msbuddy, loads an MGF file, annotates formulas, and prints the summary dictionary keys and values. The result summary contains keys such as identifier, mz, rt, adduct, formula_rank_1 through formula_rank_5, and estimated_fdr.

```python
from msbuddy import Msbuddy, MsbuddyConfig

# create 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
                                                # highly recommended to fill in the instrument type
                           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=True,
                           timeout_secs=200)

# instantiate a Msbuddy object with the parameter set
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
results = msb_engine.get_summary()

# print the result, results is a list of dictionaries
for individual_result in results:
    for key, value in individual_result.items():
        print(key, value)
```

--------------------------------

### Create MsbuddyConfig and Msbuddy objects

Source: https://msbuddy.readthedocs.io/en/latest/pyapi.html

Shows how to instantiate MsbuddyConfig with custom parameters (ms_instr, halogen, timeout_secs) and then create a Msbuddy engine with that configuration. The MsbuddyConfig constructor accepts many optional parameters; defaults are used for unspecified ones.

```python
from msbuddy import Msbuddy, MsbuddyConfig

# create a MsbuddyConfig object
msb_config = MsbuddyConfig(
    ms_instr="orbitrap",
    halogen=True,
    timeout_secs=100)

# create a Msuddy object with the specified configuration
msb_engine = Msbuddy(msb_config)

```

--------------------------------

### Create MsbuddyConfig and Msbuddy objects

Source: https://msbuddy.readthedocs.io/en/latest/_sources/config.rst.txt

Shows how to instantiate MsbuddyConfig with common parameters and pass it to Msbuddy. Parallel processing is available by setting parallel=True and n_cpu, but must be run in an if __name__ == '__main__': block. The ms_instr parameter is highly recommended for best performance.

```python
from msbuddy import Msbuddy, MsbuddyConfig

# create a config object
msb_config = MsbuddyConfig(
    ms_instr='orbitrap', # highly recommended to fill for the best annotation performance
                         # supported MS types: "qtof", "orbitrap" and "fticr"
    ppm=True, # use ppm for mass tolerance, otherwise use Da
    ms1_tol=5, # ms1 tolerance, see below for default values for each MS instrument
    ms2_tol=10, # ms2 tolerance, see below for default values for each MS instrument
    halogen=True, # enable halogen atoms in molecular formula annotation
    # parallel=True, # enable parallel processing, see note below
    # n_cpu=12, # number of CPUs to use
    timeout_secs=600, # timeout for each query in seconds
    batch_size=1000, # number of queries to process in each batch, a larger batch size will use more memory but will be faster
    c_range=(0, 100), # range of carbon numbers to consider
    h_range=(0, 150), # range of hydrogen numbers to consider
    ... # other parameters
    )

# create a Msbuddy object with the specified configuration
msb_engine = Msbuddy(msb_config)
```

--------------------------------

### Show msbuddy help

Source: https://msbuddy.readthedocs.io/en/latest/cmdapi.html

Display all available options for the msbuddy command-line interface. The -h option is equivalent to --help.

```bash
msbuddy --help

```

--------------------------------

### add_formula_str example

Source: https://msbuddy.readthedocs.io/en/latest/pyapi.html

Adds two formula strings and returns a dictionary of the summed molecular formula.

```python
from msbuddy.utils import add_formula_str

formula_dict = add_formula_str("C6H12O5", "H2O")
print(formula_dict)

```

--------------------------------

### Run msbuddy on a single USI string with QTOF

Source: https://msbuddy.readthedocs.io/en/latest/_sources/cmdapi.rst.txt

Annotate a single USI string from QTOF instruments. The output folder is required for USI input.

```bash
msbuddy -usi <usi_string> -output <output_folder> -ms qtof
```

--------------------------------

### Extract msbuddy PyPI release tarball

Source: https://msbuddy.readthedocs.io/en/latest/_sources/install.rst.txt

Downloads and extracts the msbuddy release tarball from PyPI for installation.

```bash
tar -zxvf msbuddy-0.3.0.tar.gz
```

--------------------------------

### Configure custom data directory

Source: https://msbuddy.readthedocs.io/en/latest/_sources/install.rst.txt

Creates an MsbuddyConfig with a custom data directory and initializes the Msbuddy engine.

```python
from msbuddy import Msbuddy, MsbuddyConfig

config = MsbuddyConfig(data_dir="~/msbuddy-data")
engine = Msbuddy(config)
```

--------------------------------

### read_formula_str example

Source: https://msbuddy.readthedocs.io/en/latest/pyapi.html

Reads a formula string and returns a dictionary. Handles cases such as "2H2O" and "C5H7NO2.HCl".

```python
from msbuddy.utils import read_formula_str

formula_dict = read_formula_str("2H2O")
print(formula_dict)

```

--------------------------------

### enumerate_subform_arr example

Source: https://msbuddy.readthedocs.io/en/latest/pyapi.html

Enumerates all possible sub-formula arrays of a given formula array. The input is a list-like object or 1D numpy array of the molecular formula array.

```python
from msbuddy.utils import enumerate_subform_arr

all_subform_arr = enumerate_subform_arr([10, 20, 0, 0, 0, 0, 0, 0, 0, 5, 0, 0])
print(all_subform_arr)

```

--------------------------------

### Run msbuddy with detailed output and halogen consideration

Source: https://msbuddy.readthedocs.io/en/latest/cmdapi.html

Process an MGF file from Orbitrap with parallel processing, detailed results, and halogen atoms (FClBrI) considered. The -d option writes all candidate formulas and scores.

```bash
msbuddy -mgf <mgf_file> -output <output_folder> -ms orbitrap -p -n_cpu 12 -d -hal

```

--------------------------------

### form_arr_to_str example

Source: https://msbuddy.readthedocs.io/en/latest/pyapi.html

Converts a neutral formula array to a Hill string. The array format is [C, H, Br, Cl, F, I, K, N, Na, O, P, S].

```python
from msbuddy.utils import form_arr_to_str

formula_str = form_arr_to_str([10, 20, 0, 0, 0, 0, 0, 0, 0, 5, 0, 0])
print(formula_str)

```

--------------------------------

### Download data and run msbuddy with custom options

Source: https://msbuddy.readthedocs.io/en/latest/_sources/install.rst.txt

Downloads data and runs msbuddy with custom data directory, formula database, and machine learning model.

```bash
msbuddy --download-data --data-dir ~/msbuddy-data
msbuddy --mgf input.mgf --data-dir ~/msbuddy-data \
    --formula-db formula-custom.joblib \
    --ml-model /shared/msbuddy/model-custom.joblib
```

--------------------------------

### Custom data import with MetaFeature and Spectrum (MS/MS only)

Source: https://msbuddy.readthedocs.io/en/latest/datain.html

Shows how to import a custom MS/MS spectrum using MetaFeature and Spectrum classes. The identifier, mz, and charge attributes are required; rt, ms1, and ms2 are optional and default to None.

```python
from msbuddy import Msbuddy
from msbuddy.base import MetaFeature, Spectrum
import numpy as np

# instantiate a Msbuddy object
engine = Msbuddy()

# create a Spectrum object
ms2_spec = Spectrum(mz_array = np.array([100, 200, 300]),
                    int_array = np.array([1, 2, 3]))

# create a MetaFeature object
metafeature = MetaFeature(identifier = 0,  # unique identifier for the MetaFeature object
                          mz = 400.00,  # precursor m/z
                          rt = None,  # retention time, can be None if not available
                          charge = 1,  # precursor charge
                          ms2 = ms2_spec)

# add to the Msbuddy object, List[MetaFeature] is accepted
engine.add_data([metafeature])
```

--------------------------------

### Convert mass to formula with Msbuddy.mass_to_formula

Source: https://msbuddy.readthedocs.io/en/latest/_sources/pyapi.rst.txt

Shows how to instantiate Msbuddy and call mass_to_formula with positional arguments (mass, mass_tol, ppm, halogen, dbe_cutoff, integer_dbe). The returned FormulaResult objects expose formula, mass_error, and mass_error_ppm attributes.

```python
from msbuddy import Msbuddy

# create a Msbuddy object
engine = Msbuddy()

# convert mass to formula
formula_list = engine.mass_to_formula(300.0000, 10, True, True, 0.0, True)

# print results
for f in formula_list:
   print(f.formula, f.mass_error, f.mass_error_ppm)
```

--------------------------------

### Convert m/z to formula with Msbuddy.mz_to_formula

Source: https://msbuddy.readthedocs.io/en/latest/_sources/pyapi.rst.txt

Shows how to call mz_to_formula with an adduct string like "[M+H]+" and the same tolerance/halogen/DBE parameters as mass_to_formula. Results are sorted by absolute mass error and printed via the same FormulaResult attributes.

```python
from msbuddy import Msbuddy

# create a Msbuddy object
engine = Msbuddy()

# convert mz to formula
formula_list = engine.mz_to_formula(300.0000, "[M+H]+", 10, True, True, 0.0, True)

# print results
for f in formula_list:
   print(f.formula, f.mass_error, f.mass_error_ppm)
```

--------------------------------

### Load MS/MS spectra via USIs with optional adducts

Source: https://msbuddy.readthedocs.io/en/latest/_sources/quickstart.rst.txt

Loads MS/MS spectra from USIs. Multiple USIs can be loaded at once. If adducts are not specified, default adducts ([M+H]+, [M-H]-) are used. The example shows loading two USIs with specified adducts.

```python
# you can load multiple USIs at once
msb_engine.load_usi(['mzspec:GNPS:GNPS-LIBRARY:accession:CCMSLIB00003740036',
                     'mzspec:GNPS:GNPS-LIBRARY:accession:CCMSLIB00003740037'])

# load USIs with adducts specified, otherwise the default adducts ([M+H]+, [M-H]-) will be used
msb_engine.load_usi(usi_list=['mzspec:GNPS:GNPS-LIBRARY:accession:CCMSLIB00003740036',
                              'mzspec:GNPS:GNPS-LIBRARY:accession:CCMSLIB00000845027'],
                    adduct_list=['[M+H]+', '[M-H2O]+'])
```

--------------------------------

### read_formula example

Source: https://msbuddy.readthedocs.io/en/latest/pyapi.html

Reads a neutral formula string and returns a numpy array in the order [C, H, Br, Cl, F, I, K, N, Na, O, P, S]. Returns None if the formula is invalid. For a more general approach without element restriction, use msbuddy.utils.read_formula_str().

```python
from msbuddy.utils import read_formula

formula_array = read_formula("C10H20O5")
print(formula_array)

```

--------------------------------

### msbuddy.base.MS2Explanation

Source: https://msbuddy.readthedocs.io/en/latest/_sources/pyapi.rst.txt

Class representing MS/MS explanation, with attributes for index array and explanation array.

```APIDOC
## msbuddy.base.MS2Explanation

### Description
A class to represent MS/MS explanation.

### Constructor
`MS2Explanation(idx_array: np.array, explanation_array: List[Union[Formula, None]])`

### Parameters
- **idx_array** (np.array) - Required - Index array for the explanation.
- **explanation_array** (List[Union[Formula, None]]) - Required - List of Formula objects or None for each fragment.

### Attributes
- **idx_array** - np.array. Index array for the explanation.
- **explanation_array** - List[Union[Formula, None]]. List of Formula objects or None for each fragment.
```

--------------------------------

### Load MGF file with load_mgf()

Source: https://msbuddy.readthedocs.io/en/latest/datain.html

Shows how to load a single MGF file into a Msbuddy object. The MGF file must include one of the fields TITLE, SPECTRUMID, or SPECTRUM_ID to be used as the unique identifier.

```python
from msbuddy import Msbuddy

# instantiate a Msbuddy object
engine = Msbuddy()

# load a single mgf file
engine.load_mgf('input_file.mgf')
```

--------------------------------

### Run msbuddy on an MGF file with parallel processing

Source: https://msbuddy.readthedocs.io/en/latest/cmdapi.html

Process an MGF file from Orbitrap instruments with 12 parallel processes. Results are written as a TSV file in the specified output folder.

```bash
msbuddy -mgf <mgf_file> -output <output_folder> -ms orbitrap -p -n_cpu 12

```

--------------------------------

### Configure custom data files

Source: https://msbuddy.readthedocs.io/en/latest/_sources/install.rst.txt

Configures custom data file paths for formula_db and ml_model in MsbuddyConfig.

```python
config = MsbuddyConfig(
    data_dir="~/msbuddy-data",
    data_files={
        "formula_db": "formula-custom.joblib",
        "ml_model": "/shared/msbuddy/model-custom.joblib",
    },
)
```

--------------------------------

### Load spectra via USIs with optional adducts

Source: https://msbuddy.readthedocs.io/en/latest/quickstart.html

Loads multiple MS/MS spectra using USI strings. The first load_usi call uses default adducts ([M+H]+, [M-H]-). The second call specifies adducts for each USI. msbuddy does not perform adduct annotation; adducts must be correctly specified or defaults are used.

```python
# you can load multiple USIs at once
msb_engine.load_usi(['mzspec:GNPS:GNPS-LIBRARY:accession:CCMSLIB00003740036',
                     'mzspec:GNPS:GNPS-LIBRARY:accession:CCMSLIB00003740037'])

# load USIs with adducts specified, otherwise the default adducts ([M+H]+, [M-H]-) will be used
msb_engine.load_usi(usi_list=['mzspec:GNPS:GNPS-LIBRARY:accession:CCMSLIB00003740036',
                              'mzspec:GNPS:GNPS-LIBRARY:accession:CCMSLIB00000845027'],
                    adduct_list=['[M+H]+', '[M-H2O+H]+'])
```

--------------------------------

### Inspect and download data files

Source: https://msbuddy.readthedocs.io/en/latest/_sources/install.rst.txt

Prints the data file paths and downloads all data files in advance.

```python
from msbuddy import download_data, get_data_files

print(get_data_files(config.data_dir, config.data_files))
download_data(config.data_dir, config.data_files)
```
Tokens:
Raw