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

```

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

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

```

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

### 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)
```

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

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

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

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

```

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

### 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]+'])
```

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

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

```

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

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

```

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

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

```

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

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

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

### 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)
```

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

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

```

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

### 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)
```

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

### 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)
```

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

### Run msbuddy on a single USI string

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

Process a single USI string with msbuddy. The output folder is required for USI strings.

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

```

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

### Run msbuddy on CSV file with FTICR and parallel processing

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

Annotate formulas from a CSV file containing USI strings (one per line, first column; optional adducts in second column). Uses FTICR MS data and parallel processing with 12 CPUs.

```bash
msbuddy -csv <csv_file> -output <output_folder> -ms fticr -p -n_cpu 12
```

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

### Load USI strings with load_usi()

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

Shows how to load a single USI, a list of USIs, and USIs with adducts into a Msbuddy object. The USI string is used as the unique identifier. The adduct_list is optional and applied to all USI strings accordingly.

```python
from msbuddy import Msbuddy

# instantiate a Msbuddy object
engine = Msbuddy()

# load a single USI
engine.load_usi('mzspec:GNPS:GNPS-LIBRARY:accession:CCMSLIB00003740036')

# load a list of USIs
engine.load_usi(['mzspec:GNPS:GNPS-LIBRARY:accession:CCMSLIB00003740036',
                 'mzspec:GNPS:GNPS-LIBRARY:accession:CCMSLIB00000845027'])

# load USIs with adducts
engine.load_usi(usi_list=['mzspec:GNPS:GNPS-LIBRARY:accession:CCMSLIB00003740036',
                          'mzspec:GNPS:GNPS-LIBRARY:accession:CCMSLIB00000845027'],
                adduct_list=['[M+H]+', '[M-H2O+H]+'])
```

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

### Custom data import with MS1 isotope pattern and MS/MS

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

Shows a more complicated custom import with both MS1 isotope pattern and MS/MS, and optionally specifying the adduct type. The identifier, mz, and charge are required; adduct, ms1, and ms2 are optional.

```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 for MS1 isotope pattern
ms1_spec = Spectrum(mz_array = np.array([400, 401, 402]),
                    int_array = np.array([100, 20, 5]))

# create a Spectrum object for MS/MS
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,
                          mz = 400.00,
                          charge = 1,
                          adduct = '[M+H]+',
                          ms1 = ms1_spec,
                          ms2 = ms2_spec)

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

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

### Custom Data Import

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

Custom data import using MetaFeature and Spectrum classes.

```APIDOC
## Custom Data Import with MetaFeature and Spectrum

### Description
Users can import data from custom data sources using the `msbuddy.base.MetaFeature` class and the `msbuddy.base.Spectrum` class. The `identifier`, `mz` and `charge` attributes are required; attributes `rt`, `ms1` and `ms2` are optional. If they are not provided, `None` will be assigned.

### Method
Custom Data Import

### Parameters
- **identifier** (int) - Required - Unique identifier for the MetaFeature object.
- **mz** (float) - Required - Precursor m/z.
- **charge** (int) - Required - Precursor charge.
- **rt** (float or None) - Optional - Retention time, can be None if not available.
- **adduct** (str) - Optional - Adduct type, e.g., '[M+H]+'.
- **ms1** (Spectrum) - Optional - Spectrum object for MS1 isotope pattern.
- **ms2** (Spectrum) - Optional - Spectrum object for MS/MS.

### Example Usage
```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])
```

### Example Usage with MS1 and MS/MS
```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 for MS1 isotope pattern
ms1_spec = Spectrum(mz_array = np.array([400, 401, 402]),
                    int_array = np.array([100, 20, 5]))

# create a Spectrum object for MS/MS
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,
                          mz = 400.00,
                          charge = 1,
                          adduct = '[M+H]+',
                          ms1 = ms1_spec,
                          ms2 = ms2_spec)

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

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

### Retrieve annotation result summary with get_summary()

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

Use msb_engine.get_summary() to retrieve the result summary containing the top 5 formulas after annotation.

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

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

### Msbuddy class

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

The Msbuddy class is the main entry point for the msbuddy package. It is a singleton class that manages data loading, formula annotation, and result summarization.

```APIDOC
## Msbuddy class

### Description
The Msbuddy class is the main class for the msbuddy package. It is a singleton, meaning only one instance can be created. It provides methods to load data from USI strings or MGF files, add custom data, clear data, update configuration, annotate formulas, and get summaries.

### Constructor
`Msbuddy(config: MsbuddyConfig | None = None)`

#### Parameters
- **config** (MsbuddyConfig, optional) - Configuration object for the Msbuddy instance. Default is None.

### Attributes
- **config** (MsbuddyConfig) - The configuration object.
- **data** (List[MetaFeature]) - List of loaded data objects.
- **db_loaded** (bool) - True if the database is loaded.

### Methods

#### update_config(config: **kwargs)
Update the configuration for the Msbuddy object.

##### Parameters
- **config** (**kwargs) - Attributes of MsbuddyConfig to update.

##### Returns
None. The `config` attribute is updated.

#### load_usi(usi_list: str | List[str], adduct_list: None | str | List[str] = None)
Load data from USI strings.

##### Parameters
- **usi_list** (str or List[str]) - A single USI string or a list of USI strings.
- **adduct_list** (optional, str or List[str]) - Adduct string(s) to apply to the USI strings.

##### Returns
None. Data is stored in the `data` attribute.

#### load_mgf(mgf_file: str)
Load data from an MGF file.

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

##### Returns
None. Data is stored in the `data` attribute.

#### add_data(data: List[MetaFeature])
Add custom data to the Msbuddy object.

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

##### Returns
None. Data is stored in the `data` attribute.

#### clear_data()
Clear the `data` attribute.

##### Returns
None. The `data` attribute is set to None.

#### annotate_formula()
Perform formula annotation on loaded data.

##### Returns
None. Updates the `candidate_formula_list` attribute of each MetaFeature.

#### get_summary()
Summarize annotation results.

##### Returns
List of dictionaries, each containing summary information for a single MetaFeature.

### 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)
```
```

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

### Run msbuddy on a CSV file

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

Process a CSV file with msbuddy. The output folder is optional; if omitted, results are written to the default folder './msbuddy_output'.

```bash
msbuddy -ms <ms_instr> -csv <csv_file>

```

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

### Create a Spectrum object from m/z and intensity arrays

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

Constructs a Spectrum object from numpy arrays of m/z values and intensities. The Spectrum class requires mz_array and int_array as numpy arrays.

```python
import numpy as np
from msbuddy.base import Spectrum

mz_array = np.array([100, 200, 300, 400, 500])
int_array = np.array([10, 20, 30, 40, 50])
spectrum = Spectrum(mz_array, int_array)

```

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

### Override mass tolerance with MsbuddyConfig

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

Shows how to set custom mass tolerance values using ppm, ms1_tol, and ms2_tol parameters. This overrides the default tolerances for the selected MS instrument.

```python
msb_config = MsbuddyConfig(ppm=True, ms1_tol=10, ms2_tol=10)
```

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

### load_usi

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

Loads data from USI strings into the Msbuddy object.

```APIDOC
## load_usi(usi_list, adduct_list=None)

### Description
Read from a single USI string or a sequence of USI strings, and load the data into the `data` attribute of the `msbuddy.Msbuddy` object. The USI string will be used as the unique identifier in msbuddy.

### Method
load_usi

### Parameters
- **usi_list** (str | List[str]) - Required - A single USI string or a sequence of USI strings.
- **adduct_list** (None | str | List[str]) - Optional - A single adduct string or a sequence of adduct strings, which will be applied to all USI strings accordingly.

### Returns
None. A list of `msbuddy.base.MetaFeature` objects will be stored in the `data` attribute of the `msbuddy.Msbuddy` object.

### Example Usage
```python
from msbuddy import Msbuddy

# instantiate a Msbuddy object
engine = Msbuddy()

# load a single USI
engine.load_usi('mzspec:GNPS:GNPS-LIBRARY:accession:CCMSLIB00003740036')

# load a list of USIs
engine.load_usi(['mzspec:GNPS:GNPS-LIBRARY:accession:CCMSLIB00003740036',
                 'mzspec:GNPS:GNPS-LIBRARY:accession:CCMSLIB00000845027'])

# load USIs with adducts
engine.load_usi(usi_list=['mzspec:GNPS:GNPS-LIBRARY:accession:CCMSLIB00003740036',
                          'mzspec:GNPS:GNPS-LIBRARY:accession:CCMSLIB00000845027'],
                adduct_list=['[M+H]+', '[M-H2O+H]+'])
```
```

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

### MS2Explanation

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

A class to represent MS/MS explanation. It stores the indices of the fragments and the explanations for the fragments.

```APIDOC
## MS2Explanation

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

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

### Parameters
- **idx_array** (numpy array) - Required - The indices of the fragments.
- **explanation_list** (List[Formula | None]) - Required - A list of `msbuddy.base.Formula` objects. The explanations for the fragments.

### Attributes
- **idx_array** (numpy array) - A numpy array of the indices of the fragments being explained.
- **explanation_list** (List[Formula | None]) - A list of `msbuddy.base.Formula` objects. The explanations for the fragments.
```

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

### load_mgf

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

Loads data from an MGF file into the Msbuddy object.

```APIDOC
## load_mgf(mgf_file)

### Description
Read a single mgf file, and load the data into the `data` attribute of the `msbuddy.Msbuddy` object. In mgf files, the field `TITLE`, `SPECTRUMID` or `SPECTRUM_ID` will be used as the unique identifier in msbuddy. Please include one of these fields in the mgf file.

### Method
load_mgf

### Parameters
- **mgf_file** (str) - Required - The path to the mgf file.

### Returns
None. A list of `msbuddy.base.MetaFeature` objects will be stored in the `data` attribute of the `msbuddy.Msbuddy` object.

### Example Usage
```python
from msbuddy import Msbuddy

# instantiate a Msbuddy object
engine = Msbuddy()

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

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

### Iterate over all candidate formulas for each MetaFeature

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

Iterate through msb_engine.data to access each MetaFeature and its candidate_formula_list, printing m/z, retention time, rank, formula, and estimated FDR.

```python
# retrieve all the annotation results for each metabolic feature
for meta_feature in msb_engine.data:
    for i, candidate in enumerate(meta_feature.candidate_formula_list):
        print('MetaFeature mz' + str(meta_feature.mz) + '  rt: ' + str(meta_feature.rt) + \
        '  rank: ' + str(i+1) + 'Formula: ' + candidate.formula.__str__() + \
        '  estimated FDR: ' + str(candidate.estimated_fdr))
```

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

### MsbuddyConfig class

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

The MsbuddyConfig class stores all configuration options for the msbuddy package.

```APIDOC
## MsbuddyConfig class

### Description
The MsbuddyConfig class is used to store configuration parameters for the msbuddy package. It is passed to the Msbuddy constructor or updated via the `update_config` method.

### Constructor
`MsbuddyConfig(ms_instr: str = None, ppm: bool = True, ms1_tol: float = 5, ms2_tol: float = 10, halogen: bool = False, parallel: bool = False, n_cpu: int = -1, timeout_secs: float = 300, batch_size: int = 1000, c_range: Tuple[int, int] = (0, 80), h_range: Tuple[int, int] = (0, 150), n_range: Tuple[int, int] = (0, 20), o_range: Tuple[int, int] = (0, 30), p_range: Tuple[int, int] = (0, 10), s_range: Tuple[int, int] = (0, 15), f_range: Tuple[int, int] = (0, 20), cl_range: Tuple[int, int] = (0, 15), br_range: Tuple[int, int] = (0, 10), i_range: Tuple[int, int] = (0, 10), isotope_bin_mztol: float = 0.02, max_isotope_cnt: int = 4, rel_int_denoise_cutoff: float = 0.01, top_n_per_50_da: int = 6)`

#### Parameters
- **ms_instr** (str, optional) - Mass spectrometer instrument type.
- **ppm** (bool, optional) - Use ppm for mass tolerance. Default True.
- **ms1_tol** (float, optional) - MS1 tolerance. Default 5.
- **ms2_tol** (float, optional) - MS2 tolerance. Default 10.
- **halogen** (bool, optional) - Enable halogen detection. Default False.
- **parallel** (bool, optional) - Enable parallel processing. Default False.
- **n_cpu** (int, optional) - Number of CPUs. Default -1 (all).
- **timeout_secs** (float, optional) - Timeout in seconds. Default 300.
- **batch_size** (int, optional) - Batch size. Default 1000.
- **c_range** (Tuple[int, int], optional) - Carbon range. Default (0, 80).
- **h_range** (Tuple[int, int], optional) - Hydrogen range. Default (0, 150).
- **n_range** (Tuple[int, int], optional) - Nitrogen range. Default (0, 20).
- **o_range** (Tuple[int, int], optional) - Oxygen range. Default (0, 30).
- **p_range** (Tuple[int, int], optional) - Phosphorus range. Default (0, 10).
- **s_range** (Tuple[int, int], optional) - Sulfur range. Default (0, 15).
- **f_range** (Tuple[int, int], optional) - Fluorine range. Default (0, 20).
- **cl_range** (Tuple[int, int], optional) - Chlorine range. Default (0, 15).
- **br_range** (Tuple[int, int], optional) - Bromine range. Default (0, 10).
- **i_range** (Tuple[int, int], optional) - Iodine range. Default (0, 10).
- **isotope_bin_mztol** (float, optional) - Isotope bin m/z tolerance. Default 0.02.
- **max_isotope_cnt** (int, optional) - Maximum isotope count. Default 4.
- **rel_int_denoise_cutoff** (float, optional) - Relative intensity denoise cutoff. Default 0.01.
- **top_n_per_50_da** (int, optional) - Top N peaks per 50 Da. Default 6.
```

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

### msbuddy.base.Formula

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

Class representing a molecular formula with attributes for the formula array, charge, exact mass, isotopologue, and double bond equivalent.

```APIDOC
## msbuddy.base.Formula

### Description
A class to represent a molecular formula.

### Constructor
`Formula(array: np.array, charge: int, mass: Union[float, None] = None, isotope: int = 0)`

### Parameters
- **array** (np.array) - Required - The molecular formula array in the format of [C, H, Br, Cl, F, I, K, N, Na, O, P, S].
- **charge** (int) - Required - The charge of the molecular formula.
- **mass** (Union[float, None]) - Optional - The exact mass of the molecular formula. Default is None, exact mass will be calculated.
- **isotope** (int) - Optional - The isotopologue of the formula (e.g., 1 for M+1). Default is 0, which means M+0.

### Attributes
- **array** - A numpy array of the molecular formula array.
- **charge** - int. The charge of the molecular formula.
- **mass** - float. The exact mass of the molecular formula.
- **isotope** - int. The isotopologue of the formula.
- **dbe** - float. The double bond equivalent (DBE) of the formula.
```

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

### Msbuddy.clear_data

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

Clears the data attribute of the Msbuddy object.

```APIDOC
## Msbuddy.clear_data

### Description
Clears the data attribute of the Msbuddy object.

### Method
clear_data

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Request Example
```python
engine.clear_data()
```

### Response
#### Success Response (200)
- None

#### Response Example
```python
None
```
```