statsmodels.genmod.bayes_mixed_glm.BinomialBayesMixedGLM

class statsmodels.genmod.bayes_mixed_glm.BinomialBayesMixedGLM(endog, exog, exog_vc, ident, vcp_p=1, fe_p=2, fep_names=None, vcp_names=None, vc_names=None) [source]

Fit a generalized linear mixed model using Bayesian methods.

The class implements the Laplace approximation to the posterior distribution (fit_map) and a variational Bayes approximation to the posterior (fit_vb). See the two fit method docstrings for more information about the fitting approaches.

Parameters:	endog (array-like) – Vector of response values. exog (array-like) – Array of covariates for the fixed effects part of the mean structure. exog_vc (array-like) – Array of covariates for the random part of the model. A scipy.sparse array may be provided, or else the passed array will be converted to sparse internally. ident (array-like) – Array of labels showing which random terms (columns of exog_vc) have a common variance. vc_p (float) – Prior standard deviation for variance component parameters (the prior standard deviation of log(s) is vc_p, where s is the standard deviation of a random effect). fe_p (float) – Prior standard deviation for fixed effects parameters. family (statsmodels.genmod.families instance) – The GLM family. fep_names (list of strings) – The names of the fixed effects parameters (corresponding to columns of exog). If None, default names are constructed. vcp_names (list of strings) – The names of the variance component parameters (corresponding to distinct labels in ident). If None, default names are constructed. vc_names (list of strings) – The names of the random effect realizations.
Returns:
Return type:	MixedGLMResults object

Notes

There are three types of values in the posterior distribution: fixed effects parameters (fep), corresponding to the columns of exog, random effects realizations (vc), corresponding to the columns of exog_vc, and the standard deviations of the random effects realizations (vcp), corresponding to the unique labels in ident.

All random effects are modeled as being independent Gaussian values (given the variance parameters). Every column of exog_vc has a distinct realized random effect that is used to form the linear predictors. The elements of ident determine the distinct random effect variance parameters. Two random effect realizations that have the same value in ident are constrained to have the same variance. When fitting with a formula, ident is constructed internally (each element of vc_formulas yields a distinct label in ident).

The random effect standard deviation parameters (vcp) have log-normal prior distributions with mean 0 and standard deviation vcp_p.

Note that for some families, e.g. Binomial, the posterior mode may be difficult to find numerically if vcp_p is set to too large of a value. Setting vcp_p to 0.5 seems to work well.

The prior for the fixed effects parameters is Gaussian with mean 0 and standard deviation fe_p.

Examples

A binomial (logistic) random effects model with random intercepts for villages and random slopes for each year within each village:

>>> data['year_cen'] = data['Year'] - data.Year.mean()
>>> random = ['0 + C(Village)', '0 + C(Village)*year_cen']
>>> model = BinomialBayesMixedGLM.from_formula('y ~ year_cen',
               random, data)
>>> result = model.fit()

References

Introduction to generalized linear mixed models: https://stats.idre.ucla.edu/other/mult-pkg/introduction-to-generalized-linear-mixed-models

SAS documentation: https://support.sas.com/documentation/cdl/en/statug/63033/HTML/default/viewer.htm#statug_intromix_a0000000215.htm

An assessment of estimation methods for generalized linear mixed models with binary outcomes https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3866838/

Methods

fit()	Fit a model to data.
fit_map([method, minim_opts])	Construct the Laplace approximation to the posterior distribution.
fit_vb([mean, sd, fit_method, minim_opts, …])	Fit a model using the variational Bayes mean field approximation.
from_formula(formula, vc_formulas, data[, …])	Fit a BayesMixedGLM using a formula.
logposterior(params)	The overall log-density: log p(y, fe, vc, vcp).
logposterior_grad(params)	The gradient of the log posterior.
predict(params[, exog])	After a model has been fit predict returns the fitted values.
vb_elbo(vb_mean, vb_sd)	Returns the evidence lower bound (ELBO) for the model.
vb_elbo_base(h, tm, fep_mean, vcp_mean, …)	Returns the evidence lower bound (ELBO) for the model.
vb_elbo_grad(vb_mean, vb_sd)	Returns the gradient of the model’s evidence lower bound (ELBO).
vb_elbo_grad_base(h, tm, tv, fep_mean, …)	Return the gradient of the ELBO function.

Attributes

endog_names	Names of endogenous variables
exog_names	Names of exogenous variables
rng
verbose