pareto_smooth: Pareto smoothing

In posterior: Tools for Working with Posterior Distributions

Pareto smoothing

Description

Smooth the tail draws of x by replacing tail draws by order statistics of a generalized Pareto distribution fit to the tail(s). For further details see Vehtari et al. (2022).

Usage

pareto_smooth(x, ...)

## S3 method for class 'rvar'
pareto_smooth(x, return_k = TRUE, extra_diags = FALSE, ...)

## Default S3 method:
pareto_smooth(
  x,
  tail = c("both", "right", "left"),
  r_eff = NULL,
  ndraws_tail = NULL,
  return_k = TRUE,
  extra_diags = FALSE,
  verbose = FALSE,
  ...
)

Arguments

x	(multiple options) One of: A matrix of draws for a single variable (iterations x chains). See extract_variable_matrix(). An rvar.
...	Arguments passed to individual methods (if applicable).
return_k	(logical) Should the Pareto khat be included in output? If TRUE, output will be a list containing of smoothed draws and diagnostics. Default is TRUE.
extra_diags	(logical) Should extra Pareto khat diagnostics be included in output? If TRUE, min_ss, khat_threshold and convergence_rate for the estimated k value will be returned. Default is FALSE.
tail	(string) The tail to diagnose/smooth: "right": diagnose/smooth only the right (upper) tail "left": diagnose/smooth only the left (lower) tail "both": diagnose/smooth both tails and return the maximum k-hat value The default is "both".
r_eff	(numeric) relative effective sample size estimate. If r_eff is omitted, it will be calculated assuming the draws are from MCMC.
ndraws_tail	(numeric) number of draws for the tail. If ndraws_tail is not specified, it will be calculated as ceiling(3 * sqrt(length(x) / r_eff)) if length(x) > 225 and length(x) / 5 otherwise (see Appendix H in Vehtari et al. (2022)).
verbose	(logical) Should diagnostic messages be printed? If TRUE, messages related to Pareto diagnostics will be printed. Default is FALSE.

Value

Either a vector x of smoothed values or a named list containing the vector x and a named list diagnostics containing Pareto smoothing diagnostics:

• khat: estimated Pareto k shape parameter, and optionally

• min_ss: minimum sample size for reliable Pareto smoothed estimate

• khat_threshold: khat-threshold for reliable Pareto smoothed estimates

• convergence_rate: Relative convergence rate for Pareto smoothed estimates

References

Aki Vehtari, Daniel Simpson, Andrew Gelman, Yuling Yao and Jonah Gabry (2022). Pareto Smoothed Importance Sampling. arxiv:arXiv:1507.02646

Examples

mu <- extract_variable_matrix(example_draws(), "mu")
pareto_smooth(mu)

d <- as_draws_rvars(example_draws("multi_normal"))
pareto_smooth(d$Sigma)

posterior documentation built on Nov. 2, 2023, 5:56 p.m.