Fit a Bayesian regression model with explicit priors
Source:R/model_fitting.R
fit_model_with_prior.RdFits a generalised linear model with rstanarm::stan_glm() using priors
specified with prior_config() (or derived with
empirical_bayes_priors()), then runs check_convergence() on the
result.
Arguments
- data
A data frame containing all variables in
formula.- formula
A model formula, e.g.
y ~ x1 + x2.- family
A family object, family function or family name:
gaussian,binomial,poisson,Gamma,inverse.gaussianorneg_binomial_2.- prior_config
Priors as a
prior_config()object, the output ofempirical_bayes_priors(), a bmbeR 1.x list withinterceptandslopeelements, orNULLfor rstanarm's defaults.- chains
Number of Markov chains (at least 4 are recommended).
- iter
Iterations per chain, including warm-up (half by default).
- seed
Random seed passed to Stan, for reproducibility (a single non-negative whole number).
- on_nonconvergence
What to do if
check_convergence()fails:"warn"(default),"error"or"ignore".- convergence_args
A list of further arguments for
check_convergence(), e.g.list(rhat_threshold = 1.01).- ...
Further arguments passed to
rstanarm::stan_glm(), e.g.cores,refresh = 0,adapt_deltaorweights.
Value
A stanreg object with attributes bmb_convergence (a
check_convergence() result) and bmb_prior_config (the priors used,
after any re-expression of the intercept prior).
Details
Default priors. Components of prior_config that are NULL use
rstanarm's weakly informative defaults, which are autoscaled to the
data (Gelman et al., 2008). bmbeR 1.x instead used an unscaled
student_t(3, 0, 2.5) prior for all coefficients, which can dominate the
likelihood when variables are not on a unit scale.
Convergence. Diagnostics are always computed and stored in
attr(fit, "bmb_convergence"). By default a failed check issues a
warning but still returns the fit, so that the (expensive) model is not
lost and can be inspected; use on_nonconvergence = "error" to stop
instead.
Parallel chains. bmbeR does not choose the number of cores. Set
options(mc.cores = parallel::detectCores()) or pass cores = through
....
Arguments in .... weights, subset, offset and na.action are
evaluated inside data, as in rstanarm::stan_glm(), so
weights = w refers to the column w. The stored model call refers to
the data by name, so stats::update(), loo::loo() and loo::kfold()
work on the result.
Data-informed priors. The intercept prior from
empirical_bayes_priors() is placed on the intercept at the predictor
means. When data has different predictor means from the data the priors
were derived from (always the case for power priors), the intercept prior
is re-expressed at the means of data before fitting.
Random numbers. The seed is passed to Stan. The default is fixed, so
repeated calls give identical chains unless you change it. R's own random
number stream is left unchanged.
References
Gelman, A., Jakulin, A., Pittau, M. G., & Su, Y.-S. (2008). A weakly informative default prior distribution for logistic and other regression models. The Annals of Applied Statistics, 2(4), 1360–1383. doi:10.1214/08-AOAS191
See also
prior_predictive_check() to check priors before fitting,
prior_sensitivity() to check their influence afterwards.
Examples
# \donttest{
data(kidiq, package = "rstanarm")
fit <- fit_model_with_prior(
kidiq, kid_score ~ mom_iq + mom_hs,
prior_config = prior_config(
intercept = prior_spec("normal", location = 80, scale = 20),
slope = prior_spec("normal", location = 0, scale = c(1, 10))
),
chains = 4, iter = 1000, refresh = 0
)
attr(fit, "bmb_convergence")
#> <bmb_convergence> PASSED (4 chains, 2000 post-warm-up draws)
#> Criteria: R-hat <= 1.01; bulk/tail-ESS >= 400; divergences <= 0; E-BFMI >= 0.3
#> Max R-hat: 1.003 | min bulk-ESS: 1974 | min tail-ESS: 1359
#> Divergences: 0 | max-treedepth hits: 0 | min E-BFMI: 0.96
# }