intro-brms.qmd

# Introducing `brms`

## What is `brms`?

`brms` [@brms2017] is an R library for **b**ayesian **r**egression **m**odels
using **S**tan:

+ 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 [@stan_manual_2026].

`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.

## 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. When we last checked, R version 4.6.1 was
available

### 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](https://cran.r-project.org/bin/windows/Rtools/rtools45/rtools.html).
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
```

::: {.callout-warning}
### Install 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.
:::

### Default version of brms

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

```{r install brms}
install.packages("brms")
```

Run the commands below to verify that `brms` works properly.

```{r test brms installation}
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
```

### Faster brms with cmdstanr

By default, `brms` interfaces with Stan in the background using `rstan`,
which does not require any additional installation but is somewhat slow. An
alternative is to use `cmdstanr` [@cmdstanr2025], 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:

```{r run cmdstanr installation}
# 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`:

```{r check cmdstan toolchain}
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.

```{r install cmdstan}
install_cmdstan(cores = 2)
```

Finally, verify that `brms` can call `cmdstanr`:

```{r test brms with 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.