bayestestR <img src='man/figures/logo.png' align="right" height="139" />

Become a Bayesian master you will

Existing R packages allow users to easily fit a large variety of models and extract and visualize the posterior draws. However, most of these packages only return a limited set of indices (e.g., point-estimates and CIs). bayestestR provides a comprehensive and consistent set of functions to analyze and describe posterior distributions generated by a variety of models objects, including popular modeling packages such as rstanarm, brms or BayesFactor.

You can reference the package and its documentation as follows:

• Makowski, D., Ben-Shachar, M. S., & Lüdecke, D. (2019). bayestestR: Describing Effects and their Uncertainty, Existence and Significance within the Bayesian Framework. Journal of Open Source Software, 4(40), 1541. 10.21105/joss.01541
• Makowski, D., Ben-Shachar, M. S., Chen, S. H. A., & Lüdecke, D. (2019). Indices of Effect Existence and Significance in the Bayesian Framework. Frontiers in Psychology 2019;10:2767. 10.3389/fpsyg.2019.02767

Installation

The bayestestR package is available on CRAN, while its latest development version is available on R-universe (from rOpenSci).

| Type | Source | Command | |-------------|------------|------------------------------------------------------------------------------| | Release | CRAN | install.packages("bayestestR") | | Development | R-universe | install.packages("bayestestR", repos = "https://easystats.r-universe.dev") |

Once you have downloaded the package, you can then load it using:

library("bayestestR")

Tip

Instead of library(bayestestR), use library(easystats). This will make all features of the easystats-ecosystem available.

To stay updated, use easystats::install_latest().

Documentation

Access the package documentation and check-out these vignettes:

Tutorials

• Get Started with Bayesian Analysis
• Example 1: Initiation to Bayesian models
• Example 2: Confirmation of Bayesian skills
• Example 3: Become a Bayesian master

Articles

• Credible Intervals (CI)
• Probability of Direction (pd)
• Region of Practical Equivalence (ROPE)
• Bayes Factors (BF)
• Comparison of Point-Estimates
• Comparison of Indices of Effect Existence
• Reporting Guidelines

Features

In the Bayesian framework, parameters are estimated in a probabilistic fashion as distributions. These distributions can be summarised and described by reporting four types of indices:

• Centrality
  • mean(), median() or map_estimate() for an estimation of the mode.
  • point_estimate() can be used to get them at once and can be run directly on models.
• Uncertainty
  • hdi() for Highest Density Intervals (HDI), spi() for Shortest Probability Intervals (SPI) or eti() for Equal-Tailed Intervals (ETI).
  • ci() can be used as a general method for Confidence and Credible Intervals (CI).
• Effect Existence: whether an effect is different from 0.
  • p_direction() for a Bayesian equivalent of the frequentist p-value (see Makowski et al., 2019)
  • p_pointnull() represents the odds of null hypothesis (h0 = 0) compared to the most likely hypothesis (the MAP).
  • bf_pointnull() for a classic Bayes Factor (BF) assessing the likelihood of effect presence against its absence (h0 = 0).
• Effect Significance: whether the effect size can be considered as non-negligible.
  • p_rope() is the probability of the effect falling inside a Region of Practical Equivalence (ROPE).
  • bf_rope() computes a Bayes factor against the null as defined by a region (the ROPE).
  • p_significance() that combines a region of equivalence with the probability of direction.

describe_posterior() is the master function with which you can compute all of the indices cited below at once.

describe_posterior(
  rnorm(10000),
  centrality = "median",
  test = c("p_direction", "p_significance"),
  verbose = FALSE
)
## Summary of Posterior Distribution
## 
## Parameter |   Median |        95% CI |     pd |   ps
## ----------------------------------------------------
## Posterior | 7.75e-03 | [-1.95, 1.98] | 50.36% | 0.46

describe_posterior() works for many objects, including more complex brmsfit-models. For better readability, the output is separated by model components:

zinb <- read.csv("http://stats.idre.ucla.edu/stat/data/fish.csv")
set.seed(123)
model <- brm(
  bf(
    count ~ child + camper + (1 | persons),
    zi ~ child + camper + (1 | persons)
  ),
  data = zinb,
  family = zero_inflated_poisson(),
  chains = 1,
  iter = 500
)

describe_posterior(
  model,
  effects = "all",
  component = "all",
  test = c("p_direction", "p_significance"),
  centrality = "all"
)

## Summary of Posterior Distribution
## 
## Parameter   | Median |  Mean |   MAP |         95% CI |     pd |   ps |  Rhat | ESS
## -----------------------------------------------------------------------------------
## (Intercept) |   0.96 |  0.96 |  0.96 | [-0.81,  2.51] | 90.00% | 0.88 | 1.011 | 110
## child       |  -1.16 | -1.16 | -1.16 | [-1.36, -0.94] |   100% | 1.00 | 0.996 | 278
## camper      |   0.73 |  0.72 |  0.73 | [ 0.54,  0.91] |   100% | 1.00 | 0.996 | 271
## 
## # Fixed effects (zero-inflated)
## 
## Parameter   | Median |  Mean |   MAP |         95% CI |     pd |   ps |  Rhat | ESS
## -----------------------------------------------------------------------------------
## (Intercept) |  -0.48 | -0.51 | -0.22 | [-2.03,  0.89] | 78.00% | 0.73 | 0.997 | 138
## child       |   1.85 |  1.86 |  1.81 | [ 1.19,  2.54] |   100% | 1.00 | 0.996 | 303
## camper      |  -0.88 | -0.86 | -0.99 | [-1.61, -0.07] | 98.40% | 0.96 | 0.996 | 292
## 
## # Random effects (conditional) (SD/Cor: persons)
## 
## Parameter   | Median | Mean |  MAP |         95% CI |   pd |   ps |  Rhat | ESS
## -------------------------------------------------------------------------------
## (Intercept) |   1.42 | 1.58 | 1.07 | [ 0.71,  3.58] | 100% | 1.00 | 1.010 | 126
## 
## # Random effects (zero-inflated) (SD/Cor: persons)
## 
## Parameter   | Median | Mean |  MAP |         95% CI |   pd |   ps |  Rhat | ESS
## ------------------------------------------------------