Tidying methods for a brms model

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.

Examples

 ## original model
 if (FALSE) { # \dontrun{
    brms_crossedRE <- brm(mpg ~ wt + (1|cyl) + (1+wt|gear), data = mtcars,
           iter = 500, chains = 2)
 } # }
 # \donttest{
   ## 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)
   
   }
   }
#> Loading required package: rstan
#> Loading required package: StanHeaders
#> 
#> rstan version 2.32.7 (Stan version 2.32.2)
#> For execution on a local, multicore CPU with excess RAM we recommend calling
#> options(mc.cores = parallel::detectCores()).
#> To avoid recompilation of unchanged Stan programs, we recommend calling
#> rstan_options(auto_write = TRUE)
#> For within-chain threading using `reduce_sum()` or `map_rect()` Stan functions,
#> change `threads_per_chain` option:
#> rstan_options(threads_per_chain = 1)
#> Loading required package: brms
#> Loading required package: Rcpp
#> Loading 'brms' package (version 2.23.0). Useful instructions
#> can be found by typing help('brms'). A more detailed introduction
#> to the package is available through vignette('brms_overview').
#> 
#> Attaching package: ‘brms’
#> The following object is masked from ‘package:rstan’:
#> 
#>     loo
#> The following object is masked from ‘package:lme4’:
#> 
#>     ngrps
#> The following object is masked from ‘package:stats’:
#> 
#>     ar
#> Loading required package: posterior
#> This is posterior version 1.6.1
#> 
#> Attaching package: ‘posterior’
#> The following objects are masked from ‘package:rstan’:
#> 
#>     ess_bulk, ess_tail
#> The following objects are masked from ‘package:stats’:
#> 
#>     mad, sd, var
#> The following objects are masked from ‘package:base’:
#> 
#>     %in%, match
#> # A tibble: 5 × 10
#>   effect component group term  estimate std.error conf.low conf.high  rhat   ess
#>   <chr>  <chr>     <chr> <chr>    <dbl>     <dbl>    <dbl>     <dbl> <dbl> <dbl>
#> 1 ran_p… cond      cyl   sd__…    3.04      1.99    0.834      8.76   1.01  79.5
#> 2 ran_p… cond      gear  sd__…    3.91      3.46    0.310     12.9    1.01  50.8
#> 3 ran_p… cond      gear  sd__…    1.38      0.922   0.0326     3.24   1.02  38.4
#> 4 ran_p… cond      gear  cor_…   -0.455     0.508  -0.988      0.724  1.02  61.5
#> 5 ran_p… cond      Resi… sd__…    2.57      0.393   1.96       3.48   1.03  69.4
   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))
  }
#> # A tibble: 6 × 7
#>     mpg    wt   cyl  gear .fitted .se.fit .resid
#>   <dbl> <dbl> <dbl> <dbl>   <dbl>   <dbl>  <dbl>
#> 1  21    2.62     6     4    22.7    2.87 -1.41 
#> 2  21    2.88     6     4    21.6    3.10 -0.534
#> 3  22.8  2.32     4     4    26.3    2.86 -2.77 
#> 4  21.4  3.22     6     3    19.9    2.88  2.27 
#> 5  18.7  3.44     8     3    16.9    2.66  1.17 
#> 6  18.1  3.46     6     3    18.4    2.87 -0.425
# }

Usage

Arguments

Value

Note

See also

Examples