draws_summary {posterior}

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 class 'draws'
summarise_draws(
  .x,
  ...,
  .args = list(),
  .num_args = getOption("posterior.num_args", list()),
  .cores = 1
)

## S3 method for class 'draws'
summary(object, ...)

## S3 method for class 'rvar'
summarise_draws(.x, ...)

## S3 method for class 'rvar'
summary(object, ...)

default_summary_measures()

default_convergence_measures()

default_mcse_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().

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.

See Also

diagnostics for a list of available diagnostics and links to their individual help pages.

Examples

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"))