Package ‘brms’ - Michigan Technological University · Package ‘brms ’ February 15, 2016 ... Gamma, inverse.gaussian, exponential, weibull, ... tions and brmsfamily for family

Package ‘brms’February 15, 2016

Type Package

Title Bayesian Regression Models using Stan

Version 0.8.0

Date 2016-02-15

Depends R (>= 3.1.0), rstan (>= 2.9.0), ggplot2 (>= 2.0.0), methods

Imports loo (>= 0.1.4), shinystan (>= 2.1.0), gridExtra (>= 2.0.0),lme4 (>= 1.1-11), Matrix (>= 1.1.1), coda, abind, statmod,stats, graphics, utils, parallel, grDevices, grid

Suggests testthat (>= 0.9.1), mvtnorm, KernSmooth, R.rsp, knitr,rmarkdown

Description Fit Bayesian generalized (non-)linear mixed models using Stan for fullBayesian inference.

LazyData true

NeedsCompilation yes

License GPL (>= 3)

URL http://github.com/paul-buerkner/brms

BugReports http://github.com/paul-buerkner/brms/issues

VignetteBuilder R.rsp, knitr

RoxygenNote 5.0.1

Author Paul-Christian Buerkner [aut, cre]

Maintainer Paul-Christian Buerkner <[email protected]>

Repository CRAN

Date/Publication 2016-02-15 23:59:08

R topics documented:brms-package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3as.mcmc.brmsfit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4brm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

1

http://github.com/paul-buerkner/brms

http://github.com/paul-buerkner/brms/issues

2 R topics documented:

brmsfamily . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12brmsfit-class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13coef.brmsfit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14cor_ar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15cor_arma . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16cor_arr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18cor_brms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19cor_ma . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19epilepsy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20fitted.brmsfit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21fixef.brmsfit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23get_prior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24hypothesis.brmsfit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26inhaler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28kidney . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29launch_shiny . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30logLik.brmsfit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31LOO.brmsfit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31make_stancode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33make_standata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35marginal_effects.brmsfit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37ngrps.brmsfit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38pairs.brmsfit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39parnames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40plot.brmsfit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40posterior_samples.brmsfit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41predict.brmsfit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43print.brmsfit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45prior_samples.brmsfit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45ranef.brmsfit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46residuals.brmsfit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47set_prior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49stancode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52standata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53stanplot.brmsfit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53summary.brmsfit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55update.brmsfit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55VarCorr.brmsfit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56vcov.brmsfit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57WAIC.brmsfit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Index 60

brms-package 3

brms-package Bayesian Regression Models using Stan

Description

The brms package provides an interface to fit Bayesian generalized (non)-linear mixed modelsusing Stan, which is a C++ package for obtaining Bayesian inference using the No-U-turn sampler(see http://mc-stan.org/). The formula syntax is very similar to that of the package lme4 toprovide a familiar and simple interface for performing regression analyses.

Details

The main function of the brms package is brm, which creates the model in Stan language and fitsit using Stan. Subsequently, a large number of methods can be applied: To get an overview onthe estimated parameters, summary or plot are perfectly suited. Detailed visual analyses can beperformed by applying the shinystan package, which can be called directly within brms usinglaunch_shiny. Information Criteria are also readily available via WAIC and LOO both relying on theloo package.

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

When comparing other packages fitting GLMMs to brms, keep in mind that the latter needs to com-pile models before actually fitting them, which will require between 20 and 40 seconds dependingon your machine, operating system and overall model complexity. Thus, fitting smaller modelsmay be relatively slow as compilation time makes up the majority of the whole running time. Forlarger / more complicated models however, fitting my take several minutes or even hours, so thatthe compilation time won’t make much of a difference here.

Author(s)

Paul-Christian Buerkner

Maintainer: Paul-Christian Buerkner <[email protected]>

References

The Stan Development Team Stan Modeling Language User’s Guide and Reference Manual. http://mc-stan.org/.

See Also

brm, brmsfit

http://mc-stan.org/

http://mc-stan.org/

http://mc-stan.org/

4 brm

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

Description

Extract posterior samples for use with the coda package

Usage

## S3 method for class 'brmsfit'as.mcmc(x, pars = NA, exact_match = FALSE,inc_warmup = FALSE, ...)

Arguments

x An R object typically of class brmsfitpars Names of parameters for which posterior samples should be returned, as given

by a character vector or regular expressions. By default, all posterior samples ofall parameters are extracted

exact_match Indicates whether parameter names should be matched exactly or treated as reg-ular expression. Default is FALSE.

inc_warmup Indicates if the warmup samples should be included. Default is FALSE. Warmupsamples are used to tune the parameters of the sampling algorithm and shouldnot be analyzed.

... additional arguments

Value

A list of mcmc objects (not an mcmc object itself).

brm Fit Bayesian Generalized (Non-)Linear and Ordinal Mixed Models

Description

Fit a Bayesian generalized (non-)linear or ordinal mixed model using Stan

Usage

brm(formula, data = NULL, family = gaussian(), prior = NULL,addition = NULL, autocor = NULL, nonlinear = NULL, partial = NULL,threshold = c("flexible", "equidistant"), cov_ranef = NULL,ranef = TRUE, sample_prior = FALSE, fit = NA, inits = "random",chains = 4, iter = 2000, warmup = floor(iter/2), thin = 1,cluster = 1, cluster_type = "PSOCK", control = NULL,algorithm = c("sampling", "meanfield", "fullrank"), silent = TRUE,seed = 12345, save_model = NULL, ...)

brm 5

Arguments

formula An object of class "formula" (or one that can be coerced to that class): a sym-bolic description of the model to be fitted. The details of model specification aregiven under ’Details’.

data An optional data frame, list or environment (or object coercible by as.data.frameto a data frame) containing the variables in the model. If not found in data,the variables are taken from environment(formula), typically the environmentfrom which brm is called. Although it is optional, we strongly recommend tosupply a data.frame.

family A description of the error distribution and link function to be used in the model.This can be a family function, a call to a family function or a character stringnaming the family. Currently, the following families are supported: gaussian,student, cauchy (deprecated), binomial, bernoulli, Beta, poisson, negbinomial,geometric, Gamma, inverse.gaussian, exponential, weibull, categorical,cumulative, cratio, sratio, acat, hurdle_poisson, hurdle_negbinomial,hurdle_gamma, zero_inflated_binomial, zero_inflated_beta, zero_inflated_negbinomial,and zero_inflated_poisson. Every family function has a link argument al-lowing to specify the link function to be applied on the response variable. If notspecified, default links are used. See family for help on standard family func-tions and brmsfamily for family functions specific to the brms package. Forbackwards compatibility, family may also be a vector of two character strings,the first naming the family and the second naming the link. Further informationis provided under ’Details’.

prior One or more brmsprior objects created by function set_prior and combinedusing the c method. A single brmsprior object may be passed without c()surrounding it. See also get_prior for more help.

addition Deprecated. All additional information on the response variable should be incor-porated directly into formula. See ’Formula Syntax’ under ’Details’ for furtherinformation.

autocor An optional cor_brms object describing the correlation structure within the re-sponse variable (i.e. the ’autocorrelation’). See the documentation of cor_brmsfor a description of the available correlation structures. Defaults to NULL, cor-responding to no correlations.

nonlinear An optional list of formuluas, specifying linear models for non-linear param-eters. If NULL (the default) formula is treated as an ordinary formula. If notNULL, formula is treated as a non-linear model and nonlinear should contain aformula for each non-linear parameter, which has the parameter on the left handside and its linear predictor on the right hand side. Alternatively, it can be asingle formula with all non-linear parameters on the left hand side (separated bya +) and a common linear predictor on the right hand side. More information isgiven under ’Details’.

partial A one sided formula of the form ~expression allowing to specify predictorswith category specific effects in non-cumulative ordinal models (i.e. in familiescratio, sratio, or acat).

threshold A character string indicating the type of thresholds (i.e. intercepts) used inan ordinal model. "flexible" provides the standard unstructured thresholds

6 brm

and "equidistant" restricts the distance between consecutive thresholds to thesame value.

cov_ranef A list of matrices that are proportional to the (within) covariance structure ofthe random effects. The names of the matrices should correspond to columns indata that are used as grouping factors. All levels of the grouping factor shouldappear as rownames of the corresponding matrix.

ranef A flag to indicate if random effects for each level of the grouping factor(s) shouldbe saved (default is TRUE). Set to FALSE to save memory. The argument has noimpact on the model fitting itself.

sample_prior A flag to indicate if samples from all specified proper priors should be addition-ally drawn. Among others, these samples can be used to calculate Bayes factorsfor point hypotheses. Default is FALSE.

fit An instance of S3 class brmsfit derived from a previous fit; defaults to NA. Iffit is of class brmsfit, the compiled model associated with the fitted result isre-used and all arguments modifying the model code or data are ignored.

inits Either "random" or "0". If inits is "random" (the default), Stan will randomlygenerate initial values for parameters. If it is "0", all parameters are initiliazedto zero. This option is recommended for exponential and weibull models,as it happens that default ("random") inits cause samples to be essentially con-stant. Generally, setting inits = "0" is worth a try, if chains do not behavewell. Alternatively, inits can be a list of lists containing the initial values, ora function (or function name) generating initial values. The latter options aremainly implemented for internal testing.

chains Number of Markov chains (defaults to 4). A deprecated alias is n.chains.

iter Number of total iterations per chain (including warmup; defaults to 2000). Adeprecated alias is n.iter.

warmup A positive integer specifying number of warmup (aka burnin) iterations. Thisalso specifies the number of iterations used for stepsize adaptation, so warmupsamples should not be used for inference. The number of warmup should not belarger than iter and the default is iter/2. A deprecated alias is n.warmup.

thin Thinning rate. Must be a positive integer. Set thin > 1 to save memory andcomputation time if iter is large. Default is 1, that is no thinning. A deprecatedalias is n.thin.

cluster Number of clusters to use to run parallel chains. Default is 1. A deprecated aliasis n.cluster. To use the built-in parallel execution of rstan, specify argumentcores instead of cluster.

cluster_type A character string specifying the type of cluster created by makeCluster whensampling in parallel (i.e. when cluster is greater 1). Default is "PSOCK" work-ing on all platforms. For OS X and Linux, "FORK" may be a faster and morestable option, but it does not work on Windows.

control A named list of parameters to control the sampler’s behavior. It defaults toNULL so all the default values are used. The most important control parametersare discussed in the ’Details’ section below. For a comprehensive overview seestan.

brm 7

algorithm Character string indicating the estimation approach to use. Can be "sampling"for MCMC (the default), "meanfield" for variational inference with indepen-dent normal distributions, or "fullrank" for variational inference with a multi-variate normal distribution.

silent logical; If TRUE, warning messages of the sampler are suppressed.

seed Positive integer. Used by set.seed to make results reproducable.

save_model Either NULL or a character string. In the latter case, the model code is saved in afile named after the string supplied in save_model, which may also contain thefull path where to save the file. If only a name is given, the file is save in thecurrent working directory.

... Further arguments to be passed to Stan.

Details

Fit a generalized linear mixed model, which incorporates both fixed-effects parameters and randomeffects in a linear predictor via full bayesian inference using Stan.

Formula syntax for generalized linear mixed models

The formula argument accepts formulas of the following syntax:

response | addition ~ fixed + (random | group)

Multiple grouping factors each with multiple random effects are possible. Instead of | you mayuse || in random effects terms to prevent random effects correlations from being modeled. With theexception of addition, this is basically lme4 syntax. The optional addition term may containmultiple terms of the form fun(variable) seperated by | each providing special information onthe response variable. fun can be replaced with either se, weights, trials, cat, cens, or trunc.Their meanings are explained below.

For families gaussian, student, and cauchy it is possible to specify standard errors of the observa-tion, thus allowing to perform meta-analysis. Suppose that the variable yi contains the effect sizesfrom the studies and sei the corresponding standard errors. Then, fixed and random effects meta-analyses can be conducted using the formulae yi | se(sei) ~ 1 and yi | se(sei) ~ 1 + (1|study),respectively, where study is a variable uniquely identifying every study. If desired, meta-regressencan be performed via yi | se(sei) ~ 1 + mod1 + mod2 + (1|study) oryi | se(sei) ~ 1 + mod1 + mod2 + (1 + mod1 + mod2|study), where mod1 and mod2represent moderator variables.

For all families, weighted regression may be performed using weights in the addition part. Sup-pose that variable wei contains the weights and that yi is the response variable. Then, formulayi | weights(wei) ~ predictors implements a weighted regression.

For families binomial and zero_inflated_binomial, addition should contain a variable indi-cating the number of trials underlying each observation. In lme4 syntax, we may write for in-stance cbind(success, n - success), which is equivalent to success | trials(n) in brmssyntax. If the number of trials is constant across all observation (say 10), we may also writesuccess | trials(10).

For family categorical and all ordinal families, addition may contain a term cat(number) tospecify the number categories (e.g, cat(7)). If not given, the number of categories is calculatedfrom the data.

8 brm

With the expection of categorical and ordinal families, left and right censoring can be modeledthrough yi | cens(censored) ~ predictors. The censoring variable (named censored in thisexample) should contain the values 'left', 'none', and 'right' (or equivalenty -1, 0, and 1) toindicate that the corresponding observation is left censored, not censored, or right censored.

With the expection of categorical and ordinal families, the response distribution can be truncatedusing the trunc function in the addition part. If the response variable is truncated between, say, 0and 100, we can specify this via yi | trunc(lb = 0, ub = 100) ~ predictors. Defining onlyone of the two arguments in trunc leads to one-sided truncation.

Mutiple addition terms may be specified at the same time using the + operator, for instanceformula = yi | se(sei) + cens(censored) ~ 1 for a censored meta-analytic model.

For families gaussian, student, and cauchy multivariate models may be specified using cbind no-tation. Suppose that y1 and y2 are response variables and x is a predictor. Then cbind(y1,y2) ~ xspecifies a multivariate model, where x has the same effect on y1 and y2. To indicate differenteffects on each response variable, the variable trait (which is reserved in multivariate models) canbe used as an additional categorical predictor. For instance, cbind(y1,y2) ~ 0 + x:trait leadsto seperate effects of x on y1 and y2. In this case, trait has two levels, namely "y1" and "y2". Bydefault, trait is dummy-coded. It may also be used within random effects terms, both as groupingfactor or as random effect within a grouping factor. Note that variable trait is generated internallyand may not be specified in the data passed to brm.

Zero-inflated and hurdle families are bivariate and also make use of the special internal variabletrait having two levels in this case. However, only the actual response must be specified informula, as the second response variable used for the zero-inflation / hurdle (ZIH) part is inter-nally generated. A formula for this type of models may, for instance, look like this:y ~ 0 + trait * (x1 + x2) + (0 + trait | g). In this example, the fixed effects x1and x1 influence the ZIH part differently than the actual response part as indicated by their inter-action with trait. In addition, a random effect of trait was added while the random interceptwas removed leading to the estimation of two random effects, one for the ZIH part and one for theactual response. In the example above, the correlation between the two random effects will also beestimated. Sometimes, predictors should only influence the ZIH part but not the actual response (orvice versa). As this cannot be modeled with the trait variable, two other internally generated andreserved (numeric) variables, namely main and spec, are supported. main is 1 for the response partand 0 for the ZIH part of the model. For spec it is the other way round. Suppose that x1 shouldonly influence the actual response, and x2 only the ZIH process. We can write this as follows:formula = y ~ 0 + main + spec + main:x1 + spec:x2. The main effects of main or specserve as intercepts, while the interaction terms main:x1 and spec:x2 ensure that x1 and x2 onlypredict one part of the model, respectively.

Using the same syntax as for zero-inflated and hurdle models, it is possible to specify multiplicativeeffects in family bernoulli (make sure to set argument type to "2PL"; see brmsfamily for moredetails). In Item Response Theory (IRT), these models are known as 2PL models. Suppose that wehave the variables item and person and want to model fixed effects for items and random effects forpersons. The discriminality (multiplicative effect) should depend only on the items. We can specifythis by setting formula = response ~ 0 + (main + spec):item + (0 + main|person).The random term 0 + main ensures that person does not influence discriminalities. Of courseit is possible to predict only discriminalities by using variable spec in the model formulation. Toidentify the model, multiplicative effects are estimated on the log scale. In addition, we strongly

brm 9

recommend setting proper priors on fixed effects in this case to increase sampling efficiency (fordetails on priors see set_prior).

Parameterization of the fixed effects intercept

The fixed effects intercept (if incorporated) is estimated separately and not as part of the fixedeffects parameter vector b. This has the side effect that priors on the intercept also have to bespecified separately (see set_prior for more details). Furthermore, to increase sampling efficiency,the fixed effects design matrix X is centered around its column means X_means if the intercept isincorporated. This leads to a temporary bias in the intercept equal to <X_means, b>, where <,> isthe scalar product. The bias is corrected after fitting the model, but be aware that you are effectivelydefining a prior on the temporary intercept of the centered design matrix not on the real intercept.

This behavior can be avoided by using the reserved (and internally generated) variable intercept.Instead of y ~ x, you may write y ~ -1 + intercept + x. This way, priors can be defined on thereal intercept, directly. In addition, the intercept is just treated as an ordinary fixed effect and thuspriors defined on b will also apply to it. Note that this parameterization may be a bit less efficientthan the default parameterization discussed above.

Formula syntax for non-linear mixed models

Using the nonlinear argument, it is possible to specify non-linear models in brms. Contrary towhat the name might suggest, nonlinear should not contain the non-linear model itself but ratherinformation on the non-linear parameters. The non-linear model will just be specified within theformula argument. Suppose, that we want to predict the response y through the predictor x, wherex is linked to y through y = alpha - beta * lambda^x, with parameters alpha, beta, and lambda.This is certainly a non-linear model, which is readily defined via formula = y ~ alpha - beta * lambda^x(addition arguments can be added in the same way as for ordinary formulas). Now we have to tellbrms the names of the non-linear parameters and specfiy a (linear mixed) model for each of them us-ing the nonlinear argument. Let’s say we just want to estimate those three parameters with not fur-ther covariates or random effects. Then we can write nonlinear = alpha + beta + lambda ~ 1or equivalently (and more flexible) nonlinear = list(alpha ~ 1, beta ~ 1, lambda ~ 1).This can, of course, be extended. If we have another predictor z and observations nested within thegrouping factor g, we may write for instance nonlinear = list(alpha ~ 1, beta ~ 1 + z + (1|g), lambda ~ 1).The formula syntax of fixed and random effects described above applies here as well. In this exam-ple, we are using z and g only for the prediction of beta, but we might also use them for the othernon-linear parameters (provided that the resulting model is still scientifically reasonable).

Non-linear models may not be uniquely identified and / or show bad convergence. For this reasonit is mandatory to specify priors on the non-linear parameters. For instructions on how to do that,see set_prior.

Families and link functions

Family gaussian with identity link leads to linear regression. Families student, and cauchywith identity link leads to robust linear regression that is less influenced by outliers. Fami-lies poisson, negbinomial, and geometric with log link lead to regression models for countdata. Families binomial and bernoulli with logit link leads to logistic regression and familycategorical to multi-logistic regression when there are more than two possible outcomes. Fami-lies cumulative, cratio (’contiuation ratio’), sratio (’stopping ratio’), and acat (’adjacent cate-gory’) leads to ordinal regression. Families Gamma, weibull, exponential, and inverse.gaussiancan be used (among others) for survival regression when combined with the log link. Familieshurdle_poisson, hurdle_negbinomial, hurdle_gamma, zero_inflated_poisson, andzero_inflated_negbinomial combined with the log link, and zero_inflated_binomial with

10 brm

the logit link, allow to estimate zero-inflated and hurdle models. These models can be very help-ful when there are many zeros in the data that cannot be explained by the primary distribution ofthe response. Family hurdle_gamma is especially useful, as a traditional Gamma model cannot bereasonably fitted for data containing zeros in the response.

In the following, we list all possible links for each family. The families gaussian, student, andcauchy accept the links (as names) identity, log, and inverse; families poisson, negbinomial,and geometric the links log, identity, and sqrt; families binomial, bernoulli, Beta, cumulative,cratio, sratio, and acat the links logit, probit, probit_approx, cloglog, and cauchit;family categorical the link logit; families Gamma, weibull, and exponential the links log,identity, and inverse; family inverse.gaussian the links 1/mu^2, inverse, identity andlog; families hurdle_poisson, hurdle_negbinomial, hurdle_gamma, zero_inflated_poisson,and zero_inflated_negbinomial the link log. The first link mentioned for each family is the de-fault.

Please note that when calling the Gamma family function, the default link will be inverse not log.Also, the probit_approx link cannot be used when calling the binomial family function.

The current implementation of inverse.gaussian models has some convergence problems andrequires carefully chosen prior distributions to work efficiently. For this reason, we currently donot recommend to use the inverse.gaussian family, unless you really feel that your data requiresexactly this type of model.

Prior distributions

As of brms 0.5.0, priors should be specified using the set_prior function. Its documentation con-tains detailed information on how to correctly specify priors. To find out on which parameters orparameter classes priors can be defined, use get_prior.

Adjusting the sampling behavior of Stan

In addition to choosing the number of iterations, warmup samples, and chains, users can controlthe behavior of the NUTS sampler, by using the control argument. The most important reasonto use control is to decrease (or eliminate at best) the number of divergent transitions that causea bias in the obtained posterior samples. Whenever you see the warning "There were x divergenttransitions after warmup." you should really think about increasing adapt_delta. To do this, writecontrol = list(adapt_delta = <x>), where <x> should usually be value between 0.8 (currentdefault) and 1. Increasing adapt_delta will slow down the sampler but will decrease the numberof divergent transitions threatening the validity of your posterior samples.

Another problem arises when the depth of the tree being evaluated in each iteration is exceeded.This is less common than having divergent transitions, but may also bias the posterior samples.When it happens, Stan will throw out a warning suggesting to increase max_treedepth, which canbe accomplished by writing control = list(max_treedepth = <x>) with a positive integer<x> that should usually be larger than the current default of 10. For more details on the controlargument see stan.

Value

An object of class brmsfit, which contains the posterior samples along with many other usefulinformation about the model. Use methods(class = "brmsfit") for an overview on availablemethods.

brm 11

Author(s)

Paul-Christian Buerkner <[email protected]>

Examples

## Not run:## Poisson regression for the number of seizures in epileptic patients## using student_t priors for fixed effects## and half cauchy priors for standard deviations of random effectsfit1 <- brm(count ~ log_Age_c + log_Base4_c * Trt_c

+ (1|patient) + (1|visit) + (1|obs),data = epilepsy, family = poisson(),prior = c(set_prior("student_t(5,0,10)", class = "b"),

set_prior("cauchy(0,2)", class = "sd")))## generate a summary of the resultssummary(fit1)## plot the MCMC chains as well as the posterior distributionsplot(fit1, ask = FALSE)## extract random effects standard devations and covariance matricesVarCorr(fit1)## extract group specific effects of each levelranef(fit1)## predict responses based on the fitted modelhead(predict(fit1))## plot marginal effects of each predictorplot(marginal_effects(fit1), ask = FALSE)

## Ordinal regression modeling patient's rating## of inhaler instructions with normal priors on fixed effectsfit2 <- brm(rating ~ treat + period + carry,

data = inhaler, family = sratio("cloglog"),prior = set_prior("normal(0,5)"))

summary(fit2)plot(fit2, ask = FALSE)

## Survival regression modeling the time between the first## and second recurrence of an infection in kidney patients.fit3 <- brm(time | cens(censored) ~ age * sex + disease + (1|patient),

data = kidney, family = gaussian("log"))summary(fit3)plot(fit3, ask = FALSE)plot(marginal_effects(fit3), ask = FALSE)

## Probit regression using the binomial familyn <- sample(1:10, 100, TRUE) # number of trialssuccess <- rbinom(100, size = n, prob = 0.4)x <- rnorm(100)fit4 <- brm(success | trials(n) ~ x,

family = binomial("probit"))summary(fit4)

## Simple non-linear gaussian model

12 brmsfamily

x <- rnorm(100)y <- rnorm(100, mean = 2 - 1.5^x, sd = 1)fit5 <- brm(y ~ a1 - a2^x, nonlinear = a1 + a2 ~ 1,

prior = c(set_prior("normal(0, 2)", nlpar = "a1"),set_prior("normal(0, 2)", nlpar = "a2")))

summary(fit5)plot(marginal_effects(fit5), ask = FALSE)

## End(Not run)

brmsfamily Special Family Functions for brms Models

Description

Family objects provide a convenient way to specify the details of the models used by many modelfitting functions. The families present here are currently for use with brms only and will NOT workwith other model fitting functions such as glm or glmer. However, the standard family functions asdecribed in family will work with brms. For a full list of families and link functions supported bybrms, see the documentation (in particular the ’Details’ section) of brm.

Usage

student(link = "identity")

cauchy(link = "identity")

bernoulli(link = "logit", type = NULL)

negbinomial(link = "log")

geometric(link = "log")

exponential(link = "log")

weibull(link = "log")

Beta(link = "logit")

hurdle_poisson(link = "log")

hurdle_negbinomial(link = "log")

hurdle_gamma(link = "log")

zero_inflated_beta(link = "logit")

brmsfit-class 13

zero_inflated_poisson(link = "log")

zero_inflated_negbinomial(link = "log")

zero_inflated_binomial(link = "logit")

categorical(link = "logit")

cumulative(link = "logit")

sratio(link = "logit")

cratio(link = "logit")

acat(link = "logit")

Arguments

link A specification for the model link function. This can be a name/expression orcharacter string. The following list only refers to brms specific family func-tions. Families student, and cauchy (deprecated) accept the links (as names)identity, log, and inverse; families negbinomial, and geometric the linkslog, identity, and sqrt; families bernoulli, Beta, cumulative, cratio,sratio, and acat the links logit, probit, probit_approx, cloglog, andcauchit; family categorical, the link logit; families weibull, and exponentialthe links log, identity, and inverse; families hurdle_poisson, hurdle_gamma,hurdle_negbinomial, zero_inflated_poisson, and zero_inflated_negbinomialthe link log; families zero_inflated_binomial and zero_inflated_beta thelink logit. The first link mentioned for each family is the default. A full listof families and link functions supported by brms, is provided in the ’Details’section of brm.

type An optional character string allowing to specify advanced models implementedthrough certain families. Currently, only the bernoulli family uses this argu-ment to define 2PL models (applied in IRT) by setting type = "2PL". Furtheroptions will follow in the future.

brmsfit-class Class brmsfit of fitted mixed-effect models

Description

Models fitted with the brms package are represented as a brmsfit object, which contains the pos-terior samples, the model code, the relevant data, the model formula, and some other useful infor-mation.

14 coef.brmsfit

Details

Currently, the following S3 methods are available for class brmsfit:

coef, family, fitted, fixef, formula, hypothesis, launch_shiny, logLik, LOO, model.frame,ngrps, nobs, pairs, parnames, plot, posterior_samples, predict, print, prior_samples,ranef, residuals, stancode, standata, stanplot, summary, update, VarCorr, vcov, WAIC

Slots

formula: model formula; an object of class formula

family: model family; an object of class family

link: link function; a character string (deprecated)

data.name: name of the data frame; a character string

data: model.frame containing all variables used in the model

model: model in Stan language; a character string

exclude: parameters for which samples are not saved; a character vector

prior: priors applied in the model; a matrix

ranef: random effects structure; a named list

autocor: an object of class cor_brms containing the autocorrelation structure

partial: formula of the category specific effects applied in ordinal models

cov_ranef: a list of customized random effects covariance matrices

fit: fitted results including the posterior samples; an object of class stanfit

algorithm: the name of the algorithm used to fit the model

See Also

brms, brm

coef.brmsfit Extract model coefficients

Description

Extract model coefficients, which are the sum of fixed effects and corresponding random effects

Usage

## S3 method for class 'brmsfit'coef(object, estimate = "mean", ...)

cor_ar 15

Arguments

object An object of class brmsfit

estimate The point estimate to be calculated for the random effects, either "mean" or"median".

... Further arguments to be passed to the function specified in estimate

Value

A list of matrices (one per grouping factor), with factor levels as row names and coefficients ascolumn names

Examples

## Not run:fit <- brm(count ~ log_Age_c + log_Base4_c * Trt_c + (1+Trt_c|visit),

data = epilepsy, family = "poisson", chains = 1)## extract fixed and random effects coefficients seperatelyfixef(fit)ranef(fit)## extract combined coefficientscoef(fit)

## End(Not run)

cor_ar AR(p) correlation structure

Description

This function is a constructor for the cor_arma class, allowing for autoregression terms only.

Usage

cor_ar(formula = ~1, p = 1, cov = FALSE)

Arguments

formula A one sided formula of the form ~ t, or ~ t | g, specifying a time covariate t and,optionally, a grouping factor g. A covariate for this correlation structure mustbe integer valued. When a grouping factor is present in formula, the correlationstructure is assumed to apply only to observations within the same groupinglevel; observations with different grouping levels are assumed to be uncorre-lated. Defaults to ~ 1, which corresponds to using the order of the observationsin the data as a covariate, and no groups.

p A non-negative integer specifying the autoregressive (AR) order of the ARMAstructure. Default is 0.

16 cor_arma

cov A flag indicating whether ARMA effects should be estimated by means of resid-ual covariance matrices (currently only possible for stationary ARMA effects oforder 1). If FALSE (the default) a regression formulation is used that is consid-erably faster and allows for ARMA effects of order higher than 1 but cannothandle user defined standard errors.

Details

As of brms version 0.6.0, the AR structure refers to autoregressive effects of residuals to matchthe naming and implementation in other packages such as nlme. Previously, the AR term in brmsreferred to autoregressive effects of the response. The latter are now named ARR effects and can bemodeled using argument r in the cor_arma and cor_arr functions.

Value

An object of class cor_arma containing solely autoregression terms.

Author(s)


See Also

cor_arma

Examples

cor_ar(~visit|patient, p = 2)

cor_arma ARMA(p,q) correlation structure

Description

This functions is a constructor for the cor_arma class, representing an autoregression-moving av-erage correlation structure of order (p, q).

Usage

cor_arma(formula = ~1, p = 0, q = 0, r = 0, cov = FALSE)

cor_arma 17

Arguments


p A non-negative integer specifying the autoregressive (AR) order of the ARMAstructure. Default is 0.

q A non-negative integer specifying the moving average (MA) order of the ARMAstructure. Default is 0.

r A non-negative integer specifying the autoregressive response (ARR) order. See’Details’ for differences of AR and ARR effects. Default is 0.


Details

As of brms version 0.6.0, the AR structure refers to autoregressive effects of residuals to matchthe naming and implementation in other packages such as nlme. Previously, the AR term in brmsreferred to autoregressive effects of the response. The latter are now named ARR effects and can bemodeled using argument r in the cor_arma and cor_arr functions.

Value

An object of class cor_arma, representing an autoregression-moving-average correlation structure.

Author(s)


See Also

cor_ar cor_ma cor_arr

Examples

cor_arma(~visit|patient, p = 2, q = 2)

18 cor_arr

cor_arr ARR(r) correlation structure

Description

This function is a constructor for the cor_arma class allowing for autoregressive effects of theresponse only.

Usage

cor_arr(formula = ~1, r = 1)

Arguments


r A non-negative integer specifying the autoregressive response (ARR) order. See’Details’ for differences of AR and ARR effects. Default is 0.

Details

In most packages, AR effects refer to autocorrelation of residuals. brms also implements autocor-relation of the response, which can be specified using argument r in the cor_arma and cor_arrfunctions.

Value

An object of class cor_arma containing solely autoregressive response terms.

Author(s)


See Also

cor_arma

Examples

cor_arr(~visit|patient, r = 2)

cor_brms 19

cor_brms Correlation structure classes

Description

Classes of correlation structures available in the brms package. cor_brms is not a correlationstructure itself, but the class common to all correlation structures implemented in brms.

Value

Avaiblable correlation structures

cor_ar autoregressive process of arbitrary order.

cor_arma autoregressive-moving average process, with arbitrary orders for the autoregressive andmoving average components.

cor_arr autoregressive process of the response (instead of residuals) of arbitrary order.

cor_ma moving average process of arbitrary order.

See Also

cor_ar, cor_arma, cor_arr, cor_ma

cor_ma MA(q) correlation structure

Description

This function is a constructor for the cor_arma class, allowing for moving average terms only.

Usage

cor_ma(formula = ~1, q = 1, cov = FALSE)

Arguments


q A non-negative integer specifying the moving average (MA) order of the ARMAstructure. Default is 0.

20 epilepsy


Value

An object of class cor_arma containing solely moving average terms.

Author(s)


See Also

cor_arma

Examples

cor_ma(~visit|patient, q = 2)

epilepsy Epileptic seizure counts

Description

Breslow and Clayton (1993) analyse data initially provided by Thall and Vail (1990) concerningseizure counts in a randomised trial of anti-convulsant therapy in epilepsy. Covariates are treatment,8-week baseline seizure counts, and age of the patients in years.

Usage

epilepsy

Format

A dataframe of 236 observations containing information on the following 9 variables.

Age The age of the patients in years

Base The seizure count at 8-weeks baseline

Trt Either 0 or 1 indicating if the patient recieved anti-convulsant therapy

log_Age_c The logarithm of Age centered arounds its mean

log_Base4_c The logarithm of Base divided by 4 (i.e. log(Base/4)) centered around its mean

Trt_c Trt centered around its mean

visit The session number from 1 (first visit) to 4 (last visit)

fitted.brmsfit 21

count The seizure count between two visits

patient The patient number

obs The observation number, i.e. a unique identifier for each observation

Source

Thall, P. F., & Vail, S. C. (1990). Some covariance models for longitudinal count data with overdis-persion. Biometrics, 46(2), 657-671.

Breslow, N. E., & Clayton, D. G. (1993). Approximate inference in generalized linear mixed mod-els. Journal of the American Statistical Association, 88(421), 9-25.

Examples

## Not run:## poisson regression without random effects.fit1 <- brm(count ~ log_Age_c + log_Base4_c * Trt_c,

data = epilepsy, family = poisson())summary(fit1)plot(fit1)

## poisson regression with random intercepts of patients and visits## as well as normal priors for fixed effects parameters.fit2 <- brm(count ~ log_Age_c + log_Base4_c * Trt_c

+ (1|patient) + (1|visit),data = epilepsy, family = poisson(),prior = set_prior("normal(0,5)"))

summary(fit2)plot(fit2)

## End(Not run)

fitted.brmsfit Extract Model Fitted Values of brmsfit Objects

Description

Predict fitted values (i.e. the ’regression line’) of a fitted model. Can be performed for the data usedto fit the model (posterior predictive checks) or for new data. By definition, these predictions havesmaller variance than the response predictions performed by the predict method. This is becausethe measurement error is not incorporated. The estimated means of both methods should, however,be very similar.

22 fitted.brmsfit

Usage

## S3 method for class 'brmsfit'fitted(object, newdata = NULL, re_formula = NULL,scale = c("response", "linear"), allow_new_levels = FALSE,subset = NULL, nsamples = NULL, summary = TRUE, probs = c(0.025,0.975), ...)

Arguments


newdata An optional data.frame for which to evaluate predictions. If NULL (default), theorginal data of the model is used.

re_formula formula containing random effects to be considered in the prediction. If NULL(default), include all random effects; if NA, include no random effects.

scale Either "response" or "linear". If "response" results are returned on the scaleof the response variable. If "linear" fitted values are returned on the scale ofthe linear predictor.

allow_new_levels

A flag indicating if new levels of random effects are allowed (defaults to FALSE).Only relevant if newdata is provided.

subset A numeric vector specifying the posterior samples to be used. If NULL (thedefault), all samples are used.

nsamples Positive integer indicating how many posterior samples should be used. If NULL(the default) all samples are used. Ignored if subset is not NULL.

summary Should summary statistics (i.e. means, sds, and 95% intervals) be returned in-stead of the raw values? Default is TRUE.

probs The percentiles to be computed by the quantile function. Only used if summaryis TRUE.

... Currently ignored

Details

For models fitted with brms <= 0.5.0 only: Be careful when using newdata with factors in fixed orrandom effects. The predicted results are only valid if all factor levels present in the initial data arealso defined and ordered correctly for the factors in newdata. Grouping factors may contain fewerlevels than in the inital data without causing problems. When using higher versions of brms, allfactors are automatically checked for correctness and amended if necessary.

Value

Fitted values extracted from object. The output depends on the family: If summary = TRUE it is aN x E x C array for categorical and ordinal models and a N x E matrix else. If summary = FALSEit is a S x N x C array for categorical and ordinal models and a S x N matrix else. N is the numberof observations, S is the number of samples, C is the number of categories, and E is equal tolength(probs) + 2.

fixef.brmsfit 23

Examples

## Not run:## fit a modelfit <- brm(rating ~ treat + period + carry + (1|subject),

data = inhaler)

## extract fitted valuesfitted_values <- fitted(fit)head(fitted_values)

## plot fitted means against actual responsedat <- as.data.frame(cbind(Y = standata(fit)$Y, fitted_values))ggplot(dat) + geom_point(aes(x = Estimate, y = Y))

## End(Not run)

fixef.brmsfit Extract Fixed Effects Estimates

Description

Extract the fixed effects from a brmsfit object.

Usage

## S3 method for class 'brmsfit'fixef(object, estimate = "mean", ...)

Arguments


estimate A character vector specifying which coefficients (e.g., "mean", "median", "sd",or "quantile") should be calculated for the fixed effects.

... Further arguments to be passed to the functions specified in estimate

Value

A matrix with one row per fixed effect and one column per calculated estimate.

Author(s)


24 get_prior

Examples

## Not run:fit <- brm(time | cens(censored) ~ age + sex + disease,

data = kidney, family = "exponential")fixef(fit, estimate = c("mean", "sd"))

## End(Not run)

get_prior Overview on Priors for brms Models

Description

Get information on all parameters (and parameter classes) for which priors may be specified includ-ing default priors.

Usage

get_prior(formula, data = NULL, family = gaussian(), autocor = NULL,nonlinear = NULL, partial = NULL, threshold = c("flexible","equidistant"), internal = FALSE)

Arguments




get_prior 25




threshold A character string indicating the type of thresholds (i.e. intercepts) used inan ordinal model. "flexible" provides the standard unstructured thresholdsand "equidistant" restricts the distance between consecutive thresholds to thesame value.

internal A flag indicating if the names of additional internal parameters should be dis-played. Setting priors on these parameters is not recommended

Value

A data.frame with columns prior, class, coef, and group and several rows, each providing infor-mation on a parameter (or parameter class) on which priors can be specified. The prior column isempty except for internal default priors.

See Also

set_prior

Examples

## get all parameters and parameters classes to define priors on(prior <- get_prior(count ~ log_Age_c + log_Base4_c * Trt_c

+ (1|patient) + (1|visit),data = epilepsy, family = poisson()))

## define a prior on all fixed effects a onceprior$prior[1] <- "normal(0,10)"

## define a specific prior on the fixed effect of Trt_cprior$prior[5] <- "student_t(10, 0, 5)"

## verify that the priors indeed found their way into Stan's model codemake_stancode(count ~ log_Age_c + log_Base4_c * Trt_c

+ (1|patient) + (1|visit),data = epilepsy, family = poisson(),

26 hypothesis.brmsfit

prior = prior)

hypothesis.brmsfit Non-linear hypothesis testing

Description

Perform non-linear hypothesis testing for all model parameters.

Usage

## S3 method for class 'brmsfit'hypothesis(x, hypothesis, class = "b", group = "",alpha = 0.05, ...)

hypothesis(x, hypothesis, ...)

## S3 method for class 'brmshypothesis'plot(x, N = 5, ignore_prior = FALSE,theme = ggplot2::theme(), ask = TRUE, do_plot = TRUE, newpage = TRUE,...)

Arguments

x An R object typically of class brmsfithypothesis A character vector specifying one or more non-linear hypothesis concerning

parameters of the modelclass A string specifying the class of parameters being tested. Default is "b" for fixed

effects. Other typical options are "sd" or "cor". If class = NULL, all parameterscan be tested against each other, but have to be specified with their full name(see also parnames)

group Name of a grouping factor to evaluate only random effects parameters related tothis grouping factor. Ignored if class is not "sd" or "cor".

alpha the alpha-level of the tests (default is 0.05)... Currently ignoredN The number of parameters plotted per page.ignore_prior A flag indicating if prior distributions should also be plotted. Only used if priors

were specified on the relevant parameters.theme A theme object modifying the appearance of the plots. For some basic themes

see ggtheme. Can be defined globally for the current session, via theme_set.ask logical; indicates if the user is prompted before a new page is plotted. Only used

if do_plot is TRUE.do_plot logical; indicates if plots should be plotted directly in the active graphic device.

Defaults to TRUE.newpage logical; indicates if the first set of plots should be plotted to a new page. Only

used if do_plot is TRUE.

hypothesis.brmsfit 27

Details

Among others, hypothesis computes an evidence ratio for each hypothesis. For a directed hy-pothesis, this is just the posterior probability under the hypothesis against its alternative. For anundirected (i.e. point) hypothesis the evidence ratio is a Bayes factor between the hypothesis andits alternative. In order to calculate this Bayes factor, all parameters related to the hypothesis musthave proper priors and argument sample_prior of function brm must be set to TRUE. When inter-preting Bayes factors, make sure that your priors are reasonable and carefully chosen, as the resultwill depend heavily on the priors. It particular, avoid using default priors.

Value

Summary statistics of the posterior distributions related to the hypotheses.

Author(s)


Examples

## Not run:## define priorsprior <- c(set_prior("normal(0,2)", class = "b"),

set_prior("student_t(10,0,1)", class = "sigma"),set_prior("student_t(10,0,1)", class = "sd"))

## fit a linear mixed effects modelsfit <- brm(time ~ age + sex + disease + (1 + age|patient),

data = kidney, family = gaussian("log"),prior = prior, sample_prior = TRUE,control = list(adapt_delta = 0.95))

## perform two-sided hypothesis testing(hyp1 <- hypothesis(fit, "sexfemale = age + diseasePKD"))plot(hyp1)hypothesis(fit, "exp(age) - 3 = 0", alpha = 0.01)

## perform one-sided hypothesis testinghypothesis(fit, "diseasePKD + diseaseGN - 3 < 0")

hypothesis(fit, "age < Intercept",class = "sd", group = "patient")

## test the amount of random intercept variance on all varianceh <- paste("sd_patient_Intercept^2 / (sd_patient_Intercept^2 +",

"sd_patient_age^2 + sigma_time^2) = 0")(hyp2 <- hypothesis(fit, h, class = NULL))plot(hyp2)

## test more than one hypothesis at once(hyp3 <- hypothesis(fit, c("diseaseGN = diseaseAN",

"2 * diseaseGN - diseasePKD = 0")))

28 inhaler

plot(hyp3, ignore_prior = TRUE)

## End(Not run)

inhaler Clarity of inhaler instructions

Description

Ezzet and Whitehead (1991) analyse data from a two-treatment, two-period crossover trial to com-pare 2 inhalation devices for delivering the drug salbutamol in 286 asthma patients. Patients wereasked to rate the clarity of leaflet instructions accompanying each device, using a 4-point ordinalscale.

Usage

inhaler

Format


subject The subject number

rating The rating of the inhaler instructions on a scale ranging from 1 to 4

treat A contrast to indicate which of the two inhaler devices was used

period A contrast to indicate the time of administration

carry A contrast to indicate possible carry over effects

Source

Ezzet, F., & Whitehead, J. (1991). A random effects model for ordinal responses from a crossovertrial. Statistics in Medicine, 10(6), 901-907.

Examples

## Not run:## ordinal regression with family "sratio"fit1 <- brm(rating ~ treat + period + carry,

data = inhaler, family = sratio(),prior = set_prior("normal(0,5)"))


## ordinal regression with family "cumulative"## and random intercept over subjectsfit2 <- brm(rating ~ treat + period + carry + (1|subject),

data = inhaler, family = cumulative(),

kidney 29

prior = set_prior("normal(0,5)"))summary(fit2)plot(fit2)

## End(Not run)

kidney Infections in kidney patients

Description

This dataset, originally discussed in McGilchrist and Aisbett (1991), describes the first and second(possibly right censored) recurrence time of infection in kideny patients using portable dialysisequipment. In addition, information on the risk variables age, sex and disease type is provided.

Usage

kidney

Format


time The time to first or second recurrence of the infection, or the time of censoring

recur A factor of levels 1 or 2 indicating if the infection recurred for the first or second time forthis patient

censored Either 0 or 1, where 0 indicates no censoring of recurrence time and 1 indicates rightcensoring

patient The patient number

age The age of the patient

sex The sex of the patient

disease A factor of levels other, GN, AN, and PKD specifiying the type of disease

Source

McGilchrist, C. A., & Aisbett, C. W. (1991). Regression with frailty in survival analysis. Biomet-rics, 47(2), 461-466.

Examples

## Not run:## performing surivival analysis using the "weibull" familyfit1 <- brm(time | cens(censored) ~ age + sex + disease,

data = kidney, family = weibull, inits = "0")summary(fit1)plot(fit1)

30 launch_shiny

## adding random intercepts over patientsfit2 <- brm(time | cens(censored) ~ age + sex + disease + (1|patient),

data = kidney, family = weibull(), inits = "0",prior = set_prior("cauchy(0,2)", class = "sd"))


## End(Not run)

launch_shiny Interface to shinystan

Description

Provide an interface to shinystan for models fitted with brms

Usage

launch_shiny(x, rstudio = getOption("shinystan.rstudio"), ...)

Arguments

x A fitted model object typically of class brmsfit.

rstudio Only relevant for RStudio users. The default (rstudio=FALSE) is to launch theapp in the default web browser rather than RStudio’s pop-up Viewer. Users canchange the default to TRUE by setting the global optionoptions(shinystan.rstudio = TRUE).

... Optional arguments to pass to runApp

Value

An S4 shinystan object

See Also

launch_shinystan

Examples

## Not run:fit <- brm(rating ~ treat + period + carry + (1|subject),

data = inhaler, family = "gaussian")launch_shiny(fit)

## End(Not run)

logLik.brmsfit 31

logLik.brmsfit Compute the pointwise log-likelihood

Description

Compute the pointwise log-likelihood

Usage

## S3 method for class 'brmsfit'logLik(object, newdata = NULL, re_formula = NULL,allow_new_levels = FALSE, subset = NULL, nsamples = NULL, ...)

Arguments

object A fitted model object of class brmsfit.



allow_new_levels





Value

Usually, an S x N matrix containing the pointwise log-likelihood samples, where S is the numberof samples and N is the number of observations in the data.

LOO.brmsfit Compute LOO

Description

Compute Leave-one-out cross-validation based on the posterior likelihood by using the loo package

32 LOO.brmsfit

Usage

## S3 method for class 'brmsfit'LOO(x, ..., compare = TRUE, newdata = NULL,re_formula = NULL, allow_new_levels = FALSE, subset = NULL,nsamples = NULL, cores = 1, wcp = 0.2, wtrunc = 3/4)

LOO(x, ..., compare = TRUE)

Arguments


... Optionally more fitted model objects.

compare A flag indicating if the WAICs of the models should be compared to each other.



allow_new_levels




cores The number of cores to use for parallelization. Default is 1.

wcp, wtrunc Parameters used for the Pareto smoothed importance sampling. See loo fordetails.

Details

When comparing models fitted to the same data, the smaller the LOO, the better the fit.

Value

If just one object is provided, an object of class ic. If multiple objects are provided, an object ofclass iclist.

Methods (by class)

• brmsfit: method for class brmsfit

Author(s)


make_stancode 33

References

Vehtari, A., Gelman, A., and Gabry, J. (2015). Efficient implementation of leave-one-out cross-validation and WAIC for evaluating fitted Bayesian models.

Gelman, A., Hwang, J., & Vehtari, A. (2014). Understanding predictive information criteria forBayesian models. Statistics and Computing, 24, 997-1016.

Watanabe, S. (2010). Asymptotic equivalence of Bayes cross validation and widely applicableinformation criterion in singular learning theory. The Journal of Machine Learning Research, 11,3571-3594.

Examples

## Not run:#model with fixed effects onlyfit1 <- brm(rating ~ treat + period + carry,

data = inhaler, family = "gaussian")LOO(fit1)

#model with an additional random intercept for subjectsfit2 <- brm(rating ~ treat + period + carry + (1|subject),

data = inhaler, family = "gaussian")#compare both modelsLOO(fit1, fit2)

## End(Not run)

make_stancode Stan Code for brms Models

Description

Generate Stan code for brms models

Usage

make_stancode(formula, data = NULL, family = gaussian(), prior = NULL,autocor = NULL, nonlinear = NULL, partial = NULL,threshold = c("flexible", "equidistant"), cov_ranef = NULL,sample_prior = FALSE, save_model = NULL, ...)

Arguments


34 make_stancode



prior One or more brmsprior objects created by function set_prior and combinedusing the c method. A single brmsprior object may be passed without c()surrounding it. See also get_prior for more help.




threshold A character string indicating the type of thresholds (i.e. intercepts) used inan ordinal model. "flexible" provides the standard unstructured thresholdsand "equidistant" restricts the distance between consecutive thresholds to thesame value.


make_standata 35

sample_prior A flag to indicate if samples from all specified proper priors should be addition-ally drawn. Among others, these samples can be used to calculate Bayes factorsfor point hypotheses. Default is FALSE.

save_model Either NULL or a character string. In the latter case, the model code is saved in afile named after the string supplied in save_model, which may also contain thefull path where to save the file. If only a name is given, the file is save in thecurrent working directory.

... Other arguments for internal usage only

Value

A character string containing the fully commented Stan code to fit a brms model.

Examples

make_stancode(rating ~ treat + period + carry + (1|subject),data = inhaler, family = "cumulative")

make_stancode(count ~ log_Age_c + log_Base4_c * Trt_c+ (1|patient) + (1|visit),data = epilepsy, family = "poisson")

make_standata Data for brms Models

Description

Generate data for brms models to be passed to Stan

Usage

make_standata(formula, data = NULL, family = "gaussian", autocor = NULL,nonlinear = NULL, partial = NULL, cov_ranef = NULL, control = NULL,...)

Arguments



36 make_standata






control A named list currently for internal usage only

... Other potential arguments

Value

A named list of objects containing the required data to fit a brms model with Stan.

Author(s)


Examples

data1 <- make_standata(rating ~ treat + period + carry + (1|subject),

marginal_effects.brmsfit 37

data = inhaler, family = "cumulative")names(data1)

data2 <- make_standata(count ~ log_Age_c + log_Base4_c * Trt_c+ (1|patient) + (1|visit),data = epilepsy, family = "poisson")

names(data2)

marginal_effects.brmsfit

Display marginal effects of predictors

Description

Display marginal effects of one or more numeric and/or categorical predictors including interactioneffects of order 2.

Usage

## S3 method for class 'brmsfit'marginal_effects(x, effects = NULL, data = NULL,re_formula = NA, probs = c(0.025, 0.975), method = c("fitted","predict"), ...)

marginal_effects(x, ...)

## S3 method for class 'brmsMarginalEffects'plot(x, ncol = NULL, rug = FALSE,theme = ggplot2::theme(), ask = TRUE, do_plot = TRUE, ...)

Arguments

x An object usually of class brmsfit

effects An optional character vector naming effects (main effects or interactions) forwhich to compute marginal plots. If NULL (the default), plots for all effects aregenerated.

data An optional data.frame containing variable values to marginalize on. Eacheffect defined in effects will be plotted separately for each row of data. Therow names of data will be treated as titles of the subplots. It is recommendedto only define a few rows in order to keep the plots clear. If NULL (the default),numeric variables will be marginalized by using their means and factors will gettheir reference level assigned.

re_formula A formula containing random effects to be considered in the marginal predic-tions. If NULL, include all random effects; if NA (default), include no randomeffects.

38 ngrps.brmsfit

probs The quantiles to be used in the computation of credible intervals (defaults to 2.5and 97.5 percent quantiles)

method Either "fitted" or "predict". If "fitted", plot marginal predictions of theregression curve. If "predict", plot marginal predictions of the responses.

... Currently ignored.

ncol Number of plots to display per column for each effect. If NULL (default), ncolis computed internally based on the number of rows of data.

rug Logical; indicating whether a rug representation of predictor values should beadded via geom_rug. Default is FALSE.

theme A theme object modifying the appearance of the plots. For some basic themessee ggtheme. Can be defined globally for the current session, via theme_set.

ask logical; indicates if the user is prompted before a new page is plotted. Only usedif do_plot is TRUE.

do_plot logical; indicates if plots should be plotted directly in the active graphic device.Defaults to TRUE.

Value

A list of ggplot objects one for each effect.

Examples

## Not run:fit <- brm(count ~ log_Age_c + log_Base4_c * Trt_c + (1 | patient),

data = epilepsy, family = poisson())## plot all marginal effectsplot(marginal_effects(fit), ask = FALSE)## only plot the marginal interaction effect of 'log_Base4_c:Trt_c'## for different values for 'log_Age_c'mdata <- data.frame(log_Age_c = c(-0.3, 0, 0.3))plot(marginal_effects(fit, effects = "log_Base4_c:Trt_c",

data = mdata))## also incorporate random effects variance over patients## and add a rug representation of predictor valuesplot(marginal_effects(fit, effects = "log_Base4_c:Trt_c",

data = mdata, re_formula = NULL), rug = TRUE)

## End(Not run)

ngrps.brmsfit Number of levels

Description

Number of levels of one or more grouping factors

pairs.brmsfit 39

Usage

## S3 method for class 'brmsfit'ngrps(object, ...)

Arguments

object An object of class brmsfit.... Currently ignored.

Value

A named list containing the number of levels per grouping factor

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

Description

A pairs method that is customized for MCMC output

Usage

## S3 method for class 'brmsfit'pairs(x, pars = NA, exact_match = FALSE, ...)

Arguments

x An object of class stanfitpars Names of the parameters to plot, as given by a character vector or a regular

expression. By default, all parameters are plotted.exact_match Indicates whether parameter names should be matched exactly or treated as reg-

ular expression. Default is FALSE.... Further arguments to be passed to pairs.stanfit.

Details

For a detailed description see pairs.stanfit.

Examples

## Not run:fit <- brm(count ~ log_Age_c + log_Base4_c * Trt_c

+ (1|patient) + (1|visit),data = epilepsy, family = "poisson")

pairs(fit, pars = parnames(fit)[1:3], exact_match = TRUE)pairs(fit, pars = "^sd")

## End(Not run)

40 plot.brmsfit

parnames Extract Parameter Names

Description

Extract all parameter names of a given model.

Usage

parnames(x, ...)

Arguments

x An R object

... Further arguments passed to or from other methods

Details

Currently there are methods for brmsfit and formula objects.

Value

A character vector containing the parameter names of the model.

Author(s)


plot.brmsfit Trace and Density Plots for MCMC Samples

Description

Trace and Density Plots for MCMC Samples

Usage

## S3 method for class 'brmsfit'plot(x, pars = NA, parameters = NA, N = 5,theme = ggplot2::theme(), ask = TRUE, do_plot = TRUE, newpage = TRUE,...)

posterior_samples.brmsfit 41

Arguments

x An object of class brmsfit.

pars Names of the parameters to plot, as given by a character vector or a regularexpression. By default, all parameters except for random effects are plotted.

parameters A deprecated alias of pars

N The number of parameters plotted per page.

theme A theme object modifying the appearance of the plots. For some basic themessee ggtheme. Can be defined globally for the current session, via theme_set.

ask logical; indicates if the user is prompted before a new page is plotted. Only usedif do_plot is TRUE.

do_plot logical; indicates if plots should be plotted directly in the active graphic device.Defaults to TRUE.

newpage logical; indicates if the first set of plots should be plotted to a new page. Onlyused if do_plot is TRUE.

... Further arguments passed to arrangeGrob.

Value

A (possibly invisible) list of gtable objects.

Author(s)


Examples

## Not run:fit <- brm(count ~ log_Age_c + log_Base4_c * Trt_c


## plot fixed effects as well as standard devations of the random effectsplot(fit)## plot fixed effects onlyplot(fit, pars = "^b_")

## End(Not run)

posterior_samples.brmsfit

Extract posterior samples

Description

Extract posterior samples of specified parameters

42 posterior_samples.brmsfit

Usage

## S3 method for class 'brmsfit'posterior_samples(x, pars = NA, parameters = NA,exact_match = FALSE, add_chain = FALSE, add_chains = FALSE,subset = NULL, as.matrix = FALSE, ...)

posterior_samples(x, pars = NA, ...)

Arguments

x An R object typically of class brmsfit

pars Names of parameters for which posterior samples should be returned, as givenby a character vector or regular expressions. By default, all posterior samples ofall parameters are extracted



add_chain A flag indicating if the returned data.frame should contain two additionalcolumns. The chain column indicates the chain in which each sample wasgenerated, the iter column indicates the iteration number within each chain.

add_chains A deprecated alias of add_chain. Note that the chain column will be namedchains instead.

subset A numeric vector indicating the rows (i.e., posterior samples) to be returned. IfNULL (the default), all posterior samples are returned.

as.matrix Should the output be a matrix instead of a data.frame? Defaults to FALSE

... additional arguments

Details

Currently there are methods for brmsfit objects.

Value

A data frame containing the posterior samples, with one column per parameter.

Author(s)


Examples


data = inhaler, family = "cumulative")

#extract posterior samples of fixed effectssamples1 <- posterior_samples(fit, "^b")

predict.brmsfit 43

head(samples1)

#extract posterior samples of standard deviations of random effectssamples2 <- posterior_samples(fit, "^sd")head(samples2)

## End(Not run)

predict.brmsfit Model Predictions of brmsfit Objects

Description

Predict responses based on the fitted model. Can be performed for the data used to fit the model(posterior predictive checks) or for new data. By definition, these predictions have higher variancethan predictions of the fitted values (i.e. the ’regression line’) performed by the fitted method.This is because the measurement error is incorporated. The estimated means of both methodsshould, however, be very similar.

Usage

## S3 method for class 'brmsfit'predict(object, newdata = NULL, re_formula = NULL,transform = NULL, allow_new_levels = FALSE, subset = NULL,nsamples = NULL, ntrys = 5, summary = TRUE, probs = c(0.025, 0.975),...)

Arguments




transform A function or a character string naming a function to be applied on the predictedresponses before summary statistics are computed.

allow_new_levels




ntrys Parameter used in rejection sampling for truncated discrete models only (de-faults to 5). See Details for more information.

44 predict.brmsfit




Details

For truncated discrete models only: In the absence of any general algorithm to sample from trun-cated discrete distributions, rejection sampling is applied in this special case. This means that valuesare sampled until a value lies within the defined truncation boundaries. In practice, this proceduremay be rather slow (especially in R). Thus, we try to do approximate rejection sampling by sam-pling each value ntrys times and then select a valid value. If all values are invalid, the closestboundary is used, instead. If there are more than a few of these pathological cases, a warning willoccure suggesting to increase argument ntrys.

For models fitted with brms <= 0.5.0 only: Be careful when using newdata with factors in fixed orrandom effects. The predicted results are only valid if all factor levels present in the initial data arealso defined and ordered correctly for the factors in newdata. Grouping factors may contain fewerlevels than in the inital data without causing problems. When using higher versions of brms, allfactors are automatically checked for correctness and amended if necessary.

Value

Predicted values of the response variable. If summary = TRUE the output depends on the family:For catagorical and ordinal families, it is a N x C matrix, where N is the number of observationsand C is the number of categories. For all other families, it is a N x E matrix where E is equal tolength(probs) + 2. If summary = FALSE, the output is as a S x N matrix, where S is the numberof samples.

Examples

## Not run:## fit a modelfit <- brm(time | cens(censored) ~ age + sex + (1+age||patient),

data = kidney, family = "exponential", inits = "0")

## predicted responsespp <- predict(fit)head(pp)

## predicted responses excluding the random effect of agepp2 <- predict(fit, re_formula = ~ (1|patient))head(pp2)

## predicted responses of patient 1 for new datanewdata <- data.frame(sex = factor(c("male", "female")),

age = c(20, 50),patient = c(1, 1))

predict(fit, newdata = newdata)

print.brmsfit 45

## End(Not run)

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

Description

Print basic information regarding the fitted model and a summary for the fixed and random effectsestimated by the samples included in a brmsfit object.

Usage

## S3 method for class 'brmsfit'print(x, digits = 2, ...)

Arguments

x An object of class brmsfit

digits The number of significant digits for printing out the summary; defaults to 2. Theeffective sample size is always rounded to integers.

... Additional arguments that would be passed to method summary of brmsfit.

Author(s)


prior_samples.brmsfit Extract prior samples

Description

Extract prior samples of specified parameters

Usage

## S3 method for class 'brmsfit'prior_samples(x, pars = NA, parameters = NA, ...)

prior_samples(x, pars = NA, ...)

46 ranef.brmsfit

Arguments

x An R object typically of class brmsfit

pars Names of parameters for which prior samples should be returned, as given bya character vector or regular expressions. By default, all prior samples are ex-tracted



Details

To make use of this function, the model must contain samples of prior distributions. This can beensured by setting sample_prior = TRUE in function brm. Currently there are methods for brmsfitobjects.

Value

A data frame containing the prior samples.

Author(s)


Examples


data = inhaler, family = "cumulative",prior = set_prior("normal(0,2)", class = "b"),sample_prior = TRUE)

#extract all prior samplessamples1 <- prior_samples(fit)head(samples1)

#extract prior samples for the fixed effect of \code{treat}.samples2 <- posterior_samples(fit, "b_treat")head(samples2)

## End(Not run)

ranef.brmsfit Extract Random Effects Estimates

Description

Extract the random effects of each level from brmsfit object.

residuals.brmsfit 47

Usage

## S3 method for class 'brmsfit'ranef(object, estimate = "mean", var = FALSE, ...)

Arguments

object An object of class brmsfit.

estimate The point estimate to be calculated for the random effects, either "mean" or"median".

var logical; indicating if the covariance matrix for each random effects should becomputed.

... Further arguments to be passed to the function specified in estimate

Value

A list of matrices (one per grouping factor), with factor levels as row names and random effects ascolumn names

Author(s)


Examples


data = epilepsy, family = "poisson", chains = 1)## random effects means with corresponding covariancesrf <- ranef(fit, var = TRUE)attr(rf, "var")## random effects mediansranef(fit, estimate = "median")

## End(Not run)

residuals.brmsfit Extract Model Residuals from brmsfit Objects

Description

Extract Model Residuals from brmsfit Objects

48 residuals.brmsfit

Usage

## S3 method for class 'brmsfit'residuals(object, newdata = NULL, re_formula = NULL,type = c("ordinary", "pearson"), allow_new_levels = FALSE,subset = NULL, nsamples = NULL, summary = TRUE, probs = c(0.025,0.975), ...)

Arguments




type The type of the residuals, either "ordinary" or "pearson". More informationis provided under ’Details’.

allow_new_levels







Details

Residuals of type ordinary are of the form R = Y − Y p, where Y is the observed and Y p is thepredicted response. Residuals of type pearson are of the form R = (Y − Y p)/SD(Y ), whereSD(Y ) is an estimation of the standard deviation of Y .

Currently, residuals.brmsfit does not support categorical or ordinal models.

Value

Model residuals. If summary = TRUE this is a N x C matrix and if summary = FALSE a S xN matrix, where S is the number of samples, N is the number of observations, and C is equal tolength(probs) + 2.

set_prior 49

Examples

## Not run:## fit a modelfit <- brm(rating ~ treat + period + carry + (1|subject),

data = inhaler, cluster = 2)

## extract residualsres <- residuals(fit, summary = TRUE)head(res)

## End(Not run)

set_prior Prior Definitions for brms Models

Description

Define priors for specific parameters or classes of parameters

Usage

set_prior(prior, class = "b", coef = "", group = "", nlpar = "",lb = NULL, ub = NULL)

Arguments

prior A character string defining a distribution in Stan language

class The parameter class. Defaults to "b" (fixed effects). See ’Details’ for other validparameter classes.

coef Name of the (fixed, category specific, or random effects) parameter

group Grouping factor for random effects parameters.

nlpar Name of a non-linear parameter. Only used in non-linear models.

lb Lower bound for parameter restriction. Currently only allowed if class = "b".Defaults to NULL, that is no restriction.

ub Upper bound for parameter restriction. Currently only allowed if class = "b".Defaults to NULL, that is no restriction.

Details

set_prior is used to define prior distributions for parameters in brms models. Below, we explainits usage and list some common prior distributions for parameters. A complete overview on possibleprior distributions is given in the Stan Reference Manual available at http://mc-stan.org/.

To combine multiple priors, use c(...), e.g., c(set_prior(...), set_prior(...)). brms per-forms no checks if the priors are written in correct Stan language. Instead, Stan will check theircorrectness when the model is parsed to C++ and returns an error if they are not. Currently, there

http://mc-stan.org/

50 set_prior

are five types of parameters in brms models, for which the user can specify prior distributions.

1. Fixed and category specific effects

Every fixed (and category specific) effect has its own regression parameter. These parameters areinternally named as b_<fixed>, where <fixed> represents the name of the corresponding fixedeffect. Suppose, for instance, that y is predicted by x1 and x2 (i.e. y ~ x1+x2 in formula syntax).Then, x1 and x2 have regression parameters b_x1 and b_x2 respectively. The default prior for fixedand category specific effects is an improper flat prior over the reals. Other common options arenormal priors or student-t priors. If we want to have a normal prior with mean 0 and standarddeviation 5 for x1, and a unit student-t prior with 10 degrees of freedom for x2, we can specify thisvia set_prior("normal(0,5)", class = "b", coef = "x1") andset_prior("student_t(10,0,1)", class = "b", coef = "x2"). To put the same prior onall fixed effects at once, we may write as a shortcut set_prior("<prior>", class = "b"). Thisalso leads to faster sampling, because priors can be vectorized in this case. Both ways of definingpriors can be combined using for instance set_prior("normal(0,2)", class = "b") andset_prior("normal(0,10)", class = "b", coef = "x1") at the same time. This will set anormal(0,10) prior on the fixed effect of x1 and a normal(0,2) prior on all other fixed effects.However, this will break vectorization and may slow down the sampling procedure a bit.

In case of the default intercept parameterization (discussed in the ’Details’ section of brm), the fixedeffects intercept has its own parameter class named "Intercept" and priors can thus be specifiedvia set_prior("<prior>", class = "Intercept"). Setting a prior on the intercept will notbreak vectorization of the other fixed effects.

A special shrinkage prior to be applied on fixed effects is the horseshoe prior. It is symmetric aroundzero with fat tails and an infinitely large spike at zero. This makes it ideal for sparse models thathave many regression coefficients,although only a minority of them is non-zero. For more detailssee Carvalho et al. (2009). The horseshoe prior can be applied on all fixed effects at once (exclud-ing the intercept) by using set_prior("horseshoe(1)"). The 1 implies that the student-t prior ofthe local shrinkage parameters has 1 degrees of freedom. This may, however, lead to an increasednumber of divergent transition in Stan. Accordingly, increasing the degrees of freedom to slightlyhigher values (e.g., 3) may often be a better option, although the prior no longer resembles a horse-shoe in this case. Generally, models with horseshoe priors a more likely than other models to havedivergent transitions so that increasing adapt_delta from 0.8 to values closer to 1 will often benecessary. See the documentation of brm for instructions on how to increase adapt_delta.

In non-linear models, fixed effects are defined separately for each non-linear parameter. Accord-ingly, it is necessary to specify the corresponding non-linear parameter in set_prior so that priorswe can be assigned correctly. If, for instance, alpha is the parameter and x the predictor for whichwe want to define the prior, we can write set_prior("<prior>", coef = "x", nlpar = "alpha").As a shortcut we can use set_prior("<prior>", nlpar = "alpha") to set the same prior on allfixed effects of alpha at once.

If desired, fixed effects parameters can be restricted to fall only within a certain interval using thelb and ub arguments of set_prior. This is often required when defining priors that are not definedeverywhere on the real line, such as uniform or gamma priors. When defining a uniform(2,4)prior, you should write set_prior("uniform(2,4)", lb = 2, ub = 4). When using a prior thatis defined on the postive reals only (such as a gamma prior) set lb = 0. In most situations, it is notuseful to restrict fixed effects parameters through bounded priors, but if you really want to this isthe way to go.

set_prior 51

3. Autocorrelation parameters

The autocorrelation parameters currently implemented are named ar (autoregression), ma (movingaverage), and arr (autoregression of the response). Priors can be defined by set_prior("<prior>", class = "ar")for ar and similar for ma and arr effects. By default, ar and ma are bounded between -1 and 1 andarr is unbounded (you may change this by using the arguments lb and ub). The default prior is flatover the definition area.

4. Standard deviations of random effects

Each random effect of each grouping factor has a standard deviation named sd_<group>_<random>.Consider, for instance, the formula y ~ x1+x2+(1+x1|g). We see that the intercept as well as x1are random effects nested in the grouping factor g. The corresponding standard deviation param-eters are named as sd_g_Intercept and sd_g_x1 respectively. These parameters are restriced tobe non-negative and, by default, have a half student-t prior with 3 degrees of freedom and a scaleparameter that depends on the standard deviation of the response after applying the link function.Minimally, the scale parameter is 5. To define a prior distribution only for standard deviations of aspecific grouping factor, useset_prior("<prior>", class = "sd", group = "<group>"). To define a prior distributiononly for a specific standard deviation of a specific grouping factor, you may writeset_prior("<prior>", class = "sd", group = "<group>", coef = "<coef>"). Recom-mendations on useful prior distributions for standard deviations are given in Gelman (2006).

When defining priors on random effects parameters in non-linear models, please make sure to spec-ify the corresponding non-linear parameter through the nlpar argument in the same way as forfixed effects.

5. Correlations of random effects

If there is more than one random effect per grouping factor, the correlations between those randomeffects have to be estimated. The prior "lkj_corr_cholesky(eta)" or in short "lkj(eta)" witheta > 0 is essentially the only prior for (choelsky factors) of correlation matrices. If eta = 1(the default) all correlations matrices are equally likely a priori. If eta > 1, extreme correlationsbecome less likely, whereas 0 < eta < 1 results in higher probabilities for extreme correla-tions. Correlation matrix parameters in brms models are named as cor_(group), (e.g., cor_gif g is the grouping factor). To set the same prior on every correlation matrix, use for instanceset_prior("lkj(2)", class = "cor").

6. Parameters for specific families

Some families need additional parameters to be estimated. Families gaussian, student, andcauchy need the parameter sigma to account for the residual standard deviation. By default, sigmahas a half student-t prior that scales in the same way as the random effects standard deviations. Fur-thermore, family student needs the parameter nu representing the degrees of freedom of studentst distribution. By default, nu has prior "gamma(2,0.1)" and a fixed lower bound of 1. Fami-lies gamma, weibull, inverse.gaussian, and negbinomial need a shape parameter that has a"student_t(3,0,5)" prior by default. For families cumulative, cratio, sratio, and acat, andonly if threshold = "equidistant", the parameter delta is used to model the distance betweentwo adjacent thresholds. By default, delta has an improper flat prior over the reals.Every family specific parameter has its own prior class, so thatset_prior("<prior>", class = "<parameter>") it the right way to go.

Often, it may not be immediately clear, which parameters are present in the model. To get a full listof parameters and parameter classes for which priors can be specified (depending on the model) use

52 stancode

function get_prior.

Value

An object of class brmsprior to be used in the prior argument of brm.

References

Gelman A (2006). Prior distributions for variance parameters in hierarchical models. Bayesiananalysis, 1(3), 515 – 534.

Carvalho, C. M., Polson, N. G., & Scott, J. G. (2009). Handling sparsity via the horseshoe. InInternational Conference on Artificial Intelligence and Statistics (pp. 73-80).

See Also

get_prior

Examples

## check which parameters can have priorsget_prior(rating ~ treat + period + carry + (1|subject),

data = inhaler, family = sratio(),threshold = "equidistant")

## define some priorsprior <- c(set_prior("normal(0,10)", class = "b"),

set_prior("normal(1,2)", class = "b", coef = "treat"),set_prior("cauchy(0,2)", class = "sd",

group = "subject", coef = "Intercept"),set_prior("uniform(-5,5)", class = "delta"))

## verify that the priors indeed found their way into Stan's model codemake_stancode(rating ~ period + carry + (1|subject),

data = inhaler, family = sratio(),partial = ~ treat, threshold = "equidistant",prior = prior)

## use horseshoe priors to model sparsity in fixed effects parametersmake_stancode(count ~ log_Age_c + log_Base4_c * Trt_c,

data = epilepsy, family = poisson(),prior = set_prior("horseshoe(3)"))

stancode Extract Stan Model Code

Description

Extract the model code in Stan language

standata 53

Usage

stancode(object, ...)

Arguments



Value

model code in stan language for further processing.

standata Extract Data passed to Stan

Description

Extract all data that was used by Stan to fit the model

Usage

standata(object, ...)

Arguments



Value

A named list containing the data passed to Stan

stanplot.brmsfit Various Plotting Functions implemented in rstan

Description

Conveniant way to call plotting functions implemented in the rstan package.

Usage

## S3 method for class 'brmsfit'stanplot(object, pars = NA, type = "plot",exact_match = FALSE, quiet = FALSE, ...)

stanplot(object, pars, ...)

54 stanplot.brmsfit

Arguments

object An R object typically of class brmsfit

pars Names of parameters to be plotted, as given by a character vector or regularexpressions. By default, the first 10 parameters are plotted.

type The type of the plot. Supported types are (as names) plot, trace, hist, dens,scat, diag, rhat, ess, mcse, ac. For an overview on the various plot types seeplotting-functions.


quiet A flag indicating whether messages produced by ggplot2 during the plottingprocess should be silenced. Default is FALSE.

... Additional arguments passed to the plotting functions.

Details

Instead of using stanplot(<brmsfit-object>), the plotting functions can be called directly viastan_<plot-type>(<brmsfit-object>$fit). For more details on the plotting functions seePlots as well as Diagnostic plots. Note that the plotting functions themselves only acceptfull parameter names, while stanplot allows for partial matching and regular expressions. Youshould also consider using the shinystan package available via method launch_shiny in brms forflexible and interactive visual analysis.

Value

A ggplot object that can be further customized using the ggplot2 package.

Examples

## Not run:model <- brm(count ~ log_Age_c + log_Base4_c * Trt_c


# plot 95% CIsstanplot(model, type = "plot", ci_level = 0.95)# equivalent tostan_plot(model$fit, ci_level = 0.95)

# only show fixed effects in the plots# this will not work when calling stan_plot directlystanplot(model, pars = "^b", type = "plot", ci_level = 0.95)

# plot some diagnostics on the samplerstanplot(model, type = "diag")# equivalent tostan_diag(model$fit)

## End(Not run)

summary.brmsfit 55

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

Description

Summarize estimated fixed and random effects as well as other useful results included in a brmsfitobject.

Usage

## S3 method for class 'brmsfit'summary(object, waic = FALSE, ...)

Arguments


waic logical; indicating if the WAIC should be computed (this will take some timefor larger models). Default is FALSE.

... Other potential arguments

Author(s)


update.brmsfit Update brms models

Description

This method allows to update an existing brmsfit object with new data as well as changed config-uration of the chains.

Usage

## S3 method for class 'brmsfit'update(object, newdata = NULL, ...)

Arguments

object object of class brmsfit

newdata optional data.frame to update the model with new data

... other arguments passed to brm such as iter or chains.

56 VarCorr.brmsfit

VarCorr.brmsfit Extract variance and correlation components

Description

This function calculates the estimated standard deviations, correlations and covariances of therandom-effects terms in a mixed-effects model of class brmsfit. For linear models, the residualstandard deviations, correlations and covariances are also returned.

Usage

## S3 method for class 'brmsfit'VarCorr(x, sigma = 1, estimate = "mean", as.list = TRUE,...)

## S3 method for class 'brmsVarCorr'as.data.frame(x, ...)

Arguments

x An object of class brmsift.

sigma Ignored (included for compatibility with VarCorr).

estimate A character vector specifying which summary statistics (e.g., "mean", "median","sd", or "quantile") should be calculated for the extracted parameters.

as.list logical; Indicates if covariance and correlation matrices should be returned aslists of matrices (the default), or as 3-dimensional arrays. We recommend not toset as.list to FALSE.

... Further arguments to be passed to the functions specified in estimate

Value

An object of class brmsVarCorr, which is a list of lists (one per grouping factor), each containing3 elements: a matrix containing the standard deviations, a list of correlation matrices, and a list ofcovariance matrices. Can be coerced to a data.frame by using the as.data.frame method.

Author(s)


Examples


data = epilepsy, family = "poisson", chains = 1)## return the means of random effects covariances(vc <- VarCorr(fit))as.data.frame(vc)

vcov.brmsfit 57

## return 2.5% and 97.5% quantiles of random effects covariancesVarCorr(fit, estimate = "quantile", probs = c(0.025, 0.975))

## End(Not run)

vcov.brmsfit Covariance and Correlation Matrix of Fixed Effects

Description

Get a point estimate of the covariance or correlation matrix of fixed effects parameters

Usage

## S3 method for class 'brmsfit'vcov(object, correlation = FALSE, ...)

Arguments


correlation logical; if FALSE (the default), compute the covariance matrix, if TRUE, computethe correlation matrix


Details

Estimates are obtained by calculating the maximum likelihood covariances (correlations) of theposterior samples.

Value

covariance or correlation matrix of fixed effects parameters

WAIC.brmsfit Compute the WAIC

Description

Compute the Watanabe-Akaike Information Criterion based on the posterior likelihood by using theloo package

58 WAIC.brmsfit

Usage

## S3 method for class 'brmsfit'WAIC(x, ..., compare = TRUE, newdata = NULL,re_formula = NULL, allow_new_levels = FALSE, subset = NULL,nsamples = NULL)

WAIC(x, ..., compare = TRUE)

Arguments


... Optionally more fitted model objects.

compare A flag indicating if the WAICs of the models should be compared to each other.



allow_new_levels




Details

When comparing models fitted to the same data, the smaller the WAIC, the better the fit.

Value

If just one object is provided, an object of class ic. If multiple objects are provided, an object ofclass iclist.

Methods (by class)

• brmsfit: method for class brmsfit

Author(s)


WAIC.brmsfit 59

References

Vehtari, A., Gelman, A., and Gabry, J. (2015). Efficient implementation of leave-one-out cross-validation and WAIC for evaluating fitted Bayesian models.

Gelman, A., Hwang, J., & Vehtari, A. (2014). Understanding predictive information criteria forBayesian models. Statistics and Computing, 24, 997-1016.

Watanabe, S. (2010). Asymptotic equivalence of Bayes cross validation and widely applicableinformation criterion in singular learning theory. The Journal of Machine Learning Research, 11,3571-3594.

Examples

## Not run:#model with fixed effects onlyfit1 <- brm(rating ~ treat + period + carry,

data = inhaler, family = "gaussian")WAIC(fit1)

#model with an additional random intercept for subjectsfit2 <- brm(rating ~ treat + period + carry + (1|subject),

data = inhaler, family = "gaussian")#compare both modelsWAIC(fit1, fit2)

## End(Not run)

Index

∗Topic datasetsepilepsy, 20inhaler, 28kidney, 29

∗Topic packagebrms-package, 3

acat (brmsfamily), 12arrangeGrob, 41as.data.frame.brmsVarCorr

(VarCorr.brmsfit), 56as.mcmc (as.mcmc.brmsfit), 4as.mcmc.brmsfit, 4

bernoulli (brmsfamily), 12Beta (brmsfamily), 12binomial, 10brm, 3, 4, 12–14, 50, 52, 55brm.data (make_standata), 35brmdata (make_standata), 35brms, 13, 14brms (brms-package), 3brms-package, 3brmsfamily, 5, 8, 12, 24, 34, 36brmsfit, 3brmsfit (brmsfit-class), 13brmsfit-class, 13

categorical (brmsfamily), 12cauchy (brmsfamily), 12coef, 14coef.brmsfit, 14cor.ar (cor_ar), 15cor.arma (cor_arma), 16cor.ma (cor_ma), 19cor_ar, 15, 17, 19cor_arma, 16, 16, 18–20cor_arr, 17, 18, 19cor_brms, 5, 19, 25, 34, 36cor_brms-class (cor_brms), 19

cor_ma, 17, 19, 19cratio (brmsfamily), 12cumulative (brmsfamily), 12

epilepsy, 20exponential (brmsfamily), 12

family, 5, 12, 14, 24, 34, 36fitted, 14, 43fitted.brmsfit, 21fixef, 14fixef (fixef.brmsfit), 23fixef.brmsfit, 23formula, 14

Gamma, 10geom_rug, 38geometric (brmsfamily), 12get_prior, 5, 10, 24, 34, 52ggplot, 54ggtheme, 26, 38, 41gtable, 41

hurdle_gamma (brmsfamily), 12hurdle_negbinomial (brmsfamily), 12hurdle_poisson (brmsfamily), 12hypothesis, 14hypothesis (hypothesis.brmsfit), 26hypothesis.brmsfit, 26

inhaler, 28

kidney, 29

launch_shiny, 3, 14, 30, 54launch_shinystan, 30logLik, 14logLik.brmsfit, 31LOO, 3, 14LOO (LOO.brmsfit), 31loo, 32

60

INDEX 61

LOO.brmsfit, 31

make_stancode, 33make_standata, 35makeCluster, 6marginal_effects

(marginal_effects.brmsfit), 37marginal_effects.brmsfit, 37model.frame, 14

negbinomial (brmsfamily), 12ngrps, 14ngrps (ngrps.brmsfit), 38ngrps.brmsfit, 38nobs, 14

pairs, 14, 39pairs.brmsfit, 39pairs.stanfit, 39par.names (parnames), 40parnames, 14, 26, 40plot, 3, 14plot.brmsfit, 40plot.brmshypothesis

(hypothesis.brmsfit), 26plot.brmsMarginalEffects

(marginal_effects.brmsfit), 37Plots, 54posterior.samples

(posterior_samples.brmsfit), 41posterior_samples, 14posterior_samples

(posterior_samples.brmsfit), 41posterior_samples.brmsfit, 41predict, 14, 21predict.brmsfit, 43print, 14print.brmsfit, 45print.brmssummary (print.brmsfit), 45prior_samples, 14prior_samples (prior_samples.brmsfit),

45prior_samples.brmsfit, 45

ranef, 14ranef (ranef.brmsfit), 46ranef.brmsfit, 46residuals, 14residuals.brmsfit, 47

runApp, 30

set_prior, 5, 9, 10, 25, 34, 49sratio (brmsfamily), 12stan, 6, 10stancode, 14, 52standata, 14, 53stanplot, 14stanplot (stanplot.brmsfit), 53stanplot.brmsfit, 53student (brmsfamily), 12summary, 3, 14summary.brmsfit, 55

theme, 26, 38, 41theme_set, 26, 38, 41

update, 14update.brmsfit, 55

VarCorr, 14, 56VarCorr (VarCorr.brmsfit), 56VarCorr.brmsfit, 56vcov, 14vcov.brmsfit, 57

WAIC, 3, 14WAIC (WAIC.brmsfit), 57WAIC.brmsfit, 57weibull (brmsfamily), 12

zero_inflated_beta (brmsfamily), 12zero_inflated_binomial (brmsfamily), 12zero_inflated_negbinomial (brmsfamily),

12zero_inflated_poisson (brmsfamily), 12

Documents

Package ‘brms’ - Michigan Technological University · Package ‘brms ’ February 15, 2016 ... Gamma, inverse.gaussian, exponential, weibull, ... tions and brmsfamily for family