draws_summary: Summaries of `draws` objects

Description

The summarise_draws() (and summarize_draws()) methods provide a quick way to get a table of summary statistics and diagnostics. These methods will convert an object to a draws object if it isn't already. For convenience, a summary() method for draws and rvar objects are also provided as an alias for summarise_draws() if the input object is a draws or rvar object.

Usage

summarise_draws(.x, ...)
summarize_draws(.x, ...)
# S3 method for draws
summarise_draws(
  .x,
  ...,
  .args = list(),
  .num_args = getOption("posterior.num_args", list()),
  .cores = 1
)
# S3 method for draws
summary(object, ...)
# S3 method for rvar
summarise_draws(.x, ...)
# S3 method for rvar
summary(object, ...)
default_summary_measures()
default_convergence_measures()
default_mcse_measures()

Value

The summarise_draws() methods return a tibble data frame. The first column ("variable") contains the variable names and the remaining columns contain summary statistics and diagnostics.

The functions default_summary_measures(), default_convergence_measures(), and default_mcse_measures() return character vectors of names of the default measures.

Arguments

.x, object: (draws) A draws object or one coercible to a draws object.
...: Name-value pairs of summary or diagnostic functions. The provided names will be used as the names of the columns in the result unless the function returns a named vector, in which case the latter names are used. The functions can be specified in any format supported by as_function(). See Examples.
.args: (named list) Optional arguments passed to the summary functions.
.num_args: (named list) Optional arguments passed to num() for pretty printing of summaries. Can be controlled globally via the posterior.num_args option.
.cores: (positive integer) The number of cores to use for computing summaries for different variables in parallel. Coerced to integer if possible, otherwise errors. The default is .cores = 1, in which case no parallelization is implemented. By default, a socket cluster is used on Windows and forks otherwise.

Details

The default summary functions used are the ones specified by default_summary_measures() and default_convergence_measures():

default_summary_measures()

mean()
median()
sd()
mad()
quantile2()

default_convergence_measures()

rhat()
ess_bulk()
ess_tail()

The var() function should not be used to compute variances due to its inconsistent behavior with matrices. Instead, please use distributional::variance().

Examples

Run this code

x <- example_draws("eight_schools")
class(x)
str(x)

summarise_draws(x)
summarise_draws(x, "mean", "median")
summarise_draws(x, mean, mcse = mcse_mean)
summarise_draws(x, ~quantile(.x, probs = c(0.4, 0.6)))

# using default_*_meaures()
summarise_draws(x, default_summary_measures())
summarise_draws(x, default_convergence_measures())
summarise_draws(x, default_mcse_measures())

# compute variance of variables
summarise_draws(x, var = distributional::variance)

# illustrate use of '.args'
ws <- rexp(ndraws(x))
summarise_draws(x, weighted.mean, .args = list(w = ws))

# adjust how numerical summaries are printed
summarise_draws(x, .num_args = list(sigfig = 2, notation = "dec"))