|
| 1 | +# BayesFlow |
| 2 | + |
| 3 | +BayesFlow is a Python library for simulation-based **Amortized Bayesian Inference** with neural networks. |
| 4 | +It provides users with: |
| 5 | + |
| 6 | +- A user-friendly API for rapid Bayesian workflows |
| 7 | +- A rich collection of neural network architectures |
| 8 | +- Multi-Backend Support via [Keras3](https://keras.io/keras_3/): You can use [PyTorch](https://github.com/pytorch/pytorch), [TensorFlow](https://github.com/tensorflow/tensorflow), or [JAX](https://github.com/google/jax) |
| 9 | + |
| 10 | +BayesFlow is designed to be a flexible and efficient tool that enables rapid statistical inference |
| 11 | +fueled by continuous progress in generative AI and Bayesian inference. |
| 12 | + |
| 13 | +## Conceptual Overview |
| 14 | + |
| 15 | +<div align="center"> |
| 16 | +<picture> |
| 17 | + <source media="(prefers-color-scheme: dark)" srcset="_static/bayesflow_landing_dark.jpg"> |
| 18 | + <source media="(prefers-color-scheme: light)" srcset="_static/bayesflow_landing_light.jpg"> |
| 19 | + <img alt="Overview graphic on using BayesFlow. It is split in three columns: 1. Choose you backend: BayesFlow is based on Keras, so you can choose PyTorch, TensorFlow or JAX. 2. Define your simulator: You specify you simulator in Python, and use it to generate simulated data. 3. Choose your algorithm: You define a generative nerual network, that you can use for estimation after training." src="_static/bayesflow_landing_dark.jpg"> |
| 20 | +</picture> |
| 21 | +</div> |
| 22 | + |
| 23 | +A cornerstone idea of amortized Bayesian inference is to employ generative |
| 24 | +neural networks for parameter estimation, model comparison, and model validation |
| 25 | +when working with intractable simulators whose behavior as a whole is too |
| 26 | +complex to be described analytically. |
| 27 | + |
| 28 | +## Disclaimer |
| 29 | + |
| 30 | +This is the current dev version of BayesFlow, which constitutes a complete refactor of the library built on Keras 3. This way, you can now use any of the major deep learning libraries as backend for BayesFlow. The refactor is still work in progress with some of the advanced features not yet implemented. We are actively working on them and promise to catch up soon. |
| 31 | + |
| 32 | +If you encounter any issues, please don't hesitate to open an issue here on [Github](https://github.com/bayesflow-org/bayesflow/issues) or ask questions on our [Discourse Forums](https://discuss.bayesflow.org/). |
| 33 | + |
| 34 | +## Installation |
| 35 | + |
| 36 | +### Backend |
| 37 | + |
| 38 | +First, install one machine learning backend of choice. Note that BayesFlow **will not run** without a backend. |
| 39 | + |
| 40 | +- [Install JAX](https://jax.readthedocs.io/en/latest/installation.html) |
| 41 | +- [Install PyTorch](https://pytorch.org/get-started/locally/) |
| 42 | +- [Install TensorFlow](https://www.tensorflow.org/install) |
| 43 | + |
| 44 | +If you don't know which backend to use, we recommend JAX to get started. |
| 45 | +It is the fastest backend and already works pretty reliably with the current |
| 46 | +dev version of bayesflow. |
| 47 | + |
| 48 | +Once installed, [set the backend environment variable as required by keras](https://keras.io/getting_started/#configuring-your-backend). For example, inside your Python script write: |
| 49 | + |
| 50 | +```python |
| 51 | +import os |
| 52 | +os.environ["KERAS_BACKEND"] = "jax" |
| 53 | +import bayesflow |
| 54 | +``` |
| 55 | + |
| 56 | +If you use conda, you can alternatively set this individually for each environment in your terminal. For example: |
| 57 | + |
| 58 | +```bash |
| 59 | +conda env config vars set KERAS_BACKEND=jax |
| 60 | +``` |
| 61 | + |
| 62 | +This way, you also don't have to manually set the backend every time you are starting Python to use BayesFlow. |
| 63 | + |
| 64 | +**Caution:** Some people report that the IDE (e.g., VSCode or PyCharm) can silently overwrite environment variables. If you have set your backend as an environment variable and you still get keras-related import errors when loading BayesFlow, these IDE shenanigans might be the culprit. Try setting the keras backend in your Python script via `import os; os.environ["KERAS_BACKEND"] = "<YOUR-BACKEND>"`. |
| 65 | + |
| 66 | +### BayesFlow |
| 67 | + |
| 68 | +You can then install BayesFlow itself using one of the following options: |
| 69 | + |
| 70 | +```{eval-rst} |
| 71 | +.. tab-set:: |
| 72 | +
|
| 73 | + .. tab-item:: Pip |
| 74 | +
|
| 75 | + .. code-block:: bash |
| 76 | +
|
| 77 | + pip install git+https://github.com/bayesflow-org/bayesflow@dev |
| 78 | +
|
| 79 | +
|
| 80 | + .. tab-item:: Conda (coming soon) |
| 81 | +
|
| 82 | + The dev version is not conda-installable yet. |
| 83 | +
|
| 84 | +
|
| 85 | + .. tab-item:: Source |
| 86 | +
|
| 87 | + .. code-block:: bash |
| 88 | +
|
| 89 | + git clone -b dev [email protected]:bayesflow-org/bayesflow.git |
| 90 | + cd <local-path-to-bayesflow-repository> |
| 91 | + conda env create --file environment.yaml --name bayesflow |
| 92 | +
|
| 93 | + This will create a new conda environment. Please activate it and install your preferred backend. |
| 94 | +``` |
| 95 | + |
| 96 | +## Getting Started |
| 97 | + |
| 98 | +To get started, take a look at our [Getting Started Tutorial](_examples/Linear_Regression_Starter.ipynb). |
| 99 | +After that, check out some of our walk-through notebooks in the [Examples](examples) section. |
| 100 | + |
| 101 | +## Getting Help |
| 102 | + |
| 103 | +Please use the [BayesFlow Forums](https://discuss.bayesflow.org/) for any BayesFlow-related questions and discussions, and [GitHub Issues](https://github.com/bayesflow-org/bayesflow/issues) for bug reports and feature requests. |
| 104 | + |
| 105 | +## Citing BayesFlow |
| 106 | + |
| 107 | +You can cite BayesFlow along the lines of: |
| 108 | + |
| 109 | +- We approximated the posterior with neural posterior estimation and learned summary statistics (NPE; Radev et al., 2020), as implemented in the BayesFlow software for amortized Bayesian workflows (Radev et al., 2023a). |
| 110 | +- We approximated the likelihood with neural likelihood estimation (NLE; Papamakarios et al., 2019) without hand-crafted summary statistics, as implemented in the BayesFlow software for amortized Bayesian workflows (Radev et al., 2023b). |
| 111 | +- We performed simultaneous posterior and likelihood estimation with jointly amortized neural approximation (JANA; Radev et al., 2023a), as implemented in the BayesFlow software for amortized Bayesian workflows (Radev et al., 2023b). |
| 112 | + |
| 113 | +1. Radev, S. T., Schmitt, M., Schumacher, L., Elsemüller, L., Pratz, V., Schälte, Y., Köthe, U., & Bürkner, P.-C. (2023a). BayesFlow: Amortized Bayesian workflows with neural networks. *The Journal of Open Source Software, 8(89)*, 5702.([arXiv](https://arxiv.org/abs/2306.16015))([JOSS](https://joss.theoj.org/papers/10.21105/joss.05702)) |
| 114 | +2. Radev, S. T., Mertens, U. K., Voss, A., Ardizzone, L., Köthe, U. (2020). BayesFlow: Learning complex stochastic models with invertible neural networks. *IEEE Transactions on Neural Networks and Learning Systems, 33(4)*, 1452-1466. ([arXiv](https://arxiv.org/abs/2003.06281))([IEEE TNNLS](https://ieeexplore.ieee.org/document/9298920)) |
| 115 | +3. Radev, S. T., Schmitt, M., Pratz, V., Picchini, U., Köthe, U., & Bürkner, P.-C. (2023b). JANA: Jointly amortized neural approximation of complex Bayesian models. *Proceedings of the Thirty-Ninth Conference on Uncertainty in Artificial Intelligence, 216*, 1695-1706. ([arXiv](https://arxiv.org/abs/2302.09125))([PMLR](https://proceedings.mlr.press/v216/radev23a.html)) |
| 116 | + |
| 117 | +**BibTeX:** |
| 118 | + |
| 119 | +``` |
| 120 | +@article{bayesflow_2023_software, |
| 121 | + title = {{BayesFlow}: Amortized {B}ayesian workflows with neural networks}, |
| 122 | + author = {Radev, Stefan T. and Schmitt, Marvin and Schumacher, Lukas and Elsemüller, Lasse and Pratz, Valentin and Schälte, Yannik and Köthe, Ullrich and Bürkner, Paul-Christian}, |
| 123 | + journal = {Journal of Open Source Software}, |
| 124 | + volume = {8}, |
| 125 | + number = {89}, |
| 126 | + pages = {5702}, |
| 127 | + year = {2023} |
| 128 | +} |
| 129 | +
|
| 130 | +@article{bayesflow_2020_original, |
| 131 | + title = {{BayesFlow}: Learning complex stochastic models with invertible neural networks}, |
| 132 | + author = {Radev, Stefan T. and Mertens, Ulf K. and Voss, Andreas and Ardizzone, Lynton and K{\"o}the, Ullrich}, |
| 133 | + journal = {IEEE transactions on neural networks and learning systems}, |
| 134 | + volume = {33}, |
| 135 | + number = {4}, |
| 136 | + pages = {1452--1466}, |
| 137 | + year = {2020} |
| 138 | +} |
| 139 | +
|
| 140 | +@inproceedings{bayesflow_2023_jana, |
| 141 | + title = {{JANA}: Jointly amortized neural approximation of complex {B}ayesian models}, |
| 142 | + author = {Radev, Stefan T. and Schmitt, Marvin and Pratz, Valentin and Picchini, Umberto and K\"othe, Ullrich and B\"urkner, Paul-Christian}, |
| 143 | + booktitle = {Proceedings of the Thirty-Ninth Conference on Uncertainty in Artificial Intelligence}, |
| 144 | + pages = {1695--1706}, |
| 145 | + year = {2023}, |
| 146 | + volume = {216}, |
| 147 | + series = {Proceedings of Machine Learning Research}, |
| 148 | + publisher = {PMLR} |
| 149 | +} |
| 150 | +``` |
| 151 | + |
| 152 | +## Acknowledgments |
| 153 | + |
| 154 | +This project is currently managed by researchers from Rensselaer Polytechnic Institute, TU Dortmund University, and Heidelberg University. It is partially funded by the Deutsche Forschungsgemeinschaft (DFG, German Research Foundation, Project 528702768). The project is further supported by Germany's Excellence Strategy -- EXC-2075 - 390740016 (Stuttgart Cluster of Excellence SimTech) and EXC-2181 - 390900948 (Heidelberg Cluster of Excellence STRUCTURES), as well as the Informatics for Life initiative funded by the Klaus Tschira Foundation. |
| 155 | + |
| 156 | +## License \& Source Code |
| 157 | + |
| 158 | +BayesFlow is released under {mainbranch}`MIT License <LICENSE>`. |
| 159 | +The source code is hosted on the public [GitHub repository](https://github.com/bayesflow-org/bayesflow). |
| 160 | + |
| 161 | +Indices |
| 162 | +------- |
| 163 | + |
| 164 | +* {ref}`genindex` |
| 165 | +* {ref}`modindex` |
| 166 | + |
| 167 | + |
| 168 | +```{toctree} |
| 169 | +:maxdepth: 0 |
| 170 | +:titlesonly: |
| 171 | +:hidden: |
| 172 | +
|
| 173 | +examples |
| 174 | +api/bayesflow |
| 175 | +about |
| 176 | +Contributing <contributing> |
| 177 | +Developer docs <development/index> |
| 178 | +``` |
0 commit comments