brms_tidiers: Tidying methods for a brms model

In broom.mixed: Tidying Methods for Mixed Models

Tidying methods for a brms model

Description

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

Usage

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

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

## S3 method for class '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")
rhat	whether to calculate the *Rhat* convergence metric (FALSE by default)
ess	whether to calculate the *effective sample size* (ESS) convergence metric (FALSE by default)
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.

See Also

brms, brmsfit-class

Examples

 ## original model
 ## Not run: 
    brms_crossedRE <- brm(mpg ~ wt + (1|cyl) + (1+wt|gear), data = mtcars,
           iter = 500, chains = 2)
 
## End(Not run)
 
   ## too slow for CRAN (>5 seconds)
   ## load stored object
   if (require("rstan") && require("brms")) {
      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)
      if (require("posterior")) {
      tidy(fit, effects = "ran_pars", rhat = TRUE, ess = TRUE)
   
   }
   }
   if (require("rstan") && require("brms")) {
   # 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))
  }

broom.mixed documentation built on Oct. 16, 2024, 1:06 a.m.