Describe Posterior Distributions — describe

Compute indices relevant to describe and characterize the posterior distributions.

Usage

describe_posterior(posterior, ...)

# S3 method for numeric
describe_posterior(
  posterior,
  centrality = "median",
  dispersion = FALSE,
  ci = 0.95,
  ci_method = "eti",
  test = c("p_direction", "rope"),
  rope_range = "default",
  rope_ci = 0.95,
  keep_iterations = FALSE,
  bf_prior = NULL,
  BF = 1,
  verbose = TRUE,
  ...
)

# S3 method for stanreg
describe_posterior(
  posterior,
  centrality = "median",
  dispersion = FALSE,
  ci = 0.95,
  ci_method = "eti",
  test = c("p_direction", "rope"),
  rope_range = "default",
  rope_ci = 0.95,
  keep_iterations = FALSE,
  bf_prior = NULL,
  diagnostic = c("ESS", "Rhat"),
  priors = FALSE,
  effects = c("fixed", "random", "all"),
  component = c("location", "all", "conditional", "smooth_terms", "sigma",
    "distributional", "auxiliary"),
  parameters = NULL,
  BF = 1,
  verbose = TRUE,
  ...
)

# S3 method for brmsfit
describe_posterior(
  posterior,
  centrality = "median",
  dispersion = FALSE,
  ci = 0.95,
  ci_method = "eti",
  test = c("p_direction", "rope"),
  rope_range = "default",
  rope_ci = 0.95,
  keep_iterations = FALSE,
  bf_prior = NULL,
  diagnostic = c("ESS", "Rhat"),
  effects = c("fixed", "random", "all"),
  component = c("conditional", "zi", "zero_inflated", "all", "location",
    "distributional", "auxiliary"),
  parameters = NULL,
  BF = 1,
  priors = FALSE,
  verbose = TRUE,
  ...
)

Arguments

posterior: A vector, data frame or model of posterior draws. bayestestR supports a wide range of models (see methods("describe_posterior")) and not all of those are documented in the 'Usage' section, because methods for other classes mostly resemble the arguments of the .numeric method.
...: Additional arguments to be passed to or from methods.
centrality: The point-estimates (centrality indices) to compute. Character (vector) or list with one or more of these options: "median", "mean", "MAP" (see map_estimate()), "trimmed" (which is just mean(x, trim = threshold)), "mode" or "all".
dispersion: Logical, if TRUE, computes indices of dispersion related to the estimate(s) (SD and MAD for mean and median, respectively). Dispersion is not available for "MAP" or "mode" centrality indices.
ci: Value or vector of probability of the CI (between 0 and 1) to be estimated. Default to 0.95 (95%).
ci_method: The type of index used for Credible Interval. Can be "ETI" (default, see eti()), "HDI" (see hdi()), "BCI" (see bci()), "SPI" (see spi()), or "SI" (see si()).
test: The indices of effect existence to compute. Character (vector) or list with one or more of these options: "p_direction" (or "pd"), "rope", "p_map", "equivalence_test" (or "equitest"), "bayesfactor" (or "bf") or "all" to compute all tests. For each "test", the corresponding bayestestR function is called (e.g. rope() or p_direction()) and its results included in the summary output.
rope_range: ROPE's lower and higher bounds. Should be a list of two values (e.g., c(-0.1, 0.1)) or "default". If "default", the bounds are set to x +- 0.1*SD(response).
rope_ci: The Credible Interval (CI) probability, corresponding to the proportion of HDI, to use for the percentage in ROPE.
keep_iterations: If TRUE, will keep all iterations (draws) of bootstrapped or Bayesian models. They will be added as additional columns named iter_1, iter_2, .... You can reshape them to a long format by running reshape_iterations().
bf_prior: Distribution representing a prior for the computation of Bayes factors / SI. Used if the input is a posterior, otherwise (in the case of models) ignored.
BF: The amount of support required to be included in the support interval.
verbose: Toggle off warnings.
diagnostic: Diagnostic metrics to compute. Character (vector) or list with one or more of these options: "ESS", "Rhat", "MCSE" or "all".
priors: Add the prior used for each parameter.
effects: Should results for fixed effects, random effects or both be returned? Only applies to mixed models. May be abbreviated.
component: Should results for all parameters, parameters for the conditional model or the zero-inflated part of the model be returned? May be abbreviated. Only applies to brms-models.
parameters: Regular expression pattern that describes the parameters that should be returned. Meta-parameters (like lp__ or prior_) are filtered by default, so only parameters that typically appear in the summary() are returned. Use parameters to select specific parameters for the output.

Details

One or more components of point estimates (like posterior mean or median), intervals and tests can be omitted from the summary output by setting the related argument to NULL. For example, test = NULL and centrality = NULL would only return the HDI (or CI).

References

Makowski, D., Ben-Shachar, M. S., Chen, S. H. A., and Lüdecke, D. (2019). Indices of Effect Existence and Significance in the Bayesian Framework. Frontiers in Psychology 2019;10:2767. doi:10.3389/fpsyg.2019.02767
Region of Practical Equivalence (ROPE)
Bayes factors

Examples

library(bayestestR)

if (require("logspline")) {
  x <- rnorm(1000)
  describe_posterior(x, verbose = FALSE)
  describe_posterior(x,
    centrality = "all",
    dispersion = TRUE,
    test = "all",
    verbose = FALSE
  )
  describe_posterior(x, ci = c(0.80, 0.90), verbose = FALSE)

  df <- data.frame(replicate(4, rnorm(100)))
  describe_posterior(df, verbose = FALSE)
  describe_posterior(
    df,
    centrality = "all",
    dispersion = TRUE,
    test = "all",
    verbose = FALSE
  )
  describe_posterior(df, ci = c(0.80, 0.90), verbose = FALSE)

  df <- data.frame(replicate(4, rnorm(20)))
  head(reshape_iterations(
    describe_posterior(df, keep_iterations = TRUE, verbose = FALSE)
  ))
}
#> Summary of Posterior Distribution
#> 
#> Parameter | Median |        95% CI |     pd |          ROPE | % in ROPE | iter_index | iter_group | iter_value
#> --------------------------------------------------------------------------------------------------------------
#> X1        |  -0.21 | [-1.70, 1.42] | 60.00% | [-0.10, 0.10] |     5.56% |       1.00 |       1.00 |       0.51
#> X2        |  -0.21 | [-2.38, 2.41] | 55.00% | [-0.10, 0.10] |    11.11% |       2.00 |       1.00 |      -0.36
#> X3        |   0.22 | [-1.96, 2.61] | 55.00% | [-0.10, 0.10] |     5.56% |       3.00 |       1.00 |       1.32
#> X4        |  -0.20 | [-1.58, 0.61] | 65.00% | [-0.10, 0.10] |    16.67% |       4.00 |       1.00 |       0.34
#> X1        |  -0.21 | [-1.70, 1.42] | 60.00% | [-0.10, 0.10] |     5.56% |       1.00 |       2.00 |      -0.14
#> X2        |  -0.21 | [-2.38, 2.41] | 55.00% | [-0.10, 0.10] |    11.11% |       2.00 |       2.00 |      -0.50
# \donttest{
# rstanarm models
# -----------------------------------------------
if (require("rstanarm") && require("emmeans")) {
  model <- suppressWarnings(
    stan_glm(mpg ~ wt + gear, data = mtcars, chains = 2, iter = 200, refresh = 0)
  )
  describe_posterior(model)
  describe_posterior(model, centrality = "all", dispersion = TRUE, test = "all")
  describe_posterior(model, ci = c(0.80, 0.90))

  # emmeans estimates
  # -----------------------------------------------
  describe_posterior(emtrends(model, ~1, "wt"))
}
#> Warning: Bayes factors might not be precise.
#>   For precise Bayes factors, sampling at least 40,000 posterior samples is
#>   recommended.
#> Summary of Posterior Distribution
#> 
#> Parameter | Median |         95% CI |   pd |          ROPE | % in ROPE
#> ----------------------------------------------------------------------
#> overall   |  -5.37 | [-6.57, -4.25] | 100% | [-0.10, 0.10] |        0%

# BayesFactor objects
# -----------------------------------------------
if (require("BayesFactor")) {
  bf <- ttestBF(x = rnorm(100, 1, 1))
  describe_posterior(bf)
  describe_posterior(bf, centrality = "all", dispersion = TRUE, test = "all")
  describe_posterior(bf, ci = c(0.80, 0.90))
}
#> Summary of Posterior Distribution
#> 
#> Parameter  | Median |       80% CI |       90% CI |   pd |          ROPE | % in ROPE |       BF |              Prior
#> --------------------------------------------------------------------------------------------------------------------
#> Difference |   0.97 | [0.84, 1.09] | [0.81, 1.12] | 100% | [-0.09, 0.09] |        0% | 1.27e+15 | Cauchy (0 +- 0.71)
# }