BAyesian Model-Building Interface in Python

PyPi version Build Status codecov Code style: black

Bambi is a high-level Bayesian model-building interface written in Python. It works with the PyMC probabilistic programming framework and is designed to make it extremely easy to fit Bayesian mixed-effects models common in biology, social sciences and other disciplines.

Dependencies

Bambi is tested on Python 3.10+ and depends on ArviZ, formulae, NumPy, pandas and PyMC (see pyproject.toml for version information).

Installation

Bambi is available from the Python Package Index at https://pypi.org/project/bambi, alternatively it can be installed using Conda.

PyPI

The latest release of Bambi can be installed using pip:

pip install bambi

Alternatively, if you want the bleeding edge version of the package, you can install from GitHub:

pip install git+https://github.com/bambinos/bambi.git

Conda

If you use Conda, you can also install the latest release of Bambi with the following command:

conda install -c conda-forge bambi

Examples

In the following two examples we assume the following basic setup

import arviz as az
import bambi as bmb
import numpy as np
import pandas as pd

Linear regression

A simple fixed effects model is shown in the example below.

# Read in a dataset from the package content
data = bmb.load_data("sleepstudy")

# See first rows
data.head()
 
# Initialize the fixed effects only model
model = bmb.Model('Reaction ~ Days', data)

# Get model description
print(model)

# Fit the model using 1000 on each chain
results = model.fit(draws=1000)

# Key summary and diagnostic info on the model parameters
az.summary(results)

# Use ArviZ to plot the results
az.plot_trace(results)
   Reaction  Days  Subject
0  249.5600     0      308
1  258.7047     1      308
2  250.8006     2      308
3  321.4398     3      308
4  356.8519     4      308
       Formula: Reaction ~ Days
        Family: gaussian
          Link: mu = identity
  Observations: 180
        Priors:
    target = mu
        Common-level effects
            Intercept ~ Normal(mu: 298.5079, sigma: 261.0092)
            Days ~ Normal(mu: 0.0, sigma: 48.8915)

        Auxiliary parameters
            sigma ~ HalfStudentT(nu: 4.0, sigma: 56.1721)
                   mean     sd   hdi_3%  hdi_97%  mcse_mean  mcse_sd  ess_bulk  ess_tail  r_hat
Intercept       251.552  6.658  238.513  263.417      0.083    0.059    6491.0    2933.0    1.0
Days             10.437  1.243    8.179   12.793      0.015    0.011    6674.0    3242.0    1.0
Reaction_sigma   47.949  2.550   43.363   52.704      0.035    0.025    5614.0    2974.0    1.0

First, we create and build a Bambi Model. Then, the method model.fit() tells the sampler to start running and it returns an InferenceData object, which can be passed to several ArviZ functions such as az.summary() to get a summary of the parameters distribution and sample diagnostics or az.plot_trace() to visualize them.

Logistic regression

In this example we will use a simulated dataset created as shown below.

data = pd.DataFrame({
    "g": np.random.choice(["Yes", "No"], size=50),
    "x1": np.random.normal(size=50),
    "x2": np.random.normal(size=50)
})

Here we just add the family argument set to "bernoulli" to tell Bambi we are modelling a binary response. By default, it uses a logit link. We can also use some syntax sugar to specify which event we want to model. We just say g['Yes'] and Bambi will understand we want to model the probability of a "Yes" response. But this notation is not mandatory. If we use "g ~ x1 + x2", Bambi will pick one of the events to model and will inform us which one it picked.

model = bmb.Model("g['Yes'] ~ x1 + x2", data, family="bernoulli")
fitted = model.fit()

After this, we can evaluate the model as before.

More

For a more in-depth introduction to Bambi see our Quickstart and check the notebooks in the Examples webpage.

Citation

If you use Bambi and want to cite it please use

@article{
    Capretto2022,
    title={Bambi: A Simple Interface for Fitting Bayesian Linear Models in Python},
    volume={103},
    url={https://www.jstatsoft.org/index.php/jss/article/view/v103i15},
    doi={10.18637/jss.v103.i15},
    number={15},
    journal={Journal of Statistical Software},
    author={Capretto, Tomás and Piho, Camen and Kumar, Ravin and Westfall, Jacob and Yarkoni, Tal and Martin, Osvaldo A},
    year={2022},
    pages={1–29}
}

Contributing

We welcome contributions from interested individuals or groups! For information about contributing to Bambi, check out our instructions, policies, and guidelines here.

Contributors

See the GitHub contributor page.