BayFlux

This is an open source software library for performing Bayesian genome scale 13C Metabolic Flux Analysis (Bayesian 13C MFA), and can also be used for Two Scale Metabolic Flux Analysis (2S-13C MFA) with the optional Limit Flux to Core add-on package (https://github.com/JBEI/limitfluxtocore).

BayFlux requires the use of third-party software COBRApy, which uses a GNU GPL v2.0 license and will need to download separately to be used in conjunction with this BayFlux v1.0 software, which happens automatically during the installation described below. BayFlux leverages COBRApy for handling linear optimization and parsing of genome scale models. At this time, you must use the Bayesian Sampler fork of COBRApy: https://github.com/TylerBackman/cobrapy/releases/tag/bayesianSampler-0.3

Installing prerequisites

To run the Jupyter notebook version of bayflux on a personal computer you must install Git to clone the source code, and install Docker to run the Jupyter server. Download and install the following applications:

• Git https://git-scm.com
• Docker Desktop https://www.docker.com/products/docker-desktop

Cloning the repository

You must cd into a directory you would like to install bayflux into, and then clone the repo as follows:

git clone https://github.com/JBEI/bayflux.git

You can the enter the source code folder:

cd bayflux

Note: If you are running on MacOS, you must grant Docker permission to access your files, when prompted. If you fail to do so, you can grant this later by going to System Preferences -> Security & Privacy -> Privacy -> Files and Folders -> Check the boxes below 'Docker'

Using bayflux and running test notebooks inside Docker

This will launch a Jupyter notebook server with bayflux pre-installed. Just copy and paste the url into the browser, and open the notebooks folder to start using the demo notebooks.

docker compose up

Documentation

You can access the Python documentation for all BayFlux functions at https://bayflux.readthedocs.io/en/latest/py-modindex.html

Suggested demo notebooks

The notebooks folder contains four demo notebooks for testing, and learning about bayflux. These are:

• Fig3Toy_Create_Model.ipynb This notebook demonstrates setting up the four input files necessary for a bayflux run, by using the simple newtwork from the first example in Antoniewicz 2006 (https://www.ncbi.nlm.nih.gov/pubmed/17088092). We maintain this as a template which can be used for your own project.
• MCMC_Fig3Toy_Sample_Model.ipynb This notebook demonstrates MCMC Bayesian inference, by using the simple newtwork from the first example in Antoniewicz 2006 (https://www.ncbi.nlm.nih.gov/pubmed/17088092). We maintain this as a template which can be used for your own project. It pulls input files generated by the Fig3Toy_Create_Model.ipynb notebook.
• imEco726_genome_scale.ipynb This notebook demonstrates MCMC Bayesian inference with a full genome scale E. coli model using reactions from iAF1260 and atom transitions from imEco726. The demo data here is wt5h data from Toya 2010 (https://www.ncbi.nlm.nih.gov/pubmed/20730757).
• EMU_Fig3toyModel_demo.ipynb This notebook summarizes the matrix computation steps for estimating mass isotopomer distributions from flux vectors. Specifically, this notebook reproduces the first example in Antoniewicz 2006 using the bayflux EMU simulator functions. This demonstrates the internal workings of BayFlux, but isn't essential for understanding or using BayFlux.
• analyze_command_line_output.ipynb This notebook will parse and analyze the output of a command line parallel processing BayFlux run. See the section of this readme "Using the MPI command line version of BayFlux" under the heading "For advanced users" to see how to setup and run BayFlux in this way.

Shutting down the Docker container

docker compose stop

For advanced users

Accessing a shell inside the Docker container

docker exec -it bayflux-jupyter-1 /bin/bash

Using the MPI command line version of BayFlux

This is a higher performance way to access of BayFlux in parallel. For test purposes it can be run from the command line inside the Docker container. Note that you must specify the number of mpi instances, and must specify a .yaml settings file describing your run. Some example files for a simple run are provided in the folder command_line_example.

cd command_line_example
mpirun -n 4 bayflux example_config.yaml

Installing as a Python package

pip install -vvv -e ./

Running unit tests

Run while docker container is up as described above DO NOT COMMIT CODE WITHOUT 100% COVERAGE

docker exec -it bayflux_jupyter_1 pytest tests --cov=bayflux --cov-report term-missing

Build Sphinx documentation located in docs/_build/html/index.html

Please use Google style docstrings: http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html

cd docs
make html

Adding a new module to docs/index.rst

.. automodule:: bayflux.<new_module_name_here>
   :members:

Rebuilding docker container and uploading to Docker hub

Run anytime the Dockerfile is updated (note the last two commands are for bayflux developers only, but anyone can run the first to build the container locally)

docker build --no-cache --platform=linux/amd64 -t tbackman/bayflux:1 .
docker login
docker push tbackman/bayflux:1

Benchmarking EMU computation performance in a Jupyter notebook

The following code is an example of line profiling the bayflux.simulateLabeling function

%load_ext line_profiler
def simulateLabeling(times):
    for n in range(0, times):
        bayflux.simulateLabeling(compiledData, fluxes, substrateLabelingDict)
%lprun -f bayflux.simulateLabeling simulateLabeling(10000)

Copyright Notice

BayFlux Copyright (c) 2023, The Regents of the University of California, through Lawrence Berkeley National Laboratory (subject to receipt of any required approvals from the U.S. Dept. of Energy) and Basque Center of Applied Mathematics. All rights reserved.

If you have questions about your rights to use or distribute this software, please contact Berkeley Lab's Intellectual Property Office at [email protected].

NOTICE. This Software was developed under funding from the U.S. Department of Energy and the U.S. Government consequently retains certain rights. As such, the U.S. Government has been granted for itself and others acting on its behalf a paid-up, nonexclusive, irrevocable, worldwide license in the Software to reproduce, distribute copies to the public, prepare derivative works, and perform publicly and display publicly, and to permit others to do so.

License Agreement

See license.txt

Citing BayFlux

DOI: https://doi.org/10.1371/journal.pcbi.1011111

BibTex citation:

@article{backman2023bayflux, title={BayFlux: A Bayesian method to quantify metabolic Fluxes and their uncertainty at the genome scale}, author={Backman, Tyler WH and Schenk, Christina and Radivojevic, Tijana and Ando, David and Singh, Jahnavi and Czajka, Jeffrey J and Costello, Zak and Keasling, Jay D and Tang, Yinjie and Akhmatskaya, Elena and others}, journal={PLOS Computational Biology}, volume={19}, number={11}, pages={e1011111}, year={2023}, publisher={Public Library of Science San Francisco, CA USA} }