brms v2.14.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>; B<c3><bc>rkner (2018) <doi:10.32614/RJ-2018-017>; Carpenter et al. (2017) <doi:10.18637/jss.v076.i01>.


brms LogoStan Logo


Status Coverage
Status CRAN
Version Downloads


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


How to use 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

#>  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 Rhat Bulk_ESS Tail_ESS
#> sd(Intercept)     0.58      0.07     0.46     0.74 1.00      810     1753
#> Population-Level Effects: 
#>            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      779     1319
#> zAge           0.09      0.09    -0.09     0.26 1.00      683     1071
#> zBase          0.70      0.12     0.46     0.95 1.00      847     1453
#> Trt1          -0.27      0.17    -0.59     0.06 1.00      661     1046
#> zBase:Trt1     0.05      0.16    -0.26     0.37 1.00      993     1624
#> Samples were drawn using sampling(NUTS). For each parameter, Bulk_ESS
#> and Tail_ESS are effective sample size measures, 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 zero overlapping 95%-CI. This indicates that, on average, the treatment may reduce seizure counts by some amount but the evidence based on the data and applied model is not very strong and still insufficient by standard decision rules. 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 conditional_effects method:

plot(conditional_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.8980  2.505627    2    11
#> [2,]   4.5595  2.162320    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.917144 0.7056695 4.632004 7.387471
#> [2,] 4.529949 0.5360204 3.544085 5.624005

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 (LOO) cross-validation.

loo(fit1, fit2)
#> Output of model 'fit1':
#> Computed from 4000 by 236 log-likelihood matrix
#>          Estimate   SE
#> elpd_loo   -670.4 36.7
#> p_loo        92.8 14.3
#> looic      1340.8 73.3
#> ------
#> Monte Carlo SE of elpd_loo is NA.
#> Pareto k diagnostic values:
#>                          Count Pct.    Min. n_eff
#> (-Inf, 0.5]   (good)     214   90.7%   251       
#>  (0.5, 0.7]   (ok)        17    7.2%   80        
#>    (0.7, 1]   (bad)        3    1.3%   81        
#>    (1, Inf)   (very bad)   2    0.8%   6         
#> See help('pareto-k-diagnostic') for details.
#> Output of model 'fit2':
#> Computed from 4000 by 236 log-likelihood matrix
#>          Estimate   SE
#> elpd_loo   -595.2 14.1
#> p_loo       108.0  7.3
#> looic      1190.4 28.2
#> ------
#> Monte Carlo SE of elpd_loo is NA.
#> Pareto k diagnostic values:
#>                          Count Pct.    Min. n_eff
#> (-Inf, 0.5]   (good)      82   34.7%   544       
#>  (0.5, 0.7]   (ok)       103   43.6%   153       
#>    (0.7, 1]   (bad)       47   19.9%   22        
#>    (1, Inf)   (very bad)   4    1.7%   7         
#> See help('pareto-k-diagnostic') for details.
#> Model comparisons:
#>      elpd_diff se_diff
#> fit2   0.0       0.0  
#> fit1 -75.2      26.9

The loo output when comparing models is a little verbose. We first see the individual LOO summaries of the two models and then the comparison between them. Since higher elpd (i.e., expected log posterior density) values indicate better fit, we see that the model accounting for overdispersion (i.e., fit2) fits substantially better. However, we also see in the individual LOO outputs that there are several problematic observations for which the approximations may have not have been very accurate. To deal with this appropriately, we need to fall back to other methods such as reloo or kfold but this requires the model to be refit several times which takes too long for the purpose of a quick example. The post-processing methods we have shown above are just the tip of the iceberg. For a full list of methods to apply on fitted model objects, type methods(class = "brmsfit").

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.
  • Bürkner P. C. (2018). Advanced Bayesian Multilevel Modeling with the R Package brms. The R Journal. 10(1), 395-411.

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.


How do I install brms?

To install the latest release version from CRAN use


The current developmental version can be downloaded from github via

if (!requireNamespace("remotes")) {

Because brms is based on Stan, a C++ compiler is required. The program Rtools (available on 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

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
Shifted_Lognormal The Shifted Log Normal Distribution
GenExtremeValue The Generalized Extreme Value Distribution
Dirichlet The Dirichlet Distribution
ExGaussian The Exponentially Modified Gaussian Distribution
Frechet The Frechet Distribution
AsymLaplace The Asymmetric Laplace Distribution
InvGaussian The Inverse Gaussian Distribution
MultiStudentT The Multivariate Student-t Distribution
MultiNormal The Multivariate Normal Distribution
Wiener The Wiener Diffusion Model Distribution
StudentT The Student-t Distribution
SkewNormal The Skew-Normal Distribution
ZeroInflated Zero-Inflated Distributions
ar Set up AR(p) correlation structures
autocor.brmsfit (Deprecated) Extract Autocorrelation Objects
autocor-terms Autocorrelation structures
as.mcmc.brmsfit Extract posterior samples for use with the coda package
arma Set up ARMA(p,q) correlation structures
brm Fit Bayesian Generalized (Non-)Linear Multivariate Multilevel Models
bridge_sampler.brmsfit Log Marginal Likelihood via Bridge Sampling
brms-package Bayesian Regression Models using 'Stan'
brm_multiple Run the same brms model on multiple datasets
VarCorr.brmsfit Extract Variance and Correlation Components
add_criterion Add model fit criteria to model objects
add_loo Add model fit criteria to model objects
VonMises The von Mises Distribution
bayes_R2.brmsfit Compute a Bayesian version of R-squared for regression models
bayes_factor.brmsfit Bayes Factors from Marginal Likelihoods
Hurdle Hurdle Distributions
addition-terms Additional Response Information
brmshypothesis Descriptions of brmshypothesis Objects
compare_ic Compare Information Criteria of Different Models
combine_models Combine Models fitted with brms
brmsfamily Special Family Functions for brms Models
brmsfit-class Class brmsfit of models fitted with the brms package
brmsformula-helpers Linear and Non-linear formulas in brms
brmsformula Set up a model formula for use in brms
brmsterms Parse Formulas of brms Models
cor_car (Deprecated) Spatial conditional autoregressive (CAR) structures
cor_cosy (Deprecated) Compound Symmetry (COSY) Correlation Structure
car Spatial conditional autoregressive (CAR) structures
coef.brmsfit Extract Model Coefficients
cor_ar (Deprecated) AR(p) correlation structure
cor_brms (Deprecated) Correlation structure classes for the brms package
control_params Extract Control Parameters of the NUTS Sampler
cor_bsts (Defunct) Basic Bayesian Structural Time Series
cor_arma (Deprecated) ARMA(p,q) correlation structure
cor_arr (Defunct) ARR correlation structure
conditional_effects.brmsfit Display Conditional Effects of Predictors
cosy Set up COSY correlation structures
cor_sar (Deprecated) Spatial simultaneous autoregressive (SAR) structures
expose_functions.brmsfit Expose user-defined Stan functions
cor_ma (Deprecated) MA(q) correlation structure
conditional_smooths.brmsfit Display Smooth Terms
density_ratio Compute Density Ratios
cor_fixed (Deprecated) Fixed user-defined covariance matrices
epilepsy Epileptic seizure counts
fixef.brmsfit Extract Population-Level Estimates
diagnostic-quantities Extract Diagnostic Quantities of brms Models
cs Category Specific Predictors in brms Models
data_predictor Prepare Predictor Data
hypothesis.brmsfit Non-Linear Hypothesis Testing
is.brmsprior Checks if argument is a brmsprior object
get_prior Overview on Priors for brms Models
is.brmsterms Checks if argument is a brmsterms object
expp1 Exponential function plus one.
get_y Extract response values
gp Set up Gaussian process terms in brms
is.cor_brms Check if argument is a correlation structure
is.mvbrmsformula Checks if argument is a mvbrmsformula object
family.brmsfit Extract Model Family Objects
data_response Prepare Response Data
logm1 Logarithm with a minus one offset.
is.brmsfit_multiple Checks if argument is a brmsfit_multiple object
is.brmsformula Checks if argument is a brmsformula object
kfold_predict Predictions from K-Fold Cross-Validation
lasso Set up a lasso prior in brms
inhaler Clarity of inhaler instructions
fcor Fixed residual correlation (FCOR) structures
fitted.brmsfit Expected Values of the Posterior Predictive Distribution
inv_logit_scaled Scaled inverse logit-link
launch_shinystan.brmsfit Interface to shinystan
custom_family Custom Families in brms Models
do_call Execute a Function Call
loo.brmsfit Efficient approximate leave-one-out cross-validation (LOO)
emmeans-brms-helpers Support Functions for emmeans
is.brmsfit Checks if argument is a brmsfit object
is.mvbrmsterms Checks if argument is a mvbrmsterms object
mixture Finite Mixture Families in brms
mm Set up multi-membership grouping terms in brms
loo_subsample.brmsfit Efficient approximate leave-one-out cross-validation (LOO) using subsampling
loo_predict.brmsfit Compute Weighted Expectations Using LOO
gr Set up basic grouping terms in brms
kfold.brmsfit K-Fold Cross-Validation
loo_model_weights.brmsfit Model averaging via stacking or pseudo-BMA weighting.
make_conditions Prepare Fully Crossed Conditions
make_stancode Stan Code for brms Models
loo_moment_match.brmsfit Moment matching for efficient approximate leave-one-out cross-validation
me Predictors with Measurement Error in brms Models
kidney Infections in kidney patients
loo_R2.brmsfit Compute a LOO-adjusted R-squared for regression models
mvbind Bind response variables in multivariate models
model_weights.brmsfit Model Weighting Methods
posterior_epred.brmsfit Expected Values of the Posterior Predictive Distribution
mmc Multi-Membership Covariates
mi Predictors with Missing Values in brms Models
horseshoe Regularized horseshoe priors in brms
mo Monotonic Predictors in brms Models
posterior_interval.brmsfit Compute posterior uncertainty intervals
rows2labels Convert Rows to Labels
ngrps.brmsfit Number of Grouping Factor Levels
mvbrmsformula Set up a multivariate model formula for use in brms
s Defining smooths in brms formulas
posterior_smooths.brmsfit Posterior Predictions of Smooth Terms
posterior_samples.brmsfit Extract Posterior Samples
log_lik.brmsfit Compute the Pointwise Log-Likelihood
pp_check.brmsfit Posterior Predictive Checks for brmsfit Objects
logit_scaled Scaled logit-link
pp_average.brmsfit Posterior predictive samples averaged across models
posterior_summary Summarize Posterior Samples
make_standata Data for brms Models
loo_compare.brmsfit Model comparison with the loo package
mcmc_plot.brmsfit MCMC Plots Implemented in bayesplot
nsamples.brmsfit Number of Posterior Samples
update.brmsfit Update brms models
update.brmsfit_multiple Update brms models based on multiple data sets
posterior_linpred.brmsfit Posterior Samples of the Linear Predictor
restructure Restructure Old brmsfit Objects
prior_samples.brmsfit Extract prior samples
pairs.brmsfit Create a matrix of output plots from a brmsfit object
residuals.brmsfit Posterior Samples of Residuals/Predictive Errors
posterior_predict.brmsfit Samples from the Posterior Predictive Distribution
print.brmsprior Print method for brmsprior objects
theme_default Default bayesplot Theme for ggplot2 Graphics
loss Cumulative Insurance Loss Payments
pp_mixture.brmsfit Posterior Probabilities of Mixture Component Memberships
ma Set up MA(q) correlation structures
threading Threading in Stan
prepare_predictions.brmsfit Prepare Predictions
posterior_table Table Creation for Posterior Samples
parnames Extract Parameter Names
predict.brmsfit Samples from the Posterior Predictive Distribution
standata.brmsfit Extract data passed to Stan
stanvar User-defined variables passed to Stan
vcov.brmsfit Covariance and Correlation Matrix of Population-Level Effects
waic.brmsfit Widely Applicable Information Criterion (WAIC)
plot.brmsfit Trace and Density Plots for MCMC Samples
print.brmsfit Print a summary for a fitted model represented by a brmsfit object
rename_pars Rename Parameters
stancode.brmsfit Extract Stan model code
reloo.brmsfit Compute exact cross-validation for problematic observations
set_prior Prior Definitions for brms Models
update_adterms Update Formula Addition Terms
sar Spatial simultaneous autoregressive (SAR) structures
save_pars Control Saving of Parameter Draws
post_prob.brmsfit Posterior Model Probabilities from Marginal Likelihoods
validate_newdata Validate New Data
posterior_average.brmsfit Posterior samples of parameters averaged across models
predictive_error.brmsfit Posterior Samples of Predictive Errors
summary.brmsfit Create a summary of a fitted model represented by a brmsfit object
theme_black (Deprecated) Black Theme for ggplot2 Graphics
ranef.brmsfit Extract Group-Level Estimates
predictive_interval.brmsfit Predictive Intervals
prior_summary.brmsfit Extract Priors of a Bayesian Model Fitted with brms
No Results!

Vignettes of brms

No Results!

Last month downloads


Include our badge in your README