Bayesian inference for GLMs with group-specific coefficients that have unknown covariance matrices with flexible priors.
stan_glmer(
formula,
data = NULL,
family = gaussian,
subset,
weights,
na.action = getOption("na.action", "na.omit"),
offset,
contrasts = NULL,
...,
prior = default_prior_coef(family),
prior_intercept = default_prior_intercept(family),
prior_aux = exponential(autoscale = TRUE),
prior_covariance = decov(),
prior_PD = FALSE,
algorithm = c("sampling", "meanfield", "fullrank"),
adapt_delta = NULL,
QR = FALSE,
sparse = FALSE
)stan_lmer(
formula,
data = NULL,
subset,
weights,
na.action = getOption("na.action", "na.omit"),
offset,
contrasts = NULL,
...,
prior = default_prior_coef(family),
prior_intercept = default_prior_intercept(family),
prior_aux = exponential(autoscale = TRUE),
prior_covariance = decov(),
prior_PD = FALSE,
algorithm = c("sampling", "meanfield", "fullrank"),
adapt_delta = NULL,
QR = FALSE
)
stan_glmer.nb(
formula,
data = NULL,
subset,
weights,
na.action = getOption("na.action", "na.omit"),
offset,
contrasts = NULL,
link = "log",
...,
prior = default_prior_coef(family),
prior_intercept = default_prior_intercept(family),
prior_aux = exponential(autoscale = TRUE),
prior_covariance = decov(),
prior_PD = FALSE,
algorithm = c("sampling", "meanfield", "fullrank"),
adapt_delta = NULL,
QR = FALSE
)
A stanreg object is returned
for stan_glmer, stan_lmer, stan_glmer.nb
.
A list with classes stanreg
, glm
, lm
,
and lmerMod
. The conventions for the parameter names are the
same as in the lme4 package with the addition that the standard
deviation of the errors is called sigma
and the variance-covariance
matrix of the group-specific deviations from the common parameters is
called Sigma
, even if this variance-covariance matrix only has
one row and one column (in which case it is just the group-level variance).
Same as for glmer
. We
strongly advise against omitting the data
argument. Unless
data
is specified (and is a data frame) many post-estimation
functions (including update
, loo
, kfold
) are not
guaranteed to work properly.
Same as for glmer
except it is also
possible to use family=mgcv::betar
to estimate a Beta regression
with stan_glmer
.
Same as glm
.
Same as glm
, but rarely
specified.
For stan_glmer
, further arguments passed to
sampling
(e.g. iter
, chains
,
cores
, etc.) or to vb
(if algorithm
is
"meanfield"
or "fullrank"
). For stan_lmer
and
stan_glmer.nb
, ...
should also contain all relevant arguments
to pass to stan_glmer
(except family
).
The prior distribution for the (non-hierarchical) regression coefficients.
The default priors are described in the vignette
Prior
Distributions for rstanarm Models.
If not using the default, prior
should be a call to one of the
various functions provided by rstanarm for specifying priors. The
subset of these functions that can be used for the prior on the
coefficients can be grouped into several "families":
Family | Functions |
Student t family | normal , student_t , cauchy |
Hierarchical shrinkage family | hs , hs_plus |
Laplace family | laplace , lasso |
Product normal family | product_normal |
See the priors help page for details on the families and
how to specify the arguments for all of the functions in the table above.
To omit a prior ---i.e., to use a flat (improper) uniform prior---
prior
can be set to NULL
, although this is rarely a good
idea.
Note: Unless QR=TRUE
, if prior
is from the Student t
family or Laplace family, and if the autoscale
argument to the
function used to specify the prior (e.g. normal
) is left at
its default and recommended value of TRUE
, then the default or
user-specified prior scale(s) may be adjusted internally based on the
scales of the predictors. See the priors help page and the
Prior Distributions vignette for details on the rescaling and the
prior_summary
function for a summary of the priors used for a
particular model.
The prior distribution for the intercept (after centering all predictors, see note below).
The default prior is described in the vignette
Prior
Distributions for rstanarm Models.
If not using the default, prior_intercept
can be a call to
normal
, student_t
or cauchy
. See the
priors help page for details on these functions. To omit a
prior on the intercept ---i.e., to use a flat (improper) uniform prior---
prior_intercept
can be set to NULL
.
Note: If using a dense representation of the design matrix
---i.e., if the sparse
argument is left at its default value of
FALSE
--- then the prior distribution for the intercept is set so it
applies to the value when all predictors are centered (you don't
need to manually center them). This is explained further in
[Prior Distributions for rstanarm Models](https://mc-stan.org/rstanarm/articles/priors.html)
If you prefer to specify a prior on the intercept without the predictors
being auto-centered, then you have to omit the intercept from the
formula
and include a column of ones as a predictor,
in which case some element of prior
specifies the prior on it,
rather than prior_intercept
. Regardless of how
prior_intercept
is specified, the reported estimates of the
intercept always correspond to a parameterization without centered
predictors (i.e., same as in glm
).
The prior distribution for the "auxiliary" parameter (if
applicable). The "auxiliary" parameter refers to a different parameter
depending on the family
. For Gaussian models prior_aux
controls "sigma"
, the error
standard deviation. For negative binomial models prior_aux
controls
"reciprocal_dispersion"
, which is similar to the
"size"
parameter of rnbinom
:
smaller values of "reciprocal_dispersion"
correspond to
greater dispersion. For gamma models prior_aux
sets the prior on
to the "shape"
parameter (see e.g.,
rgamma
), and for inverse-Gaussian models it is the
so-called "lambda"
parameter (which is essentially the reciprocal of
a scale parameter). Binomial and Poisson models do not have auxiliary
parameters.
The default prior is described in the vignette
Prior
Distributions for rstanarm Models.
If not using the default, prior_aux
can be a call to
exponential
to use an exponential distribution, or normal
,
student_t
or cauchy
, which results in a half-normal, half-t,
or half-Cauchy prior. See priors
for details on these
functions. To omit a prior ---i.e., to use a flat (improper) uniform
prior--- set prior_aux
to NULL
.
Cannot be NULL
; see decov
for
more information about the default arguments.
A logical scalar (defaulting to FALSE
) indicating
whether to draw from the prior predictive distribution instead of
conditioning on the outcome.
A string (possibly abbreviated) indicating the
estimation approach to use. Can be "sampling"
for MCMC (the
default), "optimizing"
for optimization, "meanfield"
for
variational inference with independent normal distributions, or
"fullrank"
for variational inference with a multivariate normal
distribution. See rstanarm-package
for more details on the
estimation algorithms. NOTE: not all fitting functions support all four
algorithms.
Only relevant if algorithm="sampling"
. See
the adapt_delta help page for details.
A logical scalar defaulting to FALSE
, but if TRUE
applies a scaled qr
decomposition to the design matrix. The
transformation does not change the likelihood of the data but is
recommended for computational reasons when there are multiple predictors.
See the QR-argument documentation page for details on how
rstanarm does the transformation and important information about how
to interpret the prior distributions of the model parameters when using
QR=TRUE
.
A logical scalar (defaulting to FALSE
) indicating
whether to use a sparse representation of the design (X) matrix.
If TRUE
, the the design matrix is not centered (since that would
destroy the sparsity) and likewise it is not possible to specify both
QR = TRUE
and sparse = TRUE
. Depending on how many zeros
there are in the design matrix, setting sparse = TRUE
may make
the code run faster and can consume much less RAM.
For stan_glmer.nb
only, the link function to use. See
neg_binomial_2
.
The stan_glmer
function is similar in syntax to
glmer
but rather than performing (restricted) maximum
likelihood estimation of generalized linear models, Bayesian estimation is
performed via MCMC. The Bayesian model adds priors on the
regression coefficients (in the same way as stan_glm
) and
priors on the terms of a decomposition of the covariance matrices of the
group-specific parameters. See priors
for more information
about the priors.
The stan_lmer
function is equivalent to stan_glmer
with
family = gaussian(link = "identity")
.
The stan_glmer.nb
function, which takes the extra argument
link
, is a wrapper for stan_glmer
with family =
neg_binomial_2(link)
.
Gelman, A. and Hill, J. (2007). Data Analysis Using Regression and Multilevel/Hierarchical Models. Cambridge University Press, Cambridge, UK. (Ch. 11-15)
Muth, C., Oravecz, Z., and Gabry, J. (2018) User-friendly Bayesian regression modeling: A tutorial with rstanarm and shinystan. The Quantitative Methods for Psychology. 14(2), 99--119. https://www.tqmp.org/RegularArticles/vol14-2/p099/p099.pdf
stanreg-methods
and
glmer
.
The vignette for stan_glmer
and the Hierarchical
Partial Pooling vignette. https://mc-stan.org/rstanarm/articles/
if (.Platform$OS.type != "windows" || .Platform$r_arch != "i386") {
# see help(example_model) for details on the model below
if (!exists("example_model")) example(example_model)
print(example_model, digits = 1)
}
Run the code above in your browser using DataLab