1  Introducing brms

1.1 What is brms?

brms is an R library for bayesian regression models using Stan:

  • Models: a mathematical description of an observed or hypothesized behavior.
  • Regression: a model that relates variables through linear combinations of variables.
  • Bayesian: a model that uses Bayes’ theorem to obtain likely values for some quantity of interest.
  • Stan: a probabilistic programming language for Bayesian modeling.

brms can fit many types of models, including: linear, robust linear, count data, survival, response times, ordinal, zero-inflated, hurdle, and even self-defined mixture models. brms can also account for non-linear terms, auto-correlation structures, censoring and truncation, meta-analytic standard errors, and more. And it can combine these models into custom versions for more complicated data.

brms can give good uncertainty estimates for all these models. It also offers thorough diagnostics to check how well a model fits the data, and how reliable the estimated parameters are.

Housing all these features in a single modeling library affords us a consistent syntax and an ecosystem of libraries that work automatically with most models. So, with brms we can learn new models incrementally and we can share code and help with other people even their models differ from ours.

1.2 Installation

Making brms work in our computer requires some preparation. First, updating R to its latest version will help our libraries work better with each other and with R itself. Installing brms with an older version of R may work, but is likely to cause problems later.

1.2.1 C++ toolchain

brms needs a C++ toolchain to translate R models into a more efficient machinespeak that runs in the background. Setting up this toolchain can take several minutes, but needs to be done only once.

In Windows, the C++ toolchain comes with RTools 4.5. To check if this is already installed, go to R and run devtools::find_rtools() (you may need to first run install.packages("devtools")). To install RTools, go to this website. Here, download the Rtools45 installer and follow its instructions while keeping all the default choices.

In macOS, the C++ toolchain comes with Xcode Command Line Tools. First, go to the Terminal (open Finder > Applications > Terminal) and check if Xcode this is already installed with

xcode-select --version

If not, install xcode (which may take a while) with

xcode-select --install
WarningInstall toolchain before brms

R would not complain if we installed brms before preparing the C++ toolchain. But without the toolchain none of our models would run, so it is better to set it up in advance.

1.2.2 Default version of brms

With our C++ toolchain ready, we can return to R and install brms.

install.packages("brms")

Run the commands below to verify that brms works properly.

library(brms)
fit1 <- brm(count ~ zAge + zBase * Trt + (1|patient),
            data = epilepsy, family = poisson())
summary(fit1)

The final part of your output should resemble this (the numbers can change slightly):

Regression Coefficients:
           Estimate Est.Error l-95% CI u-95% CI Rhat Bulk_ESS Tail_ESS
Intercept      1.77      0.12     1.53     2.00 1.00      642     1149
zAge           0.10      0.09    -0.07     0.27 1.00      690      873
zBase          0.70      0.12     0.46     0.95 1.00      591     1080
Trt1          -0.26      0.16    -0.58     0.05 1.00      699     1319
zBase:Trt1     0.05      0.17    -0.29     0.38 1.00      681     1115

1.2.3 Faster brms with cmdstanr

brms interfaces with Stan using a backend. The default backend is rstan, which does not require any additional installation but is somewhat slow. An alternative backend is cmdstanr, which needs to be installed separately but is much faster than rstan. Although tedious, the extra setup is well worth the effort.

To install cmdstanr, first download the package in R:

# Run this in a fresh R session or after restarting your current session
install.packages(
    pkgs = "cmdstanr",
    repos = c('https://stan-dev.r-universe.dev', getOption("repos"))
)

Verify that the C++ toolchain also works with cmdstanr:

library(cmdstanr)
check_cmdstan_toolchain()
The C++ toolchain required for CmdStan is setup properly!

Now R can configure cmdstanr for us. This process can take a few minutes. Ignore all the weird messages that will appear; we care only about warnings and errors.

install_cmdstan(cores = 2)

Finally, verify that brms can call cmdstanr:

library(brms)
options(brms.backend = 'cmdstanr') # This forces brms to use cmdstanr
fit1 <- brm(count ~ zAge + zBase * Trt + (1|patient),
            data = epilepsy, family = poisson())
summary(fit1)

A successful model run means a successful installation. brms is ready.