Tidying methods for a brms model

These methods tidy the estimates from brmsfit-objects (fitted model objects from the brms package) into a summary.

# S3 method for brmsfit
tidy(
  x,
  parameters = NA,
  effects = c("fixed", "ran_pars"),
  robust = FALSE,
  conf.int = TRUE,
  conf.level = 0.95,
  conf.method = c("quantile", "HPDinterval"),
  fix.intercept = TRUE,
  exponentiate = FALSE,
  ...
)

# S3 method for brmsfit
glance(x, looic = FALSE, ...)

# S3 method for brmsfit
augment(x, data = stats::model.frame(x), newdata = NULL, se.fit = TRUE, ...)

Arguments

x: Fitted model object from the brms package. See brmsfit-class.
parameters: Names of parameters for which a summary should be returned, as given by a character vector or regular expressions. If NA (the default) summarized parameters are specified by the effects argument.
effects: A character vector including one or more of "fixed", "ran_vals", or "ran_pars". See the Value section for details.
robust: Whether to use median and median absolute deviation of the posterior distribution, rather than mean and standard deviation, to derive point estimates and uncertainty
conf.int: If TRUE columns for the lower (conf.low) and upper bounds (conf.high) of posterior uncertainty intervals are included.
conf.level: Defines the range of the posterior uncertainty conf.int, such that 100 * conf.level% of the parameter's posterior distributio lies within the corresponding interval. Only used if conf.int = TRUE.
conf.method: method for computing confidence intervals ("quantile" or "HPDinterval")
fix.intercept: rename "Intercept" parameter to "(Intercept)", to match behaviour of other model types?
exponentiate: whether to exponentiate the fixed-effect coefficient estimates and confidence intervals (common for logistic regression); if TRUE, also scales the standard errors by the exponentiated coefficient, transforming them to the new scale
...: Extra arguments, not used
looic: Should the LOO Information Criterion (and related info) be included? See loo.stanfit for details. (This can be slow for models fit to large datasets.)
data: data frame
newdata: new data frame
se.fit: return standard errors of fit?

Value

All tidying methods return a data.frame without rownames. The structure depends on the method chosen. When parameters = NA, the effects argument is used to determine which parameters to summarize. Generally, tidy.brmsfit returns one row for each coefficient, with at least three columns:

term: The name of the model parameter.
estimate: A point estimate of the coefficient (mean or median).
std.error: A standard error for the point estimate (sd or mad).

When effects = "fixed", only population-level effects are returned. When effects = "ran_vals", only group-level effects are returned. In this case, two additional columns are added:

group: The name of the grouping factor.
level: The name of the level of the grouping factor.

Specifying effects = "ran_pars" selects the standard deviations and correlations of the group-level parameters. If conf.int = TRUE, columns for the lower and upper bounds of the posterior conf.int computed.

Note

The names ‘fixed’, ‘ran_pars’, and ‘ran_vals’ (corresponding to "non-varying", "hierarchical", and "varying" respectively in previous versions of the package), while technically inappropriate in a Bayesian setting where "fixed" and "random" effects are not well-defined, are used for compatibility with other (frequentist) mixed model types.

At present, the components of parameter estimates are separated by parsing the column names of as_draws (e.g. r_patient[1,Intercept] for the random effect on the intercept for patient 1, or b_Trt1 for the fixed effect Trt1. We try to detect underscores in parameter names and warn, but detection may be imperfect.

Examples

 ## original model
 if (FALSE) {
    brms_crossedRE <- brm(mpg ~ wt + (1|cyl) + (1+wt|gear), data = mtcars,
           iter = 500, chains = 2)
 }
 if (.Platform$OS.type!="windows" && require("brms")) {
   ## too slow on Windows, skip (>5 seconds on r-devel-windows)
   ## load stored object
   load(system.file("extdata", "brms_example.rda", package="broom.mixed"))

   fit <- brms_crossedRE
   tidy(fit)
   tidy(fit, parameters = "^sd_", conf.int = FALSE)
   tidy(fit, effects = "fixed", conf.method="HPDinterval")
   tidy(fit, effects = "ran_vals")
   tidy(fit, effects = "ran_pars", robust = TRUE)
   # glance method
   glance(fit)
   ## this example will give a warning that it should be run with
   ## reloo=TRUE; however, doing this will fail
   ## because the \code{fit} object has been stripped down to save space
   suppressWarnings(glance(fit, looic = TRUE, cores = 1))
   head(augment(fit))
}
#> Loading required package: brms
#> Warning: there is no package called ‘brms’

Arguments

Value

Note

See also

Examples