# brms v2.9.0

Monthly downloads

## Bayesian Regression Models using 'Stan'

Fit Bayesian generalized (non-)linear multivariate multilevel models
using 'Stan' for full Bayesian inference. A wide range of distributions
and link functions are supported, allowing users to fit -- among others --
linear, robust linear, count data, survival, response times, ordinal,
zero-inflated, hurdle, and even self-defined mixture models all in a
multilevel context. Further modeling options include non-linear and
smooth terms, auto-correlation structures, censored data, meta-analytic
standard errors, and quite a few more. In addition, all parameters of the
response distribution can be predicted in order to perform distributional
regression. Prior specifications are flexible and explicitly encourage
users to apply prior distributions that actually reflect their beliefs.
Model fit can easily be assessed and compared with posterior predictive
checks and leave-one-out cross-validation. References: B<c3><bc>rkner (2017)
<doi:10.18637/jss.v080.i01>; Carpenter et al. (2017) <doi:10.18637/jss.v076.i01>.

## Readme

# brms

## Overview

The **brms** package provides an interface to fit Bayesian generalized
(non-)linear multivariate multilevel models using Stan, which is a C++
package for performing full Bayesian inference (see
http://mc-stan.org/). The formula syntax is very similar to that of
the package lme4 to provide a familiar and simple interface for
performing regression analyses. A wide range of response distributions
are supported, allowing users to fit – among others – linear, robust
linear, count data, survival, response times, ordinal, zero-inflated,
and even self-defined mixture models all in a multilevel context.
Further modeling options include non-linear and smooth terms,
auto-correlation structures, censored data, missing value imputation,
and quite a few more. In addition, all parameters of the response
distribution can be predicted in order to perform distributional
regression. Multivariate models (i.e., models with multiple response
variables) can be fit, as well. Prior specifications are flexible and
explicitly encourage users to apply prior distributions that actually
reflect their beliefs. Model fit can easily be assessed and compared
with posterior predictive checks, cross-validation, and Bayes factors.

## Resources

- Introduction to brms (Journal of Statistical Software)
- Advanced multilevel modeling with brms (The R Journal)
- Website (Website of brms with documentation and vignettes)
- Blog posts (List of blog posts about brms)
- Ask a question (Stan Forums on Discourse)
- Open an issue (GitHub issues for bug reports and feature requests)

## How to use brms

```
library(brms)
```

As a simple example, we use poisson regression to model the seizure
counts in epileptic patients to investigate whether the treatment
(represented by variable `Trt`

) can reduce the seizure counts and
whether the effect of the treatment varies with the (standardized)
baseline number of seizures a person had before treatment (variable
`zBase`

). As we have multiple observations per person, a group-level
intercept is incorporated to account for the resulting dependency in the
data.

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

The results (i.e., posterior samples) can be investigated using

```
summary(fit1)
#> Family: poisson
#> Links: mu = log
#> Formula: count ~ zAge + zBase * Trt + (1 | patient)
#> Data: epilepsy (Number of observations: 236)
#> Samples: 4 chains, each with iter = 2000; warmup = 1000; thin = 1;
#> total post-warmup samples = 4000
#>
#> Group-Level Effects:
#> ~patient (Number of levels: 59)
#> Estimate Est.Error l-95% CI u-95% CI Eff.Sample Rhat
#> sd(Intercept) 0.59 0.07 0.47 0.74 786 1.00
#>
#> Population-Level Effects:
#> Estimate Est.Error l-95% CI u-95% CI Eff.Sample Rhat
#> Intercept 1.78 0.12 1.53 2.02 691 1.01
#> zAge 0.09 0.09 -0.08 0.27 758 1.00
#> zBase 0.70 0.12 0.47 0.96 496 1.01
#> Trt1 -0.27 0.17 -0.62 0.06 650 1.01
#> zBase:Trt1 0.06 0.17 -0.27 0.38 557 1.01
#>
#> Samples were drawn using sampling(NUTS). For each parameter, Eff.Sample
#> is a crude measure of effective sample size, and Rhat is the potential
#> scale reduction factor on split chains (at convergence, Rhat = 1).
```

On the top of the output, some general information on the model is given, such as family, formula, number of iterations and chains. Next, group-level effects are displayed seperately for each grouping factor in terms of standard deviations and (in case of more than one group-level effect per grouping factor; not displayed here) correlations between group-level effects. On the bottom of the output, population-level effects (i.e. regression coefficients) are displayed. If incorporated, autocorrelation effects and family specific parameters (e.g. the residual standard deviation ‘sigma’ in normal models) are also given.

In general, every parameter is summarized using the mean (‘Estimate’)
and the standard deviation (‘Est.Error’) of the posterior distribution
as well as two-sided 95% credible intervals (‘l-95% CI’ and ‘u-95% CI’)
based on quantiles. We see that the coefficient of `Trt`

is negative
with a completely negative 95%-CI indicating that, on average, the
treatment reduces seizure counts by some amount. Further, we find little
evidence that the treatment effect varies with the baseline number of
seizures.

The last two values (‘Eff.Sample’ and ‘Rhat’) provide information on how well the algorithm could estimate the posterior distribution of this parameter. If ‘Rhat’ is considerably greater than 1, the algorithm has not yet converged and it is necessary to run more iterations and / or set stronger priors.

To visually investigate the chains as well as the posterior
distributions, we can use the `plot`

method. If we just want to see
results of the regression coefficients of `Trt`

and `zBase`

, we go for

```
plot(fit1, pars = c("Trt", "zBase"))
```

A more detailed investigation can be performed by running
`launch_shinystan(fit1)`

. To better understand the relationship of the
predictors with the response, I recommend the `marginal_effects`

method:

```
plot(marginal_effects(fit1, effects = "zBase:Trt"))
```

This method uses some prediction functionality behind the scenes, which
can also be called directly. Suppose that we want to predict responses
(i.e. seizure counts) of a person in the treatment group (`Trt = 1`

) and
in the control group (`Trt = 0`

) with average age and average number of
previous seizures. Than we can use

```
newdata <- data.frame(Trt = c(0, 1), zAge = 0, zBase = 0)
predict(fit1, newdata = newdata, re_formula = NA)
#> Estimate Est.Error Q2.5 Q97.5
#> [1,] 5.973 2.567181 2 12
#> [2,] 4.548 2.129984 1 9
```

We need to set `re_formula = NA`

in order not to condition of the
group-level effects. While the `predict`

method returns predictions of
the responses, the `fitted`

method returns predictions of the regression
line.

```
fitted(fit1, newdata = newdata, re_formula = NA)
#> Estimate Est.Error Q2.5 Q97.5
#> [1,] 5.946417 0.7422929 4.637616 7.540027
#> [2,] 4.535893 0.5274356 3.588178 5.640799
```

Both methods return the same estimate (up to random error), while the
latter has smaller variance, because the uncertainty in the regression
line is smaller than the uncertainty in each response. If we want to
predict values of the original data, we can just leave the `newdata`

argument empty.

Suppose, we want to investigate whether there is overdispersion in the model, that is residual variation not accounted for by the response distribution. For this purpose, we include a second group-level intercept that captures possible overdispersion.

```
fit2 <- brm(count ~ zAge + zBase * Trt + (1|patient) + (1|obs),
data = epilepsy, family = poisson())
```

We can then go ahead and compare both models via approximate leave-one-out cross-validation.

```
loo(fit1, fit2)
#> LOOIC SE
#> fit1 1344.40 75.20
#> fit2 1183.91 27.21
#> fit1 - fit2 160.48 57.69
```

Since higher `LOOIC`

values indicate better fit, we see that the model
accounting for overdispersion fits substantially better. The
post-processing methods we have shown so far are just the tip of the
iceberg. For a full list of methods to apply on fitted model objects,
type `methods(class = "brmsfit")`

.

## Citing brms and related software

Developing and maintaining open source software is an important yet often underappreciated contribution to scientific progress. Thus, whenever you are using open source software (or software in general), please make sure to cite it appropriately so that developers get credit for their work.

When using brms, please cite one or more of the following publications:

- Bürkner P. C. (2017). brms: An R Package for Bayesian Multilevel
Models using Stan.
*Journal of Statistical Software*. 80(1), 1-28. doi.org/10.18637/jss.v080.i01 - Bürkner P. C. (2018). Advanced Bayesian Multilevel Modeling with the
R Package brms.
*The R Journal*. 10(1), 395-411. doi.org/10.32614/RJ-2018-017

As brms is a high-level interface to Stan, please additionally cite Stan:

- Carpenter B., Gelman A., Hoffman M. D., Lee D., Goodrich B.,
Betancourt M., Brubaker M., Guo J., Li P., and Riddell A. (2017).
Stan: A probabilistic programming language.
*Journal of Statistical Software*. 76(1). 10.18637/jss.v076.i01

Further, brms relies on several other R packages and, of course, on R
itself. To find out how to cite R and its packages, use the `citation`

function. There are some features of brms which specifically rely on
certain packages. The **rstan** package together with **Rcpp** makes
Stan conveniently accessible in R. Visualizations and
posterior-predictive checks are based on **bayesplot** and **ggplot2**.
Approximate leave-one-out cross-validation using `loo`

and related
methods is done via the **loo** package. Marginal likelihood based
methods such as `bayes_factor`

are realized by means of the
**bridgesampling** package. Splines specified via the `s`

and `t2`

functions rely on **mgcv**. If you use some of these features, please
also consider citing the related packages.

## FAQ

### How do I install brms?

To install the latest release version from CRAN use

```
install.packages("brms")
```

The current developmental version can be downloaded from github via

```
if (!requireNamespace("devtools")) {
install.packages("devtools")
}
devtools::install_github("paul-buerkner/brms")
```

Because brms is based on Stan, a C++ compiler is required. The program Rtools (available on https://cran.r-project.org/bin/windows/Rtools/) comes with a C++ compiler for Windows. On Mac, you should install Xcode. For further instructions on how to get the compilers running, see the prerequisites section on https://github.com/stan-dev/rstan/wiki/RStan-Getting-Started.

### I am new to brms. Where can I start?

Detailed instructions and case studies are given in the package’s
extensive vignettes. See `vignette(package = "brms")`

for an overview.
For documentation on formula syntax, families, and prior distributions
see `help("brm")`

.

### Where do I ask questions, propose a new feature, or report a bug?

Questions can be asked on the Stan forums on Discourse. To propose a new feature or report a bug, please open an issue on GitHub.

### How can I extract the generated Stan code?

If you have already fitted a model, just apply the `stancode`

method on
the fitted model object. If you just want to generate the Stan code
without any model fitting, use the `make_stancode`

function.

### Can I avoid compiling models?

When you fit your model for the first time with brms, there is currently
no way to avoid compilation. However, if you have already fitted your
model and want to run it again, for instance with more samples, you can
do this without recompilation by using the `update`

method. For more
details see `help("update.brmsfit")`

.

### What is the difference between brms and rstanarm?

The rstanarm package is similar to brms in that it also allows to fit
regression models using Stan for the backend estimation. Contrary to
brms, rstanarm comes with precompiled code to save the compilation time
(and the need for a C++ compiler) when fitting a model. However, as brms
generates its Stan code on the fly, it offers much more flexibility in
model specification than rstanarm. Also, multilevel models are currently
fitted a bit more efficiently in brms. For detailed comparisons of brms
with other common R packages implementing multilevel models, see
`vignette("brms_multilevel")`

and `vignette("brms_overview")`

.

## Functions in brms

Name | Description | |

AsymLaplace | The Asymmetric Laplace Distribution | |

SkewNormal | The Skew-Normal Distribution | |

StudentT | The Student-t Distribution | |

brms-package | Bayesian Regression Models using 'Stan' | |

brmsfamily | Special Family Functions for brms Models | |

compare_ic | Compare Information Criteria of Different Models | |

control_params.brmsfit | Extract Control Parameters of the NUTS Sampler | |

cor_fixed | Fixed user-defined covariance matrices | |

cor_ma | MA(q) correlation structure | |

epilepsy | Epileptic seizure counts | |

MultiStudentT | The Multivariate Student-t Distribution | |

Shifted_Lognormal | The Shifted Log Normal Distribution | |

expose_functions.brmsfit | Expose user-defined Stan functions | |

horseshoe | Set up a horseshoe prior in brms | |

hypothesis.brmsfit | Non-Linear Hypothesis Testing | |

add_criterion | Add model fit criteria to model objects | |

add_ic | Add model fit criteria to model objects | |

launch_shinystan.brmsfit | Interface to shinystan | |

autocor | Extract Autocorrelation Structures | |

bayes_R2.brmsfit | Compute a Bayesian version of R-squared for regression models | |

log_lik.brmsfit | Compute the Pointwise Log-Likelihood | |

cor_arr | (Defunct) ARR correlation structure | |

cor_brms | Correlation structure classes for the brms package | |

cor_bsts | (Defunct) Basic Bayesian Structural Time Series | |

logit_scaled | Scaled logit-link | |

logm1 | Logarithm with a minus one offset. | |

marginal_effects.brmsfit | Display Marginal Effects of Predictors | |

marginal_smooths.brmsfit | Display Smooth Terms | |

plot.brmsfit | Trace and Density Plots for MCMC Samples | |

cor_car | Spatial conditional autoregressive (CAR) structures | |

fitted.brmsfit | Extract Model Fitted Values of brmsfit Objects | |

post_prob.brmsfit | Posterior Model Probabilities from Marginal Likelihoods | |

pp_check.brmsfit | Posterior Predictive Checks for brmsfit Objects | |

fixef.brmsfit | Extract Population-Level Estimates | |

inhaler | Clarity of inhaler instructions | |

inv_logit_scaled | Scaled inverse logit-link | |

pp_mixture.brmsfit | Posterior Probabilities of Mixture Component Memberships | |

kidney | Infections in kidney patients | |

lasso | Set up a lasso prior in brms | |

residuals.brmsfit | Extract Model Residuals from brmsfit Objects | |

loo_predict.brmsfit | Compute Weighted Expectations Using LOO | |

make_conditions | Prepare Fully Crossed Conditions | |

restructure | Restructure Old brmsfit Objects | |

stanvar | User-defined variables passed to Stan | |

mixture | Finite Mixture Families in brms | |

summary.brmsfit | Create a summary of a fitted model represented by a brmsfit object | |

mm | Set up multi-membership grouping terms in brms | |

nsamples.brmsfit | Number of Posterior Samples | |

Frechet | The Frechet Distribution | |

ExGaussian | The Exponentially Modified Gaussian Distribution | |

print.brmsfit | Print a summary for a fitted model represented by a brmsfit object | |

pairs.brmsfit | Create a matrix of output plots from a brmsfit object | |

print.brmsprior | Print method for brmsprior objects | |

ranef.brmsfit | Extract Group-Level Estimates | |

VonMises | The von Mises Distribution | |

brm_multiple | Run the same brms model on multiple datasets | |

VarCorr.brmsfit | Extract Variance and Correlation Components | |

brm | Fit Bayesian Generalized (Non-)Linear Multivariate Multilevel Models | |

reloo | Compute exact cross-validation for problematic observations | |

standata.brmsfit | Extract Data passed to Stan | |

brmsformula | Set up a model formula for use in brms | |

Wiener | The Wiener Diffusion Model Distribution | |

Hurdle | Hurdle Distributions | |

brmshypothesis | Descriptions of brmshypothesis Objects | |

GenExtremeValue | The Generalized Extreme Value Distribution | |

ZeroInflated | Zero-Inflated Distributions | |

bayes_factor.brmsfit | Bayes Factors from Marginal Likelihoods | |

bridge_sampler.brmsfit | Log Marginal Likelihood via Bridge Sampling | |

cor_ar | AR(p) correlation structure | |

stanplot.brmsfit | MCMC Plots Implemented in bayesplot | |

cor_arma | ARMA(p,q) correlation structure | |

cor_sar | Spatial simultaneous autoregressive (SAR) structures | |

data_response | Prepare Response Data | |

density_ratio | Compute Density Ratios | |

log_posterior.brmsfit | Extract Diagnostic Quantities of brms Models | |

cs | Category Specific Predictors in brms Models | |

expp1 | Exponential function plus one. | |

extract_draws.brmsfit | Extract Data and Posterior Draws | |

do_call | Execute a Function Call | |

is.brmsformula | Checks if argument is a brmsformula object | |

InvGaussian | The Inverse Gaussian Distribution | |

MultiNormal | The Multivariate Normal Distribution | |

as.mcmc.brmsfit | Extract posterior samples for use with the coda package | |

addition-terms | Additional Response Information | |

is.brmsfit | Checks if argument is a brmsfit object | |

is.brmsfit_multiple | Checks if argument is a brmsfit_multiple object | |

is.brmsprior | Checks if argument is a brmsprior object | |

brmsfit-class | Class brmsfit of models fitted with the brms package | |

brmsformula-helpers | Linear and Non-linear formulas in brms | |

coef.brmsfit | Extract Model Coefficients | |

kfold.brmsfit | K-Fold Cross-Validation | |

is.mvbrmsformula | Checks if argument is a mvbrmsformula object | |

kfold_predict | Predictions from K-Fold Cross-Validation | |

make_stancode | Stan Code for brms Models | |

loo_model_weights.brmsfit | Model averaging via stacking or pseudo-BMA weighting. | |

loo_compare.brmsfit | Model comparison with the loo package | |

is.mvbrmsterms | Checks if argument is a mvbrmsterms object | |

make_standata | Data for brms Models | |

combine_models | Combine Models fitted with brms | |

custom_family | Custom Families in brms Models | |

mo | Monotonic Predictors in brms Models | |

mmc | Multi-Membership Covariates | |

parnames | Extract Parameter Names | |

parse_bf | Parse Formulas of brms Models | |

me | Predictors with Measurement Error in brms Models | |

mi | Predictors with Missing Values in brms Models | |

posterior_average.brmsfit | Posterior samples of parameters averaged across models | |

posterior_interval.brmsfit | Compute posterior uncertainty intervals | |

posterior_samples.brmsfit | Extract posterior samples | |

posterior_summary.brmsfit | Summarize Posterior Samples | |

data_predictor | Prepare Predictor Data | |

rows2labels | Convert Rows to Labels | |

s | Defining smooths in brms formulas | |

update_adterms | Update Formula Addition Terms | |

pp_average.brmsfit | Posterior predictive samples averaged across models | |

posterior_table | Table Creation for Posterior Samples | |

set_prior | Prior Definitions for brms Models | |

theme_black | Black Theme for ggplot2 Graphics | |

stancode.brmsfit | Extract Stan model code | |

validate_newdata | Validate New Data | |

get_prior | Overview on Priors for brms Models | |

theme_default | Default bayesplot Theme for ggplot2 Graphics | |

vcov.brmsfit | Covariance and Correlation Matrix of Population-Level Effects | |

gp | Set up Gaussian process terms in brms | |

get_y | Extract response values | |

gr | Set up basic grouping terms in brms | |

is.brmsterms | Checks if argument is a brmsterms object | |

is.cor_brms | Check if argument is a correlation structure | |

waic.brmsfit | Widely Applicable Information Criterion (WAIC) | |

loo.brmsfit | Efficient approximate leave-one-out cross-validation (LOO) | |

loo_R2.brmsfit | Compute a LOO-adjusted R-squared for regression models | |

model_weights.brmsfit | Model Weighting Methods | |

mvbind | Bind response variables in multivariate models | |

mvbrmsformula | Set up a multivariate model formula for use in brms | |

ngrps.brmsfit | Number of levels | |

predictive_interval.brmsfit | Predictive Intervals | |

predict.brmsfit | Model Predictions of brmsfit Objects | |

prior_samples.brmsfit | Extract prior samples | |

prior_summary.brmsfit | Extract Priors of a Bayesian Model Fitted with brms | |

update.brmsfit | Update brms models | |

update.brmsfit_multiple | Update brms models based on multiple data sets | |

Dirichlet | The Dirichlet Distribution | |

No Results! |

## Vignettes of brms

## Last month downloads

## Details

Encoding | UTF-8 |

Type | Package |

Date | 2019-05-21 |

LazyData | true |

NeedsCompilation | no |

License | GPL (>= 3) |

URL | https://github.com/paul-buerkner/brms, http://discourse.mc-stan.org |

BugReports | https://github.com/paul-buerkner/brms/issues |

VignetteBuilder | knitr, R.rsp |

RoxygenNote | 6.1.1 |

Packaged | 2019-05-22 19:53:49 UTC; paulb |

Repository | CRAN |

Date/Publication | 2019-05-23 05:00:27 UTC |

imports | abind , backports , bayesplot (>= 1.5.0) , bridgesampling (>= 0.3-0) , coda , future , ggplot2 (>= 2.0.0) , glue (>= 1.3.0) , grDevices , loo (>= 2.1.0) , Matrix (>= 1.1.1) , matrixStats , mgcv (>= 1.8-13) , nleqslv , nlme , parallel , rstan (>= 2.17.2) , rstantools (>= 1.3.0) , shinystan (>= 2.4.0) , stats , utils |

suggests | ape , arm , digest , knitr , lme4 , MCMCglmm , mice , mnormt , R.rsp , rmarkdown , RWiener , spdep , statmod , testthat (>= 0.9.1) |

depends | methods , R (>= 3.5.0) , Rcpp (>= 0.12.0) |

Contributors |

#### Include our badge in your README

```
[![Rdoc](http://www.rdocumentation.org/badges/version/brms)](http://www.rdocumentation.org/packages/brms)
```