/probability

Probabilistic reasoning and statistical analysis in TensorFlow

Primary LanguageJupyter NotebookApache License 2.0Apache-2.0

TensorFlow Probability

TensorFlow Probability is a library for probabilistic reasoning and statistical analysis in TensorFlow. As part of the TensorFlow ecosystem, TensorFlow Probability provides integration of probabilistic methods with deep networks, gradient-based inference via automatic differentiation, and scalability to large datasets and models via hardware acceleration (e.g., GPUs) and distributed computation.

Our probabilistic machine learning tools are structured as follows.

Layer 0: TensorFlow. Numerical operations. In particular, the LinearOperator class enables matrix-free implementations that can exploit special structure (diagonal, low-rank, etc.) for efficient computation. It is built and maintained by the TensorFlow Probability team and is now part of tf.linalg in core TF.

Layer 1: Statistical Building Blocks

Layer 2: Model Building

  • Joint Distributions (e.g., tfp.distributions.JointDistributionSequential): Joint distributions over one or more possibly-interdependent distributions. For an introduction to modeling with TFP's JointDistributions, check out this colab
  • Probabilistic Layers (tfp.layers): Neural network layers with uncertainty over the functions they represent, extending TensorFlow Layers.

Layer 3: Probabilistic Inference

  • Markov chain Monte Carlo (tfp.mcmc): Algorithms for approximating integrals via sampling. Includes Hamiltonian Monte Carlo, random-walk Metropolis-Hastings, and the ability to build custom transition kernels.
  • Variational Inference (tfp.vi): Algorithms for approximating integrals via optimization.
  • Optimizers (tfp.optimizer): Stochastic optimization methods, extending TensorFlow Optimizers. Includes Stochastic Gradient Langevin Dynamics.
  • Monte Carlo (tfp.monte_carlo): Tools for computing Monte Carlo expectations.

TensorFlow Probability is under active development. Interfaces may change at any time.

Examples

See tensorflow_probability/examples/ for end-to-end examples. It includes tutorial notebooks such as:

It also includes example scripts such as:

Installation

Stable Builds

To install the latest version, run the following:

# Notes:
# - We recommend that users move towards using TensorFlow 2.x as soon as
#   possible. Until the TF2 stable package is released (due in Sep. 2019),
#   the best way to use TFP with TF2 is to use nightly TFP and TF2 packages:
#     - Nightly TFP: [tfp-nightly](http://pypi.python.org/pypi/tfp-nightly)
#     - Nightly TF2: [tf-nightly-2.0-preview](http://pypi.python.org/pypi/tf-nightly-2.0-preview)
#   Once the TF2 stable release comes out, TFP will issue its 0.8.0 release,
#   which will be tested and stable against TF 2.0.0.
# - You need the latest version of `pip` in order to get the latest version of
#   `tf-nightly-2.0-preview`.
# - For GPU TF, use `tf-nightly-2.0-preview-gpu`.
# - The `--upgrade` flag ensures you'll get the latest version.
# - The `--user` flag ensures the packages are installed to your user directory
#   rather than the system directory.
python -m pip install pip --upgrade --user
python -m pip install tf-nightly-2.0-preview tfp-nightly --upgrade --user
TFVERSION=$(python -c 'import tensorflow; print(tensorflow.__version__)')
# If you have an older pip, you might get this older version of
# tf-nightly-2.0-preview, so check to be sure.
[[ $TFVERSION == '2.0.0-dev20190731' ]] &&
  echo >&2 "Failed to install the most recent TF. Found: ${TFVERSION}."

TensorFlow Probability depends on a recent stable release of TensorFlow (pip package tensorflow). See the TFP release notes for details about dependencies between TensorFlow and TensorFlow Probability.

Note: Since TensorFlow is not included as a dependency of the TensorFlow Probability package (in setup.py), you must explicitly install the TensorFlow package (tensorflow or tensorflow-gpu). This allows us to maintain one package instead of separate packages for CPU and GPU-enabled TensorFlow.

To force a Python 3-specific install, replace pip with pip3 in the above commands. For additional installation help, guidance installing prerequisites, and (optionally) setting up virtual environments, see the TensorFlow installation guide.

Nightly Builds

There are also nightly builds of TensorFlow Probability under the pip package tfp-nightly, which depends on one of tf-nightly, tf-nightly-gpu, tf-nightly-2.0-preview or tf-nightly-gpu-2.0-preview. Nightly builds include newer features, but may be less stable than the versioned releases. Docs are periodically refreshed here.

Installing from Source

You can also install from source. This requires the Bazel build system.

# sudo apt-get install bazel git python-pip  # Ubuntu; others, see above links.
git clone https://github.com/tensorflow/probability.git
cd probability
bazel build --copt=-O3 --copt=-march=native :pip_pkg
PKGDIR=$(mktemp -d)
./bazel-bin/pip_pkg $PKGDIR
pip install --user --upgrade $PKGDIR/*.whl

Community

As part of TensorFlow, we're committed to fostering an open and welcoming environment.

See the TensorFlow Community page for more details. Check out our latest publicity here:

Contributing

We're eager to collaborate with you! See CONTRIBUTING.md for a guide on how to contribute. This project adheres to TensorFlow's code of conduct. By participating, you are expected to uphold this code.

References

If you use TensorFlow Probability in a paper, please cite:

  • TensorFlow Distributions. Joshua V. Dillon, Ian Langmore, Dustin Tran, Eugene Brevdo, Srinivas Vasudevan, Dave Moore, Brian Patton, Alex Alemi, Matt Hoffman, Rif A. Saurous. arXiv preprint arXiv:1711.10604, 2017.

(We're aware there's a lot more to TensorFlow Probability than Distributions, but the Distributions paper lays out our vision and is a fine thing to cite for now.)