Bambi Documentation

Bambi requires a working Python interpreter (3.12+). You can install the stable version using pip:

pip install bambi

If you want to install the bleeding edge version directly from GitHub:

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

Bambi automatically installs its required dependencies, including ArviZ, formulae, NumPy, pandas, and PyMC.

To fit a simple fixed effects linear regression model, follow these steps:

1. Load your data (or use bmb.load_data() for built-in datasets).
2. Initialize a bmb.Model using a formula string (e.g., 'Reaction ~ Days') and your data.
3. Call .fit() on the model instance. This returns an InferenceData object.
4. Use ArviZ to analyze the results (e.g., az.summary() for parameter statistics or az.plot_trace() for visualizations).

Note: The default family is gaussian with an identity link.

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

# Load dataset
data = bmb.load_data("sleepstudy")

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

# Fit the model
results = model.fit(draws=1000)

# Summary and diagnostics
print(az.summary(results))
az.plot_trace(results)

MrP is a two-step technique used to correct for non-representative samples (e.g., in national surveys) by using known population weights.

1. Multilevel Regression: Fit a model (often hierarchical) that captures the variation in outcomes across different demographic strata (e.g., age, race, state). This allows the model to 'learn' the effect of each group even if some groups are underrepresented in the sample.
2. Post-stratification: Instead of using the raw sample averages (which are biased), use the fitted model to predict outcomes for every possible demographic combination (strata) in the actual population. Then, weight these predictions by the known population proportions (from census data) and sum them to get a representative population estimate.

This process effectively 're-weights' the model's knowledge to match the real-world distribution of the population.

A ResponseComponent represents the response variable (the dependent variable) in the model. It links the response data to the model's family and handles specific validation logic for different distributions.

Key Features

• Bernoulli Validation: For the bernoulli family, it ensures that categoric responses are binary and numeric responses consist only of 0s and 1s.
• Index Notation: Supports index notation for responses, though this is currently restricted to the bernoulli family.

Parameters

• response: The response term/data.
• spec (bambi.Model): The Bambi model instance.

A ConstantComponent represents a parameter of the response distribution that remains constant for all observations. This is equivalent to an intercept-only model for that specific parameter. For example, in a homoskedastic Gaussian linear regression, the parameter sigma (the error term) is a ConstantComponent because it does not vary with the predictors.

Parameters

• name (str): The name of the component (e.g., "sigma", "alpha", or "kappa").
• priors (bambi.Prior): The prior distribution for the parameter.
• spec (bambi.Model): The Bambi model instance.

To fit a model with fixed and random effects, initialize a bmb.Model with a formula and a pandas DataFrame, then call .fit(). Results are returned as an ArviZ InferenceData object.

Example for a within-subjects experiment with nested stimuli and crossed subjects/conditions:

import bambi as bmb
import arviz as az

# Assume 'data' is a pandas DataFrame
model = bmb.Model("rt ~ condition + (condition|subject) + (1|stimulus)", data)
results = model.fit(draws=5000, chains=2)
az.plot_trace(results)
az.summary(results)

Bambi's .fit() method returns an arviz.InferenceData object. Use ArviZ functions to inspect the posterior.

Visualizing traces

Use az.plot_trace(results) to see the posterior estimates and sample traces.

Numerical summaries

Use az.summary(results) to get a pandas DataFrame containing key diagnostics like the 94% highest posterior density intervals.

Inspecting variables

To see the names of all variables in the posterior:

list(results.posterior.data_vars)

For binary response variables, use the family="bernoulli" argument in bmb.Model.

Bambi supports syntax sugar to specify which event in a categorical response you want to model. For example, if your column g contains "Yes" and "No", you can use g['Yes'] in your formula to model the probability of a "Yes" response. If you use a standard formula like "g ~ x1 + x2", Bambi will automatically pick one of the events to model and notify you which one was selected.

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

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

# Modeling the probability of 'Yes' using Bernoulli family
model = bmb.Model("g['Yes'] ~ x1 + x2", data, family="bernoulli")
fitted = model.fit()

The bmb.Model class is the primary interface for building models. It accepts a formula string, a pandas DataFrame, and optional arguments like family.

Key Parameters:

• formula (str): A formula string describing the relationship between variables (e.g., 'y ~ x1 + x2').
• data (pd.DataFrame): The dataset containing the variables.
• family (str): The distribution family (e.g., 'gaussian', 'bernoulli').

Key Methods:

• fit(draws=...): Runs the sampler and returns an arviz.InferenceData object containing the posterior samples.

import bambi as bmb

model = bmb.Model('Reaction ~ Days', data)
results = model.fit(draws=1000)

The truncated() function constructs an array for a truncated response, where the bounds are interpreted as a missing data mechanism.

Parameters:

• x: The values of the truncated variable.
• lb: Lower truncation bound (scalar or array). If None, defaults to -inf.
• ub: Upper truncation bound (scalar or array). If None, defaults to inf.

Returns: An np.ndarray of shape (n, 3) where columns are [x, lower_bound, upper_bound].