Prior-focused Bayesian model building and evaluation for rstanarm.
bmbeR takes a regression model through a Bayesian workflow (Gelman et al., 2020) with the prior at the centre. It helps you choose priors on the scale of your data, check what they imply before fitting, verify the computation, measure how much the prior influenced the result, score predictions on held-out data, and report each step.
Website with walkthroughs: https://elkronos.github.io/bmbeR/
Installation
# install.packages("remotes")
remotes::install_github("elkronos/bmbeR")bmbeR needs rstanarm, which installs from CRAN as a binary on Windows and macOS. To install the Get started vignette as well, add build_vignettes = TRUE; this is slower because the vignette fits models.
The workflow on one screen
library(bmbeR)
options(mc.cores = 4) # run chains in parallel
data(kidiq, package = "rstanarm") # children's test scores
train <- kidiq[1:334, ]
test <- kidiq[335:434, ]
# 1. Specify priors in the units of the data
priors <- prior_config(
intercept = prior_spec("normal", location = 100, scale = 20), # at predictor means
slope = prior_spec("normal", location = 0, scale = c(1, 10)),
aux = prior_spec("exponential", rate = 1 / 15)
)
# 2. Check what the priors imply before seeing the outcome
pc <- prior_predictive_check(train, kid_score ~ mom_iq + mom_hs, prior_config = priors,
plausible_range = c(0, 200))
# 3. Fit; convergence is checked automatically (R-hat, bulk/tail-ESS, divergences, E-BFMI)
fit <- fit_model_with_prior(train, kid_score ~ mom_iq + mom_hs, prior_config = priors)
# 4. How much did the prior matter? (power-scaling; no refitting)
prior_sensitivity(fit)
plot_prior_posterior(fit)
# 5. Score predictions with proper scoring rules
perf <- evaluate_model_performance(fit, test)
# 6. Assemble a reporting checklist (Bayesian Analysis Reporting Guidelines)
workflow_report(fit, prior_check = pc, performance = perf)What’s inside
| Workflow stage | Functions | Methods |
|---|---|---|
| Specify priors |
prior_spec(), prior_config(), prior_table()
|
Validated specs; rstanarm and 1.x formats accepted; the priors a fit used after autoscaling |
| Data-informed priors | empirical_bayes_priors() |
Unit-information (Kass & Wasserman, 1995); empirical Bayes shrinkage (Morris, 1983); power priors (Ibrahim & Chen, 2000) |
| Check priors | prior_predictive_check() |
Prior predictive simulation (Gabry et al., 2019) with plausibility summaries |
| Fit | fit_model_with_prior() |
rstanarm::stan_glm() with automatic diagnostics |
| Verify computation |
check_convergence(), generate_plot()
|
Rank-normalised R-hat, bulk/tail-ESS (Vehtari et al., 2021); divergences, E-BFMI (Betancourt, 2017); rank plots |
| Prior influence |
prior_sensitivity(), plot_prior_posterior(), as_priorsense_draws()
|
Power-scaling (Kallioinen et al., 2023), covariance-based local sensitivity (Giordano et al., 2018), PSIS (Vehtari et al., 2024), posterior contraction, prior-data conflict z (Box, 1980) |
| Alternative priors | sensitivity_analysis() |
Refits (optionally in parallel) with posterior shifts and PSIS-LOO or K-fold comparison (Vehtari et al., 2017) |
| Evaluate |
evaluate_model_performance(), compare_performance()
|
Held-out ELPD, CRPS, Brier score (Gneiting & Raftery, 2007), coverage, AUC |
| Report | workflow_report() |
Checklist following BARG (Kruschke, 2021); prints as text or Markdown |
Why bmbeR?
rstanarm fits the models, bayesplot draws the plots, and loo and posterior compute the diagnostics. bmbeR adds what rstanarm users otherwise build by hand:
-
Power-scaling prior sensitivity for rstanarm fits. The priorsense package supports brms, cmdstanr, rstan, JAGS and NIMBLE models but cannot read rstanarm fits. bmbeR rebuilds rstanarm’s log prior from
prior_summary(), including autoscaling and the centred intercept, so the diagnostics work onstan_glm()andstan_glmer()fits.as_priorsense_draws()passes them to priorsense. -
A diagnosis that separates informative from conflicting priors. The
conflict_zstatistic equals the prior predictive z-score of Box (1980) in the normal model. - Data-informed priors that don’t count the data twice. Centring a tight prior on estimates from the same data drops the coverage of nominal 95% intervals to about 83%. Unit-information priors leave it where the likelihood alone puts it, and power priors take their information from a different data set.
- Predictive evaluation on held-out data with proper scoring rules (ELPD, CRPS, Brier score) and paired model comparison.
-
One object per stage, one report at the end. Every result has an
as.data.frame()method, andformat(report, type = "markdown")puts the checklist into R Markdown or Quarto.
Learn more
- Get started: the full workflow on real data
- Choosing priors: scale, autoscaling, prior predictive checks
- Data-informed priors: unit-information, empirical Bayes and power priors
- Convergence diagnostics: what each check means and what failure looks like
- Prior sensitivity: theory and practice of power-scaling
- Predictive evaluation: proper scoring rules and calibration
- Design review: the adversarial review of version 1.01 that led to 2.0.0
Scope
bmbeR supports generalised linear models fitted with rstanarm::stan_glm() (gaussian, binomial, Poisson, negative binomial, Gamma and inverse-Gaussian families). For multilevel models fitted with rstanarm::stan_glmer(), the prior tools (prior_table(), prior_sensitivity(), plot_prior_posterior(), as_priorsense_draws() and workflow_report()) cover the population-level priors and hold the group-level covariance prior fixed. brms is out of scope. The design review lists known limitations.
References
- Betancourt, M. (2017). A conceptual introduction to Hamiltonian Monte Carlo. arXiv:1701.02434. https://doi.org/10.48550/arXiv.1701.02434
- Box, G. E. P. (1980). Sampling and Bayes’ inference in scientific modelling and robustness. JRSS A, 143(4), 383–430. https://doi.org/10.2307/2982063
- Gabry, J., et al. (2019). Visualization in Bayesian workflow. JRSS A, 182(2), 389–402. https://doi.org/10.1111/rssa.12378
- Gelman, A., et al. (2020). Bayesian workflow. arXiv:2011.01808. https://doi.org/10.48550/arXiv.2011.01808
- Giordano, R., Broderick, T., & Jordan, M. I. (2018). Covariances, robustness, and variational Bayes. JMLR, 19(51), 1–49. https://jmlr.org/papers/v19/17-670.html
- Gneiting, T., & Raftery, A. E. (2007). Strictly proper scoring rules, prediction, and estimation. JASA, 102(477), 359–378. https://doi.org/10.1198/016214506000001437
- Ibrahim, J. G., & Chen, M.-H. (2000). Power prior distributions for regression models. Statistical Science, 15(1), 46–60. https://doi.org/10.1214/ss/1009212673
- Kallioinen, N., et al. (2023). Detecting and diagnosing prior and likelihood sensitivity with power-scaling. Statistics and Computing, 34, 57. https://doi.org/10.1007/s11222-023-10366-5
- Kass, R. E., & Wasserman, L. (1995). A reference Bayesian test for nested hypotheses and its relationship to the Schwarz criterion. JASA, 90(431), 928–934. https://doi.org/10.1080/01621459.1995.10476592
- Kruschke, J. K. (2021). Bayesian analysis reporting guidelines. Nature Human Behaviour, 5, 1282–1291. https://doi.org/10.1038/s41562-021-01177-7
- Morris, C. N. (1983). Parametric empirical Bayes inference: Theory and applications. JASA, 78(381), 47–55. https://doi.org/10.1080/01621459.1983.10477920
- Vehtari, A., Gelman, A., & Gabry, J. (2017). Practical Bayesian model evaluation using leave-one-out cross-validation and WAIC. Statistics and Computing, 27(5), 1413–1432. https://doi.org/10.1007/s11222-016-9696-4
- Vehtari, A., et al. (2021). Rank-normalization, folding, and localization: An improved R-hat for assessing convergence of MCMC. Bayesian Analysis, 16(2), 667–718. https://doi.org/10.1214/20-BA1221
- Vehtari, A., et al. (2024). Pareto smoothed importance sampling. JMLR, 25(72), 1–58. https://jmlr.org/papers/v25/19-556.html