https://github.com/cran/bayestestR
Raw File
Tip revision: 9985109256c08d654edb46adb9cb20c913fb1888 authored by Dominique Makowski on 29 May 2019, 14:10 UTC
version 0.2.0
Tip revision: 9985109
describe_posterior.Rd
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/describe_posterior.R
\name{describe_posterior}
\alias{describe_posterior}
\alias{describe_posterior.numeric}
\alias{describe_posterior.stanreg}
\alias{describe_posterior.brmsfit}
\alias{describe_posterior.BFBayesFactor}
\title{Describe Posterior Distributions}
\usage{
describe_posterior(posteriors, centrality = "median",
  dispersion = TRUE, ci = 0.89, ci_method = "hdi", test = c("pd",
  "rope"), rope_range = "default", rope_ci = 0.89, ...)

\method{describe_posterior}{numeric}(posteriors, centrality = "median",
  dispersion = TRUE, ci = 0.89, ci_method = "hdi", test = c("pd",
  "rope"), rope_range = "default", rope_ci = 0.89, bf_prior = NULL,
  ...)

\method{describe_posterior}{stanreg}(posteriors, centrality = "median",
  dispersion = FALSE, ci = 0.89, ci_method = "hdi", test = c("pd",
  "rope"), rope_range = "default", rope_ci = 0.89, bf_prior = NULL,
  diagnostic = c("ESS", "Rhat"), priors = TRUE, effects = c("fixed",
  "random", "all"), parameters = NULL, ...)

\method{describe_posterior}{brmsfit}(posteriors, centrality = "median",
  dispersion = FALSE, ci = 0.89, ci_method = "hdi", test = c("pd",
  "rope"), rope_range = "default", rope_ci = 0.89, bf_prior = NULL,
  diagnostic = c("ESS", "Rhat"), effects = c("fixed", "random", "all"),
  component = c("conditional", "zi", "zero_inflated", "all"),
  parameters = NULL, ...)

\method{describe_posterior}{BFBayesFactor}(posteriors,
  centrality = "median", dispersion = FALSE, ci = 0.89,
  ci_method = "hdi", test = c("pd", "rope", "bf"),
  rope_range = "default", rope_ci = 0.89, priors = TRUE, ...)
}
\arguments{
\item{posteriors}{A vector, dataframe or model of posterior draws.}

\item{centrality}{The point-estimates (centrality indices) to compute. Can be a character or a list with "median", "mean", "MAP" or "all".}

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

\item{ci}{Value or vector of probability of the interval (between 0 and 1)
to be estimated. Named Credible Interval (CI) for consistency.}

\item{ci_method}{The type of index used for Credible Interval. Can be \link{hdi} (default) or "quantile" (see \link{ci}).}

\item{test}{The indices of effect existence to compute. Can be a character or a list with "p_direction", "rope", "p_map" or "bayesfactor".}

\item{rope_range}{ROPE's lower and higher bounds. Should be a list of two values (e.g., \code{c(-0.1, 0.1)}) or \code{"default"}. If \code{"default"}, the bounds are set to \code{x +- 0.1*SD(response)}.}

\item{rope_ci}{The Credible Interval (CI) probability, corresponding to the proportion of HDI, to use for the percentage in ROPE.}

\item{...}{Additional arguments to be passed to or from methods.}

\item{bf_prior}{Distribution representing a prior for the computation of Bayes factors. Used if the input is a posterior, otherwise (in the case of models) ignored.}

\item{diagnostic}{Diagnostic metrics to compute. Can be a character or a list with "ESS", "Rhat", "MCSE" or "all".}

\item{priors}{Add the prior used for each parameter.}

\item{effects}{Should results for fixed effects, random effects or both be returned?
Only applies to mixed models. May be abbreviated.}

\item{parameters}{Regular expression pattern that describes the parameters that
should be returned. Meta-parameters (like \code{lp__} or \code{prior_}) are
filtered by default, so only parameters that typically appear in the
\code{summary()} are returned. Use \code{parameters} to select specific parameters
for the output.}

\item{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 \pkg{brms}-models.}
}
\description{
Compute indices relevant to describe and characterise the posterior distributions.
}
\examples{
library(bayestestR)

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

# rstanarm models
# -----------------------------------------------
library(rstanarm)
model <- stan_glm(mpg ~ wt + gear, data = mtcars, chains = 2, iter = 200)
describe_posterior(model)
describe_posterior(model, centrality = "all", dispersion = TRUE, test = "all")
describe_posterior(model, ci = c(0.80, 0.90))
\dontrun{
# brms models
# -----------------------------------------------
library(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
# -----------------------------------------------
library(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))
}

}
\references{
\itemize{
  \item \href{https://easystats.github.io/bayestestR/articles/indicesEstimationComparison.html}{Vignette In-Depth 1: Comparison of Point-Estimates}
  \item \href{https://easystats.github.io/bayestestR/articles/region_of_practical_equivalence.html}{Region of Practical Equivalence (ROPE)}
  \item \href{https://easystats.github.io/bayestestR/articles/bayes_factors.html}{Bayes Factors}
}
}
back to top