describe_posterior: Describe Posterior Distributions

Description Usage Arguments Details References Examples

View source: R/describe_posterior.R

Description

Compute indices relevant to describe and characterize the posterior distributions.

Usage

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
describe_posterior(
  posteriors,
  centrality = "median",
  dispersion = FALSE,
  ci = 0.95,
  ci_method = "hdi",
  test = c("p_direction", "rope"),
  rope_range = "default",
  rope_ci = 0.95,
  keep_iterations = FALSE,
  ...
)

## S3 method for class 'numeric'
describe_posterior(
  posteriors,
  centrality = "median",
  dispersion = FALSE,
  ci = 0.95,
  ci_method = "hdi",
  test = c("p_direction", "rope"),
  rope_range = "default",
  rope_ci = 0.95,
  keep_iterations = FALSE,
  bf_prior = NULL,
  BF = 1,
  ...
)

## S3 method for class 'stanreg'
describe_posterior(
  posteriors,
  centrality = "median",
  dispersion = FALSE,
  ci = 0.95,
  ci_method = "hdi",
  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,
  ...
)

## S3 method for class 'stanmvreg'
describe_posterior(
  posteriors,
  centrality = "median",
  dispersion = FALSE,
  ci = 0.95,
  ci_method = "hdi",
  test = "p_direction",
  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,
  ...
)

## S3 method for class 'brmsfit'
describe_posterior(
  posteriors,
  centrality = "median",
  dispersion = FALSE,
  ci = 0.95,
  ci_method = "hdi",
  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,
  ...
)

## S3 method for class 'MCMCglmm'
describe_posterior(
  posteriors,
  centrality = "median",
  dispersion = FALSE,
  ci = 0.95,
  ci_method = "hdi",
  test = c("p_direction", "rope"),
  rope_range = "default",
  rope_ci = 0.95,
  keep_iterations = FALSE,
  diagnostic = "ESS",
  parameters = NULL,
  ...
)

## S3 method for class 'BFBayesFactor'
describe_posterior(
  posteriors,
  centrality = "median",
  dispersion = FALSE,
  ci = 0.95,
  ci_method = "hdi",
  test = c("p_direction", "rope", "bf"),
  rope_range = "default",
  rope_ci = 0.95,
  keep_iterations = FALSE,
  priors = TRUE,
  verbose = TRUE,
  ...
)

Arguments

posteriors

A vector, data frame or model of posterior draws.

centrality

The point-estimates (centrality indices) to compute. Character (vector) or list with one or more of these options: "median", "mean", "MAP" or "all".

dispersion

Logical, if TRUE, computes indices of dispersion related to the estimate(s) (SD and MAD for mean and median, respectively).

ci

Value or vector of probability of the CI (between 0 and 1) to be estimated. Default to .95 (95%).

ci_method

The type of index used for Credible Interval. Can be "HDI" (default, see hdi()), "ETI" (see eti()), "BCI" (see bci()) 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().

...

Additional arguments to be passed to or from methods.

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.

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.

verbose

Toggle off warnings.

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

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
library(bayestestR)

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

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

  df <- data.frame(replicate(4, rnorm(20)))
  head(reshape_iterations(describe_posterior(df, keep_iterations = TRUE)))
}
## Not run: 
# rstanarm models
# -----------------------------------------------
if (require("rstanarm") && require("emmeans")) {
  model <- 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"))
}

# brms models
# -----------------------------------------------
if (require("brms")) {
  model <- brms::brm(mpg ~ wt + cyl, data = mtcars)
  describe_posterior(model)
  describe_posterior(model, centrality = "all", dispersion = TRUE, test = "all")
  describe_posterior(model, ci = c(0.80, 0.90))
}

# 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))
}

## End(Not run)

DominiqueMakowski/bayestestR documentation built on July 27, 2021, 4:12 p.m.