Skip to contents

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 on stan_glm() and stan_glmer() fits. as_priorsense_draws() passes them to priorsense.
  • A diagnosis that separates informative from conflicting priors. The conflict_z statistic 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, and format(report, type = "markdown") puts the checklist into R Markdown or Quarto.

Learn more

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

License

GPL (>= 3)

Repository

main holds the package source. The pkgdown workflow builds the website from main and publishes it with GitHub Pages.