Skip to main content

Variational Bayesian Monte Carlo in Python.

Project description

PyVBMC

PyVBMC: Variational Bayesian Monte Carlo in Python

What is it?

PyVBMC is the port of the MATLAB VBMC algorithm to Python. VBMC is an approximate inference method designed to fit and evaluate Bayesian models with a limited budget of potentially noisy likelihood evaluations (e.g., for computationally expensive models). Specifically, VBMC simultaneously computes:

  • an approximate posterior distribution of the model parameters;
  • an approximation — technically, an approximate lower bound — of the log model evidence (also known as log marginal likelihood or log Bayes factor), a metric used for Bayesian model selection.

Extensive benchmarks on both artificial test problems and a large number of real model-fitting problems from computational and cognitive neuroscience show that VBMC generally — and often vastly — outperforms alternative methods for sample-efficient Bayesian inference [1,2].

Documentation

The full documentation is available at: https://acerbilab.github.io/pyvbmc/

When should I use PyVBMC?

PyVBMC is effective when:

  • the model log-likelihood function is a black-box (e.g., the gradient is unavailable);
  • the likelihood is at least moderately expensive to compute (say, half a second or more per evaluation);
  • the model has up to D = 10 continuous parameters (maybe a few more, but no more than D = 20);
  • the target posterior distribution is continuous and reasonably smooth (see here);
  • optionally, log-likelihood evaluations may be noisy (e.g., estimated via simulation).

Conversely, if your model can be written analytically, you should exploit the powerful machinery of probabilistic programming frameworks such as Stan or PyMC3.

Installation

PyVBMC is available via pip (and soon, conda-forge).

  1. Install with:
    python -m pip install pyvbmc
    
    or:
    conda install --channel=conda-forge pyvbmc
    
    PyVBMC requires Python version 3.9 or newer.
  2. (Optional): Install Jupyter to view the example Notebooks. You can skip this step if you're working from a Conda environment which already has Jupyter, but be aware that if the wrong jupyter executable is found on your path then import errors may arise.
    conda install jupyter
    
    The example notebooks can be accessed by running
    python -m pyvbmc
    

If you wish to install directly from latest source code, please see the instructions for developers and contributors.

Quick start

A typical PyVBMC workflow follows four steps:

  1. Define the model, which defines a target log density (i.e., an unnormalized log posterior density);
  2. Setup the parameters (parameter bounds, starting point);
  3. Initialize and run the inference;
  4. Examine and visualize the results.

PyVBMC is not concerned with how you define your model in step 1, as long as you can provide an (unnormalized) target log density. Running the inference in step 3 only involves a couple of lines of code:

from pyvbmc import VBMC
# ... define your model/target density here
vbmc = VBMC(target, x0, LB, UB, PLB, PUB)
vp, results = vbmc.optimize()

with input arguments:

  • target: the target (unnormalized) log density — often an unnormalized log posterior. target is a callable that should take as input a parameter vector and return the log density at the point;
  • x0: an array representing the starting point of the inference in parameter space;
  • LB and UB: arrays of hard lower (resp. upper) bounds constraining the parameters (possibly -/+np.inf for unbounded parameters);
  • PLB and PUB: arrays of plausible lower (resp. upper) bounds: that is, a box that ideally brackets a high posterior density region of the target.

The outputs are:

  • vp: a VariationalPosterior object which approximates the true target density;
  • results: a dict containing additional information. Important keys are:
    • "elbo": the estimated lower bound on the log model evidence (log normalization constant);
    • "elbo_sd": the standard deviation of the estimate of the ELBO (not the error between the ELBO and the true log model evidence, which is generally unknown).

The vp object can be manipulated in various ways. For example, we can draw samples from vp with the vp.sample() method, or evaluate its density at a point with vp.pdf() (or log-density with vp.log_pdf()). See the VariationalPosterior class documentation for details.

PyVBMC with noisy targets

The quick start example above works for deterministic (noiseless) evaluations of the target log-density. Py(VBMC) also supports noisy evaluations of the target. Noisy evaluations often arise from simulation-based models, for which a direct expression of the (log) likelihood is not available.

For information on how to run PyVBMC on a noisy target, see this example notebook and the VBMC FAQ (for MATLAB, but most concepts still apply).

Next steps

Once installed, example Jupyter notebooks can be found in the pyvbmc/examples directory. They can also be viewed statically on the main documentation pages. These examples will walk you through the basic usage of PyVBMC as well as some if its more advanced features.

For practical recommendations, such as how to set LB and UB and the plausible bounds, check out the FAQ on the VBMC wiki. The wiki was written with the MATLAB toolbox in mind, but the general advice applies to the Python version as well.

How does it work?

VBMC/PyVBMC combine two machine learning techniques in a novel way:

PyVBMC iteratively builds an approximation of the true, expensive target posterior via a Gaussian process (GP), and it matches a variational distribution — an expressive mixture of Gaussians — to the GP.

This matching process entails optimization of the evidence lower bound (ELBO), that is a lower bound on the log marginal likelihood (LML), also known as log model evidence. Crucially, we estimate the ELBO via Bayesian quadrature, which is fast and does not require further evaluation of the true target posterior.

In each iteration, PyVBMC uses active sampling to select which points to evaluate next in order to explore the posterior landscape and reduce uncertainty in the approximation.

VBMC demo

In the figure above, we show an example PyVBMC run on a Rosenbrock "banana" function. The bottom-left panel shows PyVBMC at work: in grayscale are samples from the variational posterior (drawn as small points) and the corresponding estimated density (drawn as contours). The solid orange circles are the active sampling points chosen at each iteration, and the hollow blue circles are the previously sampled points. The topmost and rightnmost panels show histograms of the marginal densities along the $x_1$ and $x_2$ dimensions, respectively. PyVBMC converges to an excellent approximation of the true posterior with a few dozens evaluations of the target density.

See the VBMC papers [1,2] for more details.

Troubleshooting and contact

PyVBMC is under active development. The original VBMC algorithm has been extensively tested in several benchmarks and published papers, and the benchmarks have been replicated using PyVBMC. But as with any approximate inference technique, you should double-check your results. See the examples for descriptions of the convergence diagnostics and suggestions on validating PyVBMC's results with multiple runs.

If you have trouble doing something with PyVBMC, spot bugs or strange behavior, or you simply have some questions, please feel free to:

References and citation

  1. Acerbi, L. (2018). Variational Bayesian Monte Carlo. In Advances in Neural Information Processing Systems 31: 8222-8232. (paper + supplement on arXiv, NeurIPS Proceedings)
  2. Acerbi, L. (2020). Variational Bayesian Monte Carlo with Noisy Likelihoods. In Advances in Neural Information Processing Systems 33: 8211-8222 (paper + supplement on arXiv, NeurIPS Proceedings).

Please cite both references if you use PyVBMC in your work (the 2018 paper introduced the framework, and the 2020 paper includes a number of major improvements, including but not limited to support for noisy likelihoods). You can cite PyVBMC in your work with something along the lines of

We estimated approximate posterior distibutions and approximate lower bounds to the model evidence of our models using Variational Bayesian Monte Carlo (PyVBMC; Acerbi, 2018, 2020). PyVBMC combines variational inference and active-sampling Bayesian quadrature to perform approximate Bayesian inference in a sample-efficient manner.

Besides formal citations, you can demonstrate your appreciation for PyVBMC in the following ways:

  • Star :star: the VBMC repository on GitHub;
  • Subscribe to the lab's newsletter for news and updates (new features, bug fixes, new releases, etc.);
  • Follow Luigi Acerbi on Twitter for updates about VBMC/PyVBMC and other projects;
  • Tell us about your model-fitting problem and your experience with PyVBMC (positive or negative) in the lab's Discussions forum.

You may also want to check out Bayesian Adaptive Direct Search (BADS), our method for fast Bayesian optimization. Currently available only in MATLAB, but a Python version will be released soon.

Additional references

  1. Acerbi, L. (2019). An Exploration of Acquisition and Mean Functions in Variational Bayesian Monte Carlo. In Proc. Machine Learning Research 96: 1-10. 1st Symposium on Advances in Approximate Bayesian Inference, Montréal, Canada. (paper in PMLR)

BibTeX

@article{acerbi2018variational,
  title={{V}ariational {B}ayesian {M}onte {C}arlo},
  author={Acerbi, Luigi},
  journal={Advances in Neural Information Processing Systems},
  volume={31},
  pages={8222--8232},
  year={2018}
}

@article{acerbi2020variational,
  title={{V}ariational {B}ayesian {M}onte {C}arlo with noisy likelihoods},
  author={Acerbi, Luigi},
  journal={Advances in Neural Information Processing Systems},
  volume={33},
  pages={8211--8222},
  year={2020}
}

@article{acerbi2019exploration,
  title={An Exploration of Acquisition and Mean Functions in {V}ariational {B}ayesian {M}onte {C}arlo},
  author={Acerbi, Luigi},
  journal={PMLR},
  volume={96},
  pages={1--10},
  year={2019}
}

License

PyVBMC is released under the terms of the BSD 3-Clause License.

Acknowledgments

PyVBMC was developed from the original MATLAB toolbox by members (past and current) of the Machine and Human Intelligence Lab at the University of Helsinki. The ongoing Python port is being supported by the Academy of Finland Flagship programme: Finnish Center for Artificial Intelligence FCAI.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

PyVBMC-0.9.0.tar.gz (9.2 MB view details)

Uploaded Source

Built Distribution

PyVBMC-0.9.0-py3-none-any.whl (9.2 MB view details)

Uploaded Python 3

File details

Details for the file PyVBMC-0.9.0.tar.gz.

File metadata

  • Download URL: PyVBMC-0.9.0.tar.gz
  • Upload date:
  • Size: 9.2 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.10.8

File hashes

Hashes for PyVBMC-0.9.0.tar.gz
Algorithm Hash digest
SHA256 2bcbf4dc58ef38407222f753576232ed189d7925276e79ec4bda4d1540f22b08
MD5 d9a49b62da4c875ad68208e4657ec780
BLAKE2b-256 796bd3c8fb797cb2b3605a1910e717db26e9e4797dfee68824cab2cb095ff1d8

See more details on using hashes here.

File details

Details for the file PyVBMC-0.9.0-py3-none-any.whl.

File metadata

  • Download URL: PyVBMC-0.9.0-py3-none-any.whl
  • Upload date:
  • Size: 9.2 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.10.8

File hashes

Hashes for PyVBMC-0.9.0-py3-none-any.whl
Algorithm Hash digest
SHA256 702ed71628bc7a8966c5a29bba41485f3217e5209349dbe6f33c32447f91631c
MD5 72cf486b3f50e39d1874fd7462807040
BLAKE2b-256 98cdf607fd1d0ee95f57ae6a82ad08f34228b608217458294acc360f8644e04f

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page