Kruschke, J. K. (2015). *Doing Bayesian data analysis: A tutorial with
R, JAGS, and Stan* (2. ed). Amsterdam: Elsevier, Academic Press.
Kruschke, J. K. (2018). Rejecting or accepting parameter values in
Bayesian estimation. *Advances in Methods and Practices in Psychological
Science*, *1*(2), 270–280.
Kruschke, J. K., & Liddell, T. M. (2018). The Bayesian new statistics:
Hypothesis testing, estimation, meta-analysis, and power analysis from a
Bayesian perspective. *Psychonomic Bulletin & Review*, *25*(1), 178–206.
McElreath, R. (2018). *Statistical rethinking*.
Wagenmakers, E.-J., Lodewyckx, T., Kuriyal, H., & Grasman, R. (2010).
Bayesian hypothesis testing for psychologists: A tutorial on the
SavageDickey method. *Cognitive Psychology*, *60*(3), 158–189.
bayestestR/man/ 0000755 0001762 0000144 00000000000 13616666250 013165 5 ustar ligges users bayestestR/man/overlap.Rd 0000644 0001762 0000144 00000002365 13571067532 015130 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/overlap.R
\name{overlap}
\alias{overlap}
\title{Overlap Coefficient}
\usage{
overlap(
x,
y,
method_density = "kernel",
method_auc = "trapezoid",
precision = 2^10,
extend = TRUE,
extend_scale = 0.1,
...
)
}
\arguments{
\item{x}{Vector of x values.}
\item{y}{Vector of x values.}
\item{method_density}{Density estimation method. See \code{\link{estimate_density}}.}
\item{method_auc}{Area Under the Curve (AUC) estimation method. See \code{\link{area_under_curve}}.}
\item{precision}{Number of points of density data. See the \code{n} parameter in \link[=density]{density}.}
\item{extend}{Extend the range of the x axis by a factor of \code{extend_scale}.}
\item{extend_scale}{Ratio of range by which to extend the x axis. A value of \code{0.1} means that the x axis will be extended by \code{1/10} of the range of the data.}
\item{...}{Currently not used.}
}
\description{
A method to calculate the overlap coefficient between two empirical distributions (that can be used as a measure of similarity between two samples).
}
\examples{
library(bayestestR)
x <- distribution_normal(1000, 2, 0.5)
y <- distribution_normal(1000, 0, 1)
overlap(x, y)
plot(overlap(x, y))
}
bayestestR/man/dot-prior_new_location.Rd 0000644 0001762 0000144 00000000501 13620150257 020116 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sensitivity_to_prior.R
\name{.prior_new_location}
\alias{.prior_new_location}
\title{Set a new location for a prior}
\usage{
.prior_new_location(prior, sign, magnitude = 10)
}
\description{
Set a new location for a prior
}
\keyword{internal}
bayestestR/man/p_significance.Rd 0000644 0001762 0000144 00000007226 13616544116 016420 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/p_significance.R
\name{p_significance}
\alias{p_significance}
\alias{p_significance.numeric}
\alias{p_significance.emmGrid}
\alias{p_significance.stanreg}
\alias{p_significance.brmsfit}
\title{Practical Significance (ps)}
\usage{
p_significance(x, ...)
\method{p_significance}{numeric}(x, threshold = "default", ...)
\method{p_significance}{emmGrid}(x, threshold = "default", ...)
\method{p_significance}{stanreg}(
x,
threshold = "default",
effects = c("fixed", "random", "all"),
parameters = NULL,
verbose = TRUE,
...
)
\method{p_significance}{brmsfit}(
x,
threshold = "default",
effects = c("fixed", "random", "all"),
component = c("conditional", "zi", "zero_inflated", "all"),
parameters = NULL,
verbose = TRUE,
...
)
}
\arguments{
\item{x}{Vector representing a posterior distribution. Can also be a \code{stanreg} or \code{brmsfit} model.}
\item{...}{Currently not used.}
\item{threshold}{The threshold value that separates significant from negligible effect. If \code{"default"}, the range is set to \code{0.1} if input is a vector, and based on \code{\link[=rope_range]{rope_range()}} if a Bayesian model is provided.}
\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{verbose}{Toggle off warnings.}
\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.}
}
\value{
Values between 0 and 1 corresponding to the probability of practical significance (ps).
}
\description{
Compute the probability of \strong{Practical Significance} (\strong{\emph{ps}}), which can be conceptualized as a unidirectional equivalence test. It returns the probability that effect is above a given threshold corresponding to a negligible effect in the median's direction. Mathematically, it is defined as the proportion of the posterior distribution of the median sign above the threshold.
}
\details{
\code{p_significance()} returns the proportion of a probability
distribution (\code{x}) that is outside a certain range (the negligible
effect, or ROPE, see argument \code{threshold}). If there are values of the
distribution both below and above the ROPE, \code{p_significance()} returns
the higher probability of a value being outside the ROPE. Typically, this
value should be larger than 0.5 to indicate practical significance. However,
if the range of the negligible effect is rather large compared to the
range of the probability distribution \code{x}, \code{p_significance()}
will be less than 0.5, which indicates no clear practical significance.
}
\examples{
library(bayestestR)
# Simulate a posterior distribution of mean 1 and SD 1
# ----------------------------------------------------
posterior <- rnorm(1000, mean = 1, sd = 1)
p_significance(posterior)
# Simulate a dataframe of posterior distributions
# -----------------------------------------------
df <- data.frame(replicate(4, rnorm(100)))
p_significance(df)
\dontrun{
# rstanarm models
# -----------------------------------------------
if (require("rstanarm")) {
model <- rstanarm::stan_glm(mpg ~ wt + cyl,
data = mtcars,
chains = 2, refresh = 0
)
p_significance(model)
}
}
}
bayestestR/man/bayesfactor_parameters.Rd 0000644 0001762 0000144 00000023602 13616544116 020200 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/bayesfactor_parameters.R
\name{bayesfactor_parameters}
\alias{bayesfactor_parameters}
\alias{bayesfactor_pointull}
\alias{bayesfactor_rope}
\alias{bf_parameters}
\alias{bf_pointull}
\alias{bf_rope}
\alias{bayesfactor_parameters.numeric}
\alias{bayesfactor_parameters.stanreg}
\alias{bayesfactor_parameters.brmsfit}
\alias{bayesfactor_parameters.emmGrid}
\alias{bayesfactor_parameters.data.frame}
\title{Bayes Factors (BF) for a Single Parameter}
\usage{
bayesfactor_parameters(
posterior,
prior = NULL,
direction = "two-sided",
null = 0,
verbose = TRUE,
...
)
bayesfactor_pointull(
posterior,
prior = NULL,
direction = "two-sided",
null = 0,
verbose = TRUE,
...
)
bayesfactor_rope(
posterior,
prior = NULL,
direction = "two-sided",
null = rope_range(posterior),
verbose = TRUE,
...
)
bf_parameters(
posterior,
prior = NULL,
direction = "two-sided",
null = 0,
verbose = TRUE,
...
)
bf_pointull(
posterior,
prior = NULL,
direction = "two-sided",
null = 0,
verbose = TRUE,
...
)
bf_rope(
posterior,
prior = NULL,
direction = "two-sided",
null = rope_range(posterior),
verbose = TRUE,
...
)
\method{bayesfactor_parameters}{numeric}(
posterior,
prior = NULL,
direction = "two-sided",
null = 0,
verbose = TRUE,
...
)
\method{bayesfactor_parameters}{stanreg}(
posterior,
prior = NULL,
direction = "two-sided",
null = 0,
verbose = TRUE,
effects = c("fixed", "random", "all"),
component = c("conditional", "zi", "zero_inflated", "all"),
parameters = NULL,
...
)
\method{bayesfactor_parameters}{brmsfit}(
posterior,
prior = NULL,
direction = "two-sided",
null = 0,
verbose = TRUE,
effects = c("fixed", "random", "all"),
component = c("conditional", "zi", "zero_inflated", "all"),
parameters = NULL,
...
)
\method{bayesfactor_parameters}{emmGrid}(
posterior,
prior = NULL,
direction = "two-sided",
null = 0,
verbose = TRUE,
...
)
\method{bayesfactor_parameters}{data.frame}(
posterior,
prior = NULL,
direction = "two-sided",
null = 0,
verbose = TRUE,
...
)
}
\arguments{
\item{posterior}{A numerical vector, \code{stanreg} / \code{brmsfit} object, \code{emmGrid}
or a data frame - representing a posterior distribution(s) from (see 'Details').}
\item{prior}{An object representing a prior distribution (see 'Details').}
\item{direction}{Test type (see 'Details'). One of \code{0}, \code{"two-sided"} (default, two tailed),
\code{-1}, \code{"left"} (left tailed) or \code{1}, \code{"right"} (right tailed).}
\item{null}{Value of the null, either a scaler (for point-null) or a a range
(for a interval-null).}
\item{verbose}{Toggle off warnings.}
\item{...}{Currently not used.}
\item{effects}{Should results for fixed effects, random effects or both be returned?
Only applies to mixed models. May be abbreviated.}
\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.}
\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.}
}
\value{
A data frame containing the Bayes factor representing evidence \emph{against} the null.
}
\description{
This method computes Bayes factors against the null (either a point or an interval),
based on prior and posterior samples of a single parameter. This Bayes factor indicates
the degree by which the mass of the posterior distribution has shifted further away
from or closer to the null value(s) (relative to the prior distribution), thus indicating
if the null value has become less or more likely given the observed data.
\cr \cr
When the null is an interval, the Bayes factor is computed by comparing the prior
and posterior odds of the parameter falling within or outside the null interval
(Morey & Rouder, 2011; Liao et al., 2020); When the null is a point, a Savage-Dickey
density ratio is computed, which is also an approximation of a Bayes factor comparing
the marginal likelihoods of the model against a model in which the tested parameter
has been restricted to the point null (Wagenmakers et al., 2010; Heck, 2019).
\cr \cr
Note that the \code{logspline} package is used for estimating densities and probabilies,
and must be installed for the function to work.
\cr \cr
\code{bayesfactor_pointnull()} and \code{bayesfactor_rope()} are wrappers around
\code{bayesfactor_parameters} with different defaults for the null to be tested against
(a point and a range, respectively). Aliases of the main functions are prefixed
with \code{bf_*}, like \code{bf_parameters()} or \code{bf_pointnull()}
\cr \cr
\strong{For more info, in particular on specifying correct priors for factors with more than 2 levels, see \href{https://easystats.github.io/bayestestR/articles/bayes_factors.html}{the Bayes factors vignette}.}
}
\details{
This method is used to compute Bayes factors based on prior and posterior distributions.
\cr\cr
For the computation of Bayes factors, the model priors must be proper priors (at the very least
they should be \emph{not flat}, and it is preferable that they be \emph{informative}); As the priors for
the alternative get wider, the likelihood of the null value(s) increases, to the extreme that for completely
flat priors the null is infinitely more favorable than the alternative (this is called \emph{the Jeffreys-Lindley-Bartlett
paradox}). Thus, you should only ever try (or want) to compute a Bayes factor when you have an informed prior.
\cr\cr
(Note that by default, \code{brms::brm()} uses flat priors for fixed-effects; See example below.)
\subsection{Setting the correct \code{prior}}{
It is important to provide the correct \code{prior} for meaningful results.
\itemize{
\item When \code{posterior} is a numerical vector, \code{prior} should also be a numerical vector.
\item When \code{posterior} is a \code{data.frame}, \code{prior} should also be a \code{data.frame}, with matching column order.
\item When \code{posterior} is a \code{stanreg} or \code{brmsfit} model: \itemize{
\item \code{prior} can be set to \code{NULL}, in which case prior samples are drawn internally.
\item \code{prior} can also be a model equvilant to \code{posterior} but with samples from the priors \emph{only}.
}
\item When \code{posterior} is an \code{emmGrid} object: \itemize{
\item \code{prior} should be the \code{stanreg} or \code{brmsfit} model used to create the \code{emmGrid} objects.
\item \code{prior} can also be an \code{emmGrid} object equvilant to \code{posterior} but created with a model of priors samples \emph{only}.
}
}}
\subsection{One-sided Tests (setting an order restriction)}{
One sided tests (controlled by \code{direction}) are conducted by restricting the prior and
posterior of the non-null values (the "alternative") to one side of the null only
(\cite{Morey & Wagenmakers, 2014}). For example, if we have a prior hypothesis that the
parameter should be positive, the alternative will be restricted to the region to the right
of the null (point or interval).
}
\subsection{Interpreting Bayes Factors}{
A Bayes factor greater than 1 can be interpereted as evidence against the null,
at which one convention is that a Bayes factor greater than 3 can be considered
as "substantial" evidence against the null (and vice versa, a Bayes factor
smaller than 1/3 indicates substantial evidence in favor of the null-model)
(\cite{Wetzels et al. 2011}).
}
}
\examples{
library(bayestestR)
prior <- distribution_normal(1000, mean = 0, sd = 1)
posterior <- distribution_normal(1000, mean = .5, sd = .3)
bayesfactor_parameters(posterior, prior)
\dontrun{
# rstanarm models
# ---------------
if (require("rstanarm") &6 require("emmeans")) {
contrasts(sleep$group) <- contr.bayes # see vingette
stan_model <- stan_lmer(extra ~ group + (1 | ID), data = sleep)
bayesfactor_parameters(stan_model)
bayesfactor_parameters(stan_model, null = rope_range(stan_model))
# emmGrid objects
# ---------------
group_diff <- pairs(emmeans(stan_model, ~group))
bayesfactor_parameters(group_diff, prior = stan_model)
}
# brms models
# -----------
if (require("brms")) {
contrasts(sleep$group) <- contr.bayes # see vingette
my_custom_priors <-
set_prior("student_t(3, 0, 1)", class = "b") +
set_prior("student_t(3, 0, 1)", class = "sd", group = "ID")
brms_model <- brm(extra ~ group + (1 | ID),
data = sleep,
prior = my_custom_priors
)
bayesfactor_parameters(brms_model)
}
}
}
\references{
\itemize{
\item Wagenmakers, E. J., Lodewyckx, T., Kuriyal, H., and Grasman, R. (2010). Bayesian hypothesis testing for psychologists: A tutorial on the Savage-Dickey method. Cognitive psychology, 60(3), 158-189.
\item Heck, D. W. (2019). A caveat on the Savage–Dickey density ratio: The case of computing Bayes factors for regression parameters. British Journal of Mathematical and Statistical Psychology, 72(2), 316-333.
\item Morey, R. D., & Wagenmakers, E. J. (2014). Simple relation between Bayesian order-restricted and point-null hypothesis tests. Statistics & Probability Letters, 92, 121-124.
\item Morey, R. D., & Rouder, J. N. (2011). Bayes factor approaches for testing interval null hypotheses. Psychological methods, 16(4), 406.
\item Liao, J. G., Midya, V., & Berg, A. (2020). Connecting and contrasting the Bayes factor and a modified ROPE procedure for testing interval null hypotheses. The American Statistician, 1-19.
\item Wetzels, R., Matzke, D., Lee, M. D., Rouder, J. N., Iverson, G. J., and Wagenmakers, E.-J. (2011). Statistical Evidence in Experimental Psychology: An Empirical Comparison Using 855 t Tests. Perspectives on Psychological Science, 6(3), 291–298. \doi{10.1177/1745691611406923}
}
}
\author{
Mattan S. Ben-Shachar
}
bayestestR/man/dot-select_nums.Rd 0000644 0001762 0000144 00000000365 13620150257 016553 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/utils.R
\name{.select_nums}
\alias{.select_nums}
\title{select numerics columns}
\usage{
.select_nums(x)
}
\description{
select numerics columns
}
\keyword{internal}
bayestestR/man/bayesfactor.Rd 0000644 0001762 0000144 00000005543 13616544116 015761 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/bayesfactor.R
\name{bayesfactor}
\alias{bayesfactor}
\title{Bayes Factors (BF)}
\usage{
bayesfactor(
...,
prior = NULL,
direction = "two-sided",
null = 0,
hypothesis = NULL,
effects = c("fixed", "random", "all"),
verbose = TRUE,
denominator = 1,
match_models = FALSE,
prior_odds = NULL
)
}
\arguments{
\item{...}{A numeric vector, model object(s), or the output from \code{bayesfactor_models}.}
\item{prior}{An object representing a prior distribution (see 'Details').}
\item{direction}{Test type (see 'Details'). One of \code{0}, \code{"two-sided"} (default, two tailed),
\code{-1}, \code{"left"} (left tailed) or \code{1}, \code{"right"} (right tailed).}
\item{null}{Value of the null, either a scaler (for point-null) or a a range
(for a interval-null).}
\item{hypothesis}{A character vector specifying the restrictions as logical conditions (see examples below).}
\item{effects}{Should results for fixed effects, random effects or both be returned?
Only applies to mixed models. May be abbreviated.}
\item{verbose}{Toggle off warnings.}
\item{denominator}{Either an integer indicating which of the models to use as the denominator,
or a model to be used as a denominator. Ignored for \code{BFBayesFactor}.}
\item{match_models}{See details.}
\item{prior_odds}{Optional vector of prior odds for the models. See \code{BayesFactor::priorOdds<-}.}
}
\value{
Some type of Bayes factor, depending on the input. See \code{\link{bayesfactor_parameters}}, \code{\link{bayesfactor_models}} or \code{\link{bayesfactor_inclusion}}
}
\description{
This function compte the Bayes factors (BFs) that are appropriate to the input.
For vectors or single models, it will compute \code{\link[=bayesfactor_parameters]{BFs for single parameters}},
or is \code{hypothesis} is specified, \code{\link[=bayesfactor_restricted]{BFs for restricted models}}.
For multiple models, it will return the BF corresponding to \code{\link[=bayesfactor_models]{comparison between models}}
and if a model comparison is passed, it will compute the \code{\link[=bayesfactor_inclusion]{inclusion BF}}.
\cr\cr
For a complete overview of these functions, read the \href{https://easystats.github.io/bayestestR/articles/bayes_factors.html}{Bayes factor vignette}.
}
\examples{
library(bayestestR)
# Vectors
prior <- distribution_normal(1000, mean = 0, sd = 1)
posterior <- distribution_normal(1000, mean = .5, sd = .3)
bayesfactor(posterior, prior = prior)
\dontrun{
# rstanarm models
# ---------------
if (require("rstanarm")) {
model <- stan_lmer(extra ~ group + (1 | ID), data = sleep)
bayesfactor(model)
}
}
# Frequentist models
# ---------------
m0 <- lm(extra ~ 1, data = sleep)
m1 <- lm(extra ~ group, data = sleep)
m2 <- lm(extra ~ group + ID, data = sleep)
comparison <- bayesfactor(m0, m1, m2)
comparison
bayesfactor(comparison)
}
bayestestR/man/mhdior.Rd 0000644 0001762 0000144 00000010562 13616544116 014736 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mhdior.R
\name{mhdior}
\alias{mhdior}
\alias{mhdior.numeric}
\alias{mhdior.data.frame}
\alias{mhdior.emmGrid}
\alias{mhdior.BFBayesFactor}
\alias{mhdior.stanreg}
\alias{mhdior.brmsfit}
\title{Maximum HDI level inside/outside ROPE (MHDIOR)}
\usage{
mhdior(x, ...)
\method{mhdior}{numeric}(x, range = "default", precision = 0.1, ...)
\method{mhdior}{data.frame}(x, range = "default", precision = 0.1, ...)
\method{mhdior}{emmGrid}(x, range = "default", precision = 0.1, ...)
\method{mhdior}{BFBayesFactor}(x, range = "default", precision = 0.1, ...)
\method{mhdior}{stanreg}(
x,
range = "default",
precision = 0.1,
effects = c("fixed", "random", "all"),
parameters = NULL,
...
)
\method{mhdior}{brmsfit}(
x,
range = "default",
precision = 0.1,
effects = c("fixed", "random", "all"),
component = c("conditional", "zi", "zero_inflated", "all"),
parameters = NULL,
...
)
}
\arguments{
\item{x}{Vector representing a posterior distribution. Can also be a \code{stanreg} or \code{brmsfit} model.}
\item{...}{Currently not used.}
\item{range}{ROPE's lower and higher bounds. Should be a vector of length two (e.g., \code{c(-0.1, 0.1)}) or \code{"default"}. If \code{"default"}, the range is set to \code{c(-0.1, 0.1)} if input is a vector, and based on \code{\link[=rope_range]{rope_range()}} if a Bayesian model is provided.}
\item{precision}{The precision by which to explore the ROPE space (in percentage). Lower values increase the precision of the returned p value but can be quite computationaly costly.}
\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{
The MHDIOR (pronounced 'em-eich-dior') is an exploratory and non-validated index representing the maximum percentage of \link[=hdi]{HDI} that does not contain (or is entirely contained, in which case the value is prefixed with a negative sign), in the negligible values space defined by the \link[=rope]{ROPE}. It differs from the ROPE percentage, \emph{i.e.}, from the proportion of a given CI in the ROPE, as it represents the maximum CI values needed to reach a ROPE proportion of 0\% or 100\%. Whether the index reflects the ROPE reaching 0\% or 100\% is indicated through the sign: a negative sign is added to indicate that the probability corresponds to the probability of a not significant effect (a percentage in ROPE of 100\%). For instance, a MHDIOR of 97\% means that there is a probability of .97 that a parameter (described by its posterior distribution) is outside the ROPE. In other words, the 97\% HDI is the maximum HDI level for which the percentage in ROPE is 0\%. On the contrary, a ROPE-based p of -97\% indicates that there is a probability of .97 that the parameter is inside the ROPE (percentage in ROPE of 100\%). A value close to 0\% would indicate that the mode of the distribution falls perfectly at the edge of the ROPE, in which case the percentage of HDI needed to be on either side of the ROPE becomes infinitely small. Negative values do not refer to negative values \emph{per se}, simply indicating that the value corresponds to non-significance rather than significance.
}
\examples{
\dontrun{
library(bayestestR)
# precision = 1 is used to speed up examples...
mhdior(
x = rnorm(1000, mean = 1, sd = 1),
range = c(-0.1, 0.1),
precision = 1
)
df <- data.frame(replicate(4, rnorm(100)))
mhdior(df, precision = 1)
if (require("rstanarm")) {
model <- stan_glm(
mpg ~ wt + gear, data = mtcars,
chains = 2,
iter = 200,
refresh = 0
)
mhdior(model, precision = 1)
}
if (require("emmeans")) {
mhdior(emtrends(model, ~1, "wt"))
}
if (require("brms")) {
model <- brms::brm(mpg ~ wt + cyl, data = mtcars)
mhdior(model)
}
if (require("BayesFactor")) {
bf <- ttestBF(x = rnorm(100, 1, 1))
mhdior(bf)
}
}
}
bayestestR/man/ci.Rd 0000644 0001762 0000144 00000011175 13616544116 014050 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ci.R
\name{ci}
\alias{ci}
\alias{ci.numeric}
\alias{ci.data.frame}
\alias{ci.emmGrid}
\alias{ci.sim.merMod}
\alias{ci.sim}
\alias{ci.stanreg}
\alias{ci.brmsfit}
\alias{ci.BFBayesFactor}
\alias{ci.MCMCglmm}
\title{Confidence/Credible/Compatibility Interval (CI)}
\usage{
ci(x, ...)
\method{ci}{numeric}(x, ci = 0.89, method = "ETI", verbose = TRUE, BF = 1, ...)
\method{ci}{data.frame}(x, ci = 0.89, method = "ETI", verbose = TRUE, BF = 1, ...)
\method{ci}{emmGrid}(x, ci = 0.89, method = "ETI", verbose = TRUE, BF = 1, ...)
\method{ci}{sim.merMod}(
x,
ci = 0.89,
method = "ETI",
effects = c("fixed", "random", "all"),
parameters = NULL,
verbose = TRUE,
...
)
\method{ci}{sim}(x, ci = 0.89, method = "ETI", parameters = NULL, verbose = TRUE, ...)
\method{ci}{stanreg}(
x,
ci = 0.89,
method = "ETI",
effects = c("fixed", "random", "all"),
parameters = NULL,
verbose = TRUE,
BF = 1,
...
)
\method{ci}{brmsfit}(
x,
ci = 0.89,
method = "ETI",
effects = c("fixed", "random", "all"),
component = c("conditional", "zi", "zero_inflated", "all"),
parameters = NULL,
verbose = TRUE,
BF = 1,
...
)
\method{ci}{BFBayesFactor}(x, ci = 0.89, method = "ETI", verbose = TRUE, BF = 1, ...)
\method{ci}{MCMCglmm}(x, ci = 0.89, method = "ETI", verbose = TRUE, ...)
}
\arguments{
\item{x}{A \code{stanreg} or \code{brmsfit} model, or a vector representing a posterior distribution.}
\item{...}{Currently not used.}
\item{ci}{Value or vector of probability of the CI (between 0 and 1)
to be estimated. Default to \code{.89} (89\%) for Bayesian models and \code{.95} (95\%) for frequentist models.}
\item{method}{Can be \link[=eti]{'ETI'} (default), \link[=hdi]{'HDI'} or \link[=si]{'SI'}.}
\item{verbose}{Toggle off warnings.}
\item{BF}{The amount of support required to be included in the support interval.}
\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.}
}
\value{
A data frame with following columns:
\itemize{
\item \code{Parameter} The model parameter(s), if \code{x} is a model-object. If \code{x} is a vector, this column is missing.
\item \code{CI} The probability of the credible interval.
\item \code{CI_low}, \code{CI_high} The lower and upper credible interval limits for the parameters.
}
}
\description{
Compute Confidence/Credible/Compatibility Intervals (CI) or Support Intervals (SI) for Bayesian and frequentist models. The Documentation is accessible for:
}
\details{
\itemize{
\item \href{https://easystats.github.io/bayestestR/articles/credible_interval.html}{Bayesian models}
\item \href{https://easystats.github.io/parameters/reference/ci.merMod.html}{Frequentist models}
}
}
\note{
When it comes to interpretation, we recommend thinking of the CI in terms of
an "uncertainty" or "compatibility" interval, the latter being defined as
\dQuote{Given any value in the interval and the background assumptions,
the data should not seem very surprising} (\cite{Gelman & Greenland 2019}).
}
\examples{
library(bayestestR)
posterior <- rnorm(1000)
ci(posterior, method = "ETI")
ci(posterior, method = "HDI")
df <- data.frame(replicate(4, rnorm(100)))
ci(df, method = "ETI", ci = c(.80, .89, .95))
ci(df, method = "HDI", ci = c(.80, .89, .95))
\dontrun{
if (require("rstanarm")) {
model <- stan_glm(mpg ~ wt, data = mtcars, chains = 2, iter = 200, refresh = 0)
ci(model, method = "ETI", ci = c(.80, .89))
ci(model, method = "HDI", ci = c(.80, .89))
ci(model, method = "SI")
}
if (require("brms")) {
model <- brms::brm(mpg ~ wt + cyl, data = mtcars)
ci(model, method = "ETI")
ci(model, method = "HDI")
ci(model, method = "SI")
}
if (require("BayesFactor")) {
bf <- ttestBF(x = rnorm(100, 1, 1))
ci(bf, method = "ETI")
ci(bf, method = "HDI")
}
if (require("emmeans")) {
model <- emtrends(model, ~1, "wt")
ci(model, method = "ETI")
ci(model, method = "HDI")
ci(model, method = "SI")
}
}
}
\references{
Gelman A, Greenland S. Are confidence intervals better termed "uncertainty intervals"? BMJ 2019;l5381. \doi{10.1136/bmj.l5381}
}
bayestestR/man/pd_to_p.Rd 0000644 0001762 0000144 00000001640 13571067531 015076 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/convert_pd_to_p.R
\name{pd_to_p}
\alias{pd_to_p}
\alias{p_to_pd}
\alias{convert_p_to_pd}
\alias{convert_pd_to_p}
\title{Convert between Probability of Direction (pd) and p-value.}
\usage{
pd_to_p(pd, direction = "two-sided", ...)
p_to_pd(p, direction = "two-sided", ...)
convert_p_to_pd(p, direction = "two-sided", ...)
convert_pd_to_p(pd, direction = "two-sided", ...)
}
\arguments{
\item{pd}{A Probability of Direction (pd) value (between 0 and 1).}
\item{direction}{What type of p-value is requested or provided. Can be \code{"two-sided"} (default, two tailed) or \code{"one-sided"} (one tailed).}
\item{...}{Arguments passed to or from other methods.}
\item{p}{A p-value.}
}
\description{
Enables a conversion between sProbability of Direction (pd) and p-value.
}
\examples{
pd_to_p(pd = 0.95)
pd_to_p(pd = 0.95, direction = "one-sided")
}
bayestestR/man/update.bayesfactor_models.Rd 0000644 0001762 0000144 00000002043 13616544116 020575 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/update.bayesfactor_models.R
\name{update.bayesfactor_models}
\alias{update.bayesfactor_models}
\title{Update bayesfactor_models}
\usage{
\method{update}{bayesfactor_models}(object, subset = NULL, reference = NULL, ...)
}
\arguments{
\item{object}{A \code{\link{bayesfactor_models}} object.}
\item{subset}{Vector of model indices to keep or remove.}
\item{reference}{Index of model to rereference to, or \code{"top"} to reference to the best model, or \code{"bottom"} to reference to the worst model.}
\item{...}{Currently not used.}
}
\description{
Update bayesfactor_models
}
\examples{
\dontrun{
library(lme4)
lmer1 <- lmer(Sepal.Length ~ Petal.Length + (1 | Species), data = iris)
lmer2 <- lmer(Sepal.Length ~ Petal.Length + (Petal.Length | Species), data = iris)
lmer3 <- lmer(
Sepal.Length ~ Petal.Length + (Petal.Length | Species) + (1 | Petal.Width),
data = iris
)
m <- bayesfactor_models(lmer1, lmer2, lmer3, denominator = 1)
m
update(m, reference = "bottom")
}
}
bayestestR/man/point_estimate.Rd 0000644 0001762 0000144 00000007045 13603652205 016475 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/point_estimate.R
\name{point_estimate}
\alias{point_estimate}
\alias{point_estimate.stanreg}
\alias{point_estimate.brmsfit}
\alias{point_estimate.BFBayesFactor}
\title{Point-estimates of posterior distributions}
\usage{
point_estimate(x, centrality = "all", dispersion = FALSE, ...)
\method{point_estimate}{stanreg}(
x,
centrality = "all",
dispersion = FALSE,
effects = c("fixed", "random", "all"),
parameters = NULL,
...
)
\method{point_estimate}{brmsfit}(
x,
centrality = "all",
dispersion = FALSE,
effects = c("fixed", "random", "all"),
component = c("conditional", "zi", "zero_inflated", "all"),
parameters = NULL,
...
)
\method{point_estimate}{BFBayesFactor}(x, centrality = "all", dispersion = FALSE, ...)
}
\arguments{
\item{x}{Vector representing a posterior distribution. Can also be a
\code{stanreg}, \code{brmsfit} or a \code{BayesFactor} model.}
\item{centrality}{The point-estimates (centrality indices) to compute. Character (vector) or list with one or more of these options: \code{"median"}, \code{"mean"}, \code{"MAP"} or \code{"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{...}{Additional arguments to be passed to or from methods.}
\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 various point-estimates, such as the mean, the median or the MAP, to describe posterior distributions.
}
\examples{
library(bayestestR)
point_estimate(rnorm(1000))
point_estimate(rnorm(1000), centrality = "all", dispersion = TRUE)
point_estimate(rnorm(1000), centrality = c("median", "MAP"))
df <- data.frame(replicate(4, rnorm(100)))
point_estimate(df, centrality = "all", dispersion = TRUE)
point_estimate(df, centrality = c("median", "MAP"))
\dontrun{
# rstanarm models
# -----------------------------------------------
library(rstanarm)
model <- rstanarm::stan_glm(mpg ~ wt + cyl, data = mtcars)
point_estimate(model, centrality = "all", dispersion = TRUE)
point_estimate(model, centrality = c("median", "MAP"))
# emmeans estimates
# -----------------------------------------------
library(emmeans)
point_estimate(emtrends(model, ~1, "wt"), centrality = c("median", "MAP"))
# brms models
# -----------------------------------------------
library(brms)
model <- brms::brm(mpg ~ wt + cyl, data = mtcars)
point_estimate(model, centrality = "all", dispersion = TRUE)
point_estimate(model, centrality = c("median", "MAP"))
# BayesFactor objects
# -----------------------------------------------
library(BayesFactor)
bf <- ttestBF(x = rnorm(100, 1, 1))
point_estimate(bf, centrality = "all", dispersion = TRUE)
point_estimate(bf, centrality = c("median", "MAP"))
}
}
\references{
\href{https://easystats.github.io/bayestestR/articles/indicesEstimationComparison.html}{Vignette In-Depth 1: Comparison of Point-Estimates}
}
bayestestR/man/area_under_curve.Rd 0000644 0001762 0000144 00000002772 13571067531 016772 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/area_under_curve.R
\name{area_under_curve}
\alias{area_under_curve}
\alias{auc}
\title{Area under the Curve (AUC)}
\usage{
area_under_curve(x, y, method = c("trapezoid", "step", "spline"), ...)
auc(x, y, method = c("trapezoid", "step", "spline"), ...)
}
\arguments{
\item{x}{Vector of x values.}
\item{y}{Vector of y values.}
\item{method}{Method to compute the Area Under the Curve (AUC). Can be \code{"trapezoid"} (default), \code{"step"} or \code{"spline"}. If "trapezoid", the curve is formed by connecting all points by a direct line (composite trapezoid rule). If "step" is chosen then a stepwise connection of two points is used. For calculating the area under a spline interpolation the splinefun function is used in combination with integrate.}
\item{...}{Arguments passed to or from other methods.}
}
\description{
Based on the DescTools \code{AUC} function. It can calculate the area under the curve with a naive algorithm or a more elaborated spline approach. The curve must be given by vectors of xy-coordinates. This function can handle unsorted x values (by sorting x) and ties for the x values (by ignoring duplicates).
}
\examples{
library(bayestestR)
posterior <- distribution_normal(1000)
dens <- estimate_density(posterior)
dens <- dens[dens$x > 0, ]
x <- dens$x
y <- dens$y
area_under_curve(x, y, method = "trapezoid")
area_under_curve(x, y, method = "step")
area_under_curve(x, y, method = "spline")
}
\seealso{
DescTools
}
bayestestR/man/p_map.Rd 0000644 0001762 0000144 00000007753 13616544116 014560 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/p_map.R
\name{p_map}
\alias{p_map}
\alias{p_pointnull}
\alias{p_map.stanreg}
\alias{p_map.brmsfit}
\title{Bayesian p-value based on the density at the Maximum A Posteriori (MAP)}
\usage{
p_map(x, precision = 2^10, method = "kernel", ...)
p_pointnull(x, precision = 2^10, method = "kernel", ...)
\method{p_map}{stanreg}(
x,
precision = 2^10,
method = "kernel",
effects = c("fixed", "random", "all"),
parameters = NULL,
...
)
\method{p_map}{brmsfit}(
x,
precision = 2^10,
method = "kernel",
effects = c("fixed", "random", "all"),
component = c("conditional", "zi", "zero_inflated", "all"),
parameters = NULL,
...
)
}
\arguments{
\item{x}{Vector representing a posterior distribution. Can also be a
\code{stanreg}, \code{brmsfit} or a \code{BayesFactor} model.}
\item{precision}{Number of points of density data. See the \code{n} parameter in \link[=density]{density}.}
\item{method}{Density estimation method. Can be \code{"kernel"} (default), \code{"logspline"} or \code{"KernSmooth"}.}
\item{...}{Currently not used.}
\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 a Bayesian equivalent of the \emph{p}-value, related to the odds that a parameter (described by its posterior distribution) has against the null hypothesis (\emph{h0}) using Mills' (2014, 2017) \emph{Objective Bayesian Hypothesis Testing} framework. It corresponds to the density value at 0 divided by the density at the Maximum A Posteriori (MAP).
}
\details{
Note that this method is sensitive to the density estimation \code{method} (see the secion in the examples below).
\subsection{Strengths and Limitations}{
\strong{Strengths:} Straightforward computation. Objective property of the posterior distribution.
\cr \cr
\strong{Limitations:} Limited information favoring the null hypothesis. Relates on density approximation. Indirect relationship between mathematical definition and interpretation. Only suitable for weak / very diffused priors.
}
}
\examples{
library(bayestestR)
p_map(rnorm(1000, 0, 1))
p_map(rnorm(1000, 10, 1))
\dontrun{
library(rstanarm)
model <- stan_glm(mpg ~ wt + gear, data = mtcars, chains = 2, iter = 200, refresh = 0)
p_map(model)
library(emmeans)
p_map(emtrends(model, ~1, "wt"))
library(brms)
model <- brms::brm(mpg ~ wt + cyl, data = mtcars)
p_map(model)
library(BayesFactor)
bf <- ttestBF(x = rnorm(100, 1, 1))
p_map(bf)
}
\donttest{
# ---------------------------------------
# Robustness to density estimation method
set.seed(333)
data <- data.frame()
for (iteration in 1:250) {
x <- rnorm(1000, 1, 1)
result <- data.frame(
"Kernel" = p_map(x, method = "kernel"),
"KernSmooth" = p_map(x, method = "KernSmooth"),
"logspline" = p_map(x, method = "logspline")
)
data <- rbind(data, result)
}
data$KernSmooth <- data$Kernel - data$KernSmooth
data$logspline <- data$Kernel - data$logspline
summary(data$KernSmooth)
summary(data$logspline)
boxplot(data[c("KernSmooth", "logspline")])
}
}
\references{
\itemize{
\item Makowski D, Ben-Shachar MS, Chen SHA, 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}
\item Mills, J. A. (2018). Objective Bayesian Precise Hypothesis Testing. University of Cincinnati.
}
}
\seealso{
\href{https://www.youtube.com/watch?v=Ip8Ci5KUVRc}{Jeff Mill's talk}
}
bayestestR/man/equivalence_test.Rd 0000644 0001762 0000144 00000017245 13571067531 017022 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/equivalence_test.R
\name{equivalence_test}
\alias{equivalence_test}
\alias{equivalence_test.default}
\alias{equivalence_test.numeric}
\alias{equivalence_test.data.frame}
\alias{equivalence_test.emmGrid}
\alias{equivalence_test.BFBayesFactor}
\alias{equivalence_test.stanreg}
\alias{equivalence_test.brmsfit}
\title{Test for Practical Equivalence}
\usage{
equivalence_test(x, ...)
\method{equivalence_test}{default}(x, ...)
\method{equivalence_test}{numeric}(x, range = "default", ci = 0.89, verbose = TRUE, ...)
\method{equivalence_test}{data.frame}(x, range = "default", ci = 0.89, verbose = TRUE, ...)
\method{equivalence_test}{emmGrid}(x, range = "default", ci = 0.89, verbose = TRUE, ...)
\method{equivalence_test}{BFBayesFactor}(x, range = "default", ci = 0.89, verbose = TRUE, ...)
\method{equivalence_test}{stanreg}(
x,
range = "default",
ci = 0.89,
effects = c("fixed", "random", "all"),
parameters = NULL,
verbose = TRUE,
...
)
\method{equivalence_test}{brmsfit}(
x,
range = "default",
ci = 0.89,
effects = c("fixed", "random", "all"),
component = c("conditional", "zi", "zero_inflated", "all"),
parameters = NULL,
verbose = TRUE,
...
)
}
\arguments{
\item{x}{Vector representing a posterior distribution. Can also be a \code{stanreg} or \code{brmsfit} model.}
\item{...}{Currently not used.}
\item{range}{ROPE's lower and higher bounds. Should be a vector of length two (e.g., \code{c(-0.1, 0.1)}) or \code{"default"}. If \code{"default"}, the range is set to \code{c(-0.1, 0.1)} if input is a vector, and based on \code{\link[=rope_range]{rope_range()}} if a Bayesian model is provided.}
\item{ci}{The Credible Interval (CI) probability, corresponding to the proportion of HDI, to use for the percentage in ROPE.}
\item{verbose}{Toggle off warnings.}
\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.}
}
\value{
A data frame with following columns:
\itemize{
\item \code{Parameter} The model parameter(s), if \code{x} is a model-object. If \code{x} is a vector, this column is missing.
\item \code{CI} The probability of the HDI.
\item \code{ROPE_low}, \code{ROPE_high} The limits of the ROPE. These values are identical for all parameters.
\item \code{ROPE_Percentage} The proportion of the HDI that lies inside the ROPE.
\item \code{ROPE_Equivalence} The "test result", as character. Either "rejected", "accepted" or "undecided".
\item \code{HDI_low} , \code{HDI_high} The lower and upper HDI limits for the parameters.
}
}
\description{
Perform a \strong{Test for Practical Equivalence} for Bayesian and frequentist models.
}
\details{
Documentation is accessible for:
\itemize{
\item \href{https://easystats.github.io/bayestestR/reference/equivalence_test.html}{Bayesian models}
\item \href{https://easystats.github.io/parameters/reference/equivalence_test.lm.html}{Frequentist models}
}
For Bayesian models, the \strong{Test for Practical Equivalence} is based on the \emph{"HDI+ROPE decision rule"} (\cite{Kruschke, 2014, 2018}) to check whether parameter values should be accepted or rejected against an explicitly formulated "null hypothesis" (i.e., a ROPE). In other words, it checks the percentage of the 89\% \link[=hdi]{HDI} that is the null region (the ROPE). If this percentage is sufficiently low, the null hypothesis is rejected. If this percentage is sufficiently high, the null hypothesis is accepted.
Using the \link[=rope]{ROPE} and the \link[=hdi]{HDI}, \cite{Kruschke (2018)}
suggests using the percentage of the 95\% (or 89\%, considered more stable)
HDI that falls within the ROPE as a decision rule. If the HDI
is completely outside the ROPE, the "null hypothesis" for this parameter is
"rejected". If the ROPE completely covers the HDI, i.e., all most credible
values of a parameter are inside the region of practical equivalence, the
null hypothesis is accepted. Else, it’s undecided whether to accept or
reject the null hypothesis. If the full ROPE is used (i.e., 100\% of the
HDI), then the null hypothesis is rejected or accepted if the percentage
of the posterior within the ROPE is smaller than to 2.5\% or greater than
97.5\%. Desirable results are low proportions inside the ROPE (the closer
to zero the better).
\cr \cr
Some attention is required for finding suitable values for the ROPE limits
(argument \code{range}). See 'Details' in \code{\link[=rope_range]{rope_range()}}
for further information.
\cr \cr
\strong{Multicollinearity: Non-independent covariates}
\cr \cr
When parameters show strong correlations, i.e. when covariates are not
independent, the joint parameter distributions may shift towards or
away from the ROPE. In such cases, the test for practical equivalence may
have inappropriate results. Collinearity invalidates ROPE and hypothesis
testing based on univariate marginals, as the probabilities are conditional
on independence. Most problematic are the results of the "undecided"
parameters, which may either move further towards "rejection" or away
from it (\cite{Kruschke 2014, 340f}).
\cr \cr
\code{equivalence_test()} performs a simple check for pairwise correlations
between parameters, but as there can be collinearity between more than two variables,
a first step to check the assumptions of this hypothesis testing is to look
at different pair plots. An even more sophisticated check is the projection
predictive variable selection (\cite{Piironen and Vehtari 2017}).
}
\note{
There is a \code{print()}-method with a \code{digits}-argument to control
the amount of digits in the output, and there is a \code{plot()}-method
to visualize the results from the equivalence-test (for models only).
}
\examples{
library(bayestestR)
equivalence_test(x = rnorm(1000, 0, 0.01), range = c(-0.1, 0.1))
equivalence_test(x = rnorm(1000, 0, 1), range = c(-0.1, 0.1))
equivalence_test(x = rnorm(1000, 1, 0.01), range = c(-0.1, 0.1))
equivalence_test(x = rnorm(1000, 1, 1), ci = c(.50, .99))
# print more digits
test <- equivalence_test(x = rnorm(1000, 1, 1), ci = c(.50, .99))
print(test, digits = 4)
\dontrun{
library(rstanarm)
model <- rstanarm::stan_glm(mpg ~ wt + cyl, data = mtcars)
equivalence_test(model)
equivalence_test(model, ci = c(.50, 1))
# plot result
test <- equivalence_test(model)
plot(test)
library(emmeans)
equivalence_test(emtrends(model, ~1, "wt"))
library(brms)
model <- brms::brm(mpg ~ wt + cyl, data = mtcars)
equivalence_test(model)
equivalence_test(model, ci = c(.50, .99))
ibrary(BayesFactor)
bf <- ttestBF(x = rnorm(100, 1, 1))
equivalence_test(bf)
equivalence_test(bf, ci = c(.50, .99))
}
}
\references{
\itemize{
\item Kruschke, J. K. (2018). Rejecting or accepting parameter values in Bayesian estimation. Advances in Methods and Practices in Psychological Science, 1(2), 270-280. \doi{10.1177/2515245918771304}
\item Kruschke, J. (2014). Doing Bayesian data analysis: A tutorial with R, JAGS, and Stan. Academic Press
\item Piironen, J., & Vehtari, A. (2017). Comparison of Bayesian predictive methods for model selection. Statistics and Computing, 27(3), 711–735. \doi{10.1007/s11222-016-9649-y}
}
}
bayestestR/man/convert_bayesian_as_frequentist.Rd 0000644 0001762 0000144 00000002433 13616544116 022121 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/convert_bayesian_to_frequentist.R
\name{convert_bayesian_as_frequentist}
\alias{convert_bayesian_as_frequentist}
\alias{bayesian_as_frequentist}
\title{Convert (refit) a Bayesian model to frequentist}
\usage{
convert_bayesian_as_frequentist(model, data = NULL)
bayesian_as_frequentist(model, data = NULL)
}
\arguments{
\item{model}{A Bayesian model.}
\item{data}{Data used by the model. If \code{NULL}, will try to extract it from the model.}
}
\description{
Refit Bayesian model as frequentist. Can be useful for comparisons.
}
\examples{
\donttest{
# Rstanarm ----------------------
if (require("rstanarm")) {
# Simple regressions
model <- stan_glm(Sepal.Length ~ Petal.Length * Species,
data = iris, chains = 2, refresh = 0
)
bayesian_as_frequentist(model)
model <- stan_glm(vs ~ mpg,
family = "binomial",
data = mtcars, chains = 2, refresh = 0
)
bayesian_as_frequentist(model)
# Mixed models
model <- stan_glmer(Sepal.Length ~ Petal.Length + (1 | Species),
data = iris, chains = 2, refresh = 0
)
bayesian_as_frequentist(model)
model <- stan_glmer(vs ~ mpg + (1 | cyl),
family = "binomial",
data = mtcars, chains = 2, refresh = 0
)
bayesian_as_frequentist(model)
}
}
}
bayestestR/man/as.data.frame.density.Rd 0000644 0001762 0000144 00000000577 13620150257 017535 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/estimate_density.R
\name{as.data.frame.density}
\alias{as.data.frame.density}
\title{Coerce to a Data Frame}
\usage{
\method{as.data.frame}{density}(x, ...)
}
\arguments{
\item{x}{any \R object.}
\item{...}{additional arguments to be passed to or from methods.}
}
\description{
Coerce to a Data Frame
}
bayestestR/man/contr.bayes.Rd 0000644 0001762 0000144 00000004272 13571067531 015705 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/contr.bayes.R
\name{contr.bayes}
\alias{contr.bayes}
\title{Orthonormal Contrast Matrices for Bayesian Estimation}
\usage{
contr.bayes(n, contrasts = TRUE)
}
\arguments{
\item{n}{a vector of levels for a factor, or the number of levels.}
\item{contrasts}{logical indicating whether contrasts should be computed.}
}
\value{
A \code{matrix} with n rows and k columns, with k=n-1 if contrasts is
\code{TRUE} and k=n if contrasts is \code{FALSE}.
}
\description{
Returns a design or model matrix of orthonormal contrasts such that the
marginal prior on all effects is identical. Implementation from Singmann
\& Gronau's \href{https://github.com/bayesstuff/bfrms/}{\code{bfrms}},
following the description in Rouder, Morey, Speckman, \& Province (2012, p. 363).
}
\details{
Though using this factor coding scheme might obscure the interpretation of
parameters, it is essential for correct estimation of Bayes factors for
contrasts and multi-level order restrictions. See info on specifying correct
priors for factors with more than 2 levels in
\href{https://easystats.github.io/bayestestR/articles/bayes_factors.html}{the Bayes factors vignette}.
}
\examples{
\dontrun{
contr.bayes(2) # Q_2 in Rouder et al. (2012, p. 363)
# [,1]
# [1,] -0.7071068
# [2,] 0.7071068
contr.bayes(5) # equivalent to Q_5 in Rouder et al. (2012, p. 363)
# [,1] [,2] [,3] [,4]
# [1,] 0.0000000 0.8944272 0.0000000 0.0000000
# [2,] 0.0000000 -0.2236068 -0.5000000 0.7071068
# [3,] 0.7071068 -0.2236068 -0.1666667 -0.4714045
# [4,] -0.7071068 -0.2236068 -0.1666667 -0.4714045
# [5,] 0.0000000 -0.2236068 0.8333333 0.2357023
## check decomposition
Q3 <- contr.bayes(3)
Q3 \%*\% t(Q3)
# [,1] [,2] [,3]
# [1,] 0.6666667 -0.3333333 -0.3333333
# [2,] -0.3333333 0.6666667 -0.3333333
# [3,] -0.3333333 -0.3333333 0.6666667
## 2/3 on diagonal and -1/3 on off-diagonal elements
}
}
\references{
Rouder, J. N., Morey, R. D., Speckman, P. L., \& Province, J. M.
(2012). Default Bayes factors for ANOVA designs. *Journal of Mathematical
Psychology*, 56(5), 356-374. https://doi.org/10.1016/j.jmp.2012.08.001
}
bayestestR/man/si.Rd 0000644 0001762 0000144 00000013624 13610203766 014066 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/si.R
\name{si}
\alias{si}
\alias{si.numeric}
\alias{si.stanreg}
\alias{si.brmsfit}
\alias{si.emmGrid}
\alias{si.data.frame}
\title{Compute Support Intervals}
\usage{
si(posterior, prior = NULL, BF = 1, verbose = TRUE, ...)
\method{si}{numeric}(posterior, prior = NULL, BF = 1, verbose = TRUE, ...)
\method{si}{stanreg}(
posterior,
prior = NULL,
BF = 1,
verbose = TRUE,
effects = c("fixed", "random", "all"),
component = c("conditional", "zi", "zero_inflated", "all"),
parameters = NULL,
...
)
\method{si}{brmsfit}(
posterior,
prior = NULL,
BF = 1,
verbose = TRUE,
effects = c("fixed", "random", "all"),
component = c("conditional", "zi", "zero_inflated", "all"),
parameters = NULL,
...
)
\method{si}{emmGrid}(posterior, prior = NULL, BF = 1, verbose = TRUE, ...)
\method{si}{data.frame}(posterior, prior = NULL, BF = 1, verbose = TRUE, ...)
}
\arguments{
\item{posterior}{A numerical vector, \code{stanreg} / \code{brmsfit} object, \code{emmGrid}
or a data frame - representing a posterior distribution(s) from (see 'Details').}
\item{prior}{An object representing a prior distribution (see 'Details').}
\item{BF}{The amount of support required to be included in the support interval.}
\item{verbose}{Toggle off warnings.}
\item{...}{Arguments passed to and from other methods.}
\item{effects}{Should results for fixed effects, random effects or both be returned?
Only applies to mixed models. May be abbreviated.}
\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.}
\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.}
}
\value{
A data frame containing the lower and upper bounds of the SI.
\cr
Note that if the level of requested support is higher than observed in the data, the
interval will be \code{[NA,NA]}.
}
\description{
A support interval contains only the values of the parameter that predict the observed data better
than average, by some degree \emph{k}; these are values of the parameter that are associated with an
updating factor greater or equal than \emph{k}. From the perspective of the Savage-Dickey Bayes factor, testing
against a point null hypothesis for any value within the support interval will yield a Bayes factor smaller
than \emph{1/k}.
\cr \cr
\strong{For more info, in particular on specifying correct priors for factors with more than 2 levels,
see \href{https://easystats.github.io/bayestestR/articles/bayes_factors.html}{the Bayes factors vignette}.}
}
\details{
This method is used to compute support intervals based on prior and posterior distributions.
For the computation of support intervals, the model priors must be proper priors (at the very least
they should be \emph{not flat}, and it is preferable that they be \emph{informative} - note
that by default, \code{brms::brm()} uses flat priors for fixed-effects; see example below).
\subsection{Setting the correct \code{prior}}{
It is important to provide the correct \code{prior} for meaningful results.
\itemize{
\item When \code{posterior} is a numerical vector, \code{prior} should also be a numerical vector.
\item When \code{posterior} is a \code{data.frame}, \code{prior} should also be a \code{data.frame}, with matching column order.
\item When \code{posterior} is a \code{stanreg} or \code{brmsfit} model: \itemize{
\item \code{prior} can be set to \code{NULL}, in which case prior samples are drawn internally.
\item \code{prior} can also be a model equvilant to \code{posterior} but with samples from the priors \emph{only}.
}
\item When \code{posterior} is an \code{emmGrid} object: \itemize{
\item \code{prior} should be the \code{stanreg} or \code{brmsfit} model used to create the \code{emmGrid} objects.
\item \code{prior} can also be an \code{emmGrid} object equvilant to \code{posterior} but created with a model of priors samples \emph{only}.
}
}}
\subsection{Choosing a value of \code{BF}}{
The choice of \code{BF} (the level of support) depends on what we want our interval to represent:
\itemize{
\item A \code{BF} = 1 contains values whose credibility is not decreased by observing the data.
\item A \code{BF} > 1 contains values who recived more impressive support from the data.
\item A \code{BF} < 1 contains values whose credibility has \emph{not} been impressively decreased by observing the data.
Testing against values outside this interval will produce a Bayes factor larger than 1/\code{BF} in support of
the alternative. E.g., if an SI (BF = 1/3) excludes 0, the Bayes factor against the point-null will be larger than 3.
}
}
}
\examples{
library(bayestestR)
prior <- distribution_normal(1000, mean = 0, sd = 1)
posterior <- distribution_normal(1000, mean = .5, sd = .3)
si(posterior, prior)
\dontrun{
# rstanarm models
# ---------------
library(rstanarm)
contrasts(sleep$group) <- contr.bayes # see vingette
stan_model <- stan_lmer(extra ~ group + (1 | ID), data = sleep)
si(stan_model)
si(stan_model, BF = 3)
# emmGrid objects
# ---------------
library(emmeans)
group_diff <- pairs(emmeans(stan_model, ~group))
si(group_diff, prior = stan_model)
# brms models
# -----------
library(brms)
contrasts(sleep$group) <- contr.bayes # see vingette
my_custom_priors <-
set_prior("student_t(3, 0, 1)", class = "b") +
set_prior("student_t(3, 0, 1)", class = "sd", group = "ID")
brms_model <- brm(extra ~ group + (1 | ID),
data = sleep,
prior = my_custom_priors
)
si(brms_model)
}
}
\references{
Wagenmakers, E., Gronau, Q. F., Dablander, F., & Etz, A. (2018, November 22). The Support Interval. \doi{10.31234/osf.io/zwnxb}
}
bayestestR/man/weighted_posteriors.Rd 0000644 0001762 0000144 00000011631 13610210602 017523 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/weighted_posteriors.R
\name{weighted_posteriors}
\alias{weighted_posteriors}
\alias{weighted_posteriors.stanreg}
\alias{weighted_posteriors.brmsfit}
\alias{weighted_posteriors.BFBayesFactor}
\title{Generate posterior distributions weighted across models}
\usage{
weighted_posteriors(..., prior_odds = NULL, missing = 0, verbose = TRUE)
\method{weighted_posteriors}{stanreg}(
...,
prior_odds = NULL,
missing = 0,
verbose = TRUE,
effects = c("fixed", "random", "all"),
component = c("conditional", "zi", "zero_inflated", "all"),
parameters = NULL
)
\method{weighted_posteriors}{brmsfit}(
...,
prior_odds = NULL,
missing = 0,
verbose = TRUE,
effects = c("fixed", "random", "all"),
component = c("conditional", "zi", "zero_inflated", "all"),
parameters = NULL
)
\method{weighted_posteriors}{BFBayesFactor}(..., prior_odds = NULL, missing = 0, verbose = TRUE)
}
\arguments{
\item{...}{Fitted models (see details), all fit on the same data, or a single \code{BFBayesFactor} object (see 'Details').}
\item{prior_odds}{Optional vector of prior odds for the models. See \code{BayesFactor::priorOdds<-}.}
\item{missing}{An optional numeric value to use if a model does not contain a parameter that appears in other models. Defaults to 0.}
\item{verbose}{Toggle off warnings.}
\item{effects}{Should results for fixed effects, random effects or both be returned?
Only applies to mixed models. May be abbreviated.}
\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.}
\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.}
}
\value{
A data frame with posterior distributions (weighted accross models) .
}
\description{
Extract posterior samples of parameters, weighted across models.
Weighting is done by comparing posterior model probabilities, via \code{\link{bayesfactor_models}}.
}
\details{
Note that across models some parameters might play different roles. For example,
the parameter \code{A} plays a different role in the model \code{Y ~ A + B} (where it is a main effect)
than it does in the model \code{Y ~ A + B + A:B} (where it is a simple effect). In many cases centering
of predictors (mean subtracting for continuous variables, and effects coding via \code{contr.sum} or
orthonormal coding via {\code{\link{contr.bayes}}} for factors) can reduce this issue. In any case
you should be mindful of this issue.
\cr\cr
See \code{\link{bayesfactor_models}} details for more info on passed models.
\cr\cr
Note that for \code{BayesFactor} models, posterior samples cannot be generated from intercept only models.
\cr\cr
This function is similar in function to \code{brms::\link[brms]{posterior_average}}.
}
\examples{
\donttest{
library(rstanarm)
library(see)
stan_m0 <- stan_glm(extra ~ 1, data = sleep,
family = gaussian(),
refresh=0,
diagnostic_file = file.path(tempdir(), "df0.csv"))
stan_m1 <- stan_glm(extra ~ group, data = sleep,
family = gaussian(),
refresh=0,
diagnostic_file = file.path(tempdir(), "df1.csv"))
res <- weighted_posteriors(stan_m0, stan_m1)
plot(eti(res))
# With BayesFactor and brms
library(BayesFactor)
library(brms)
BFmods <- anovaBF(extra ~ group + ID, sleep, whichRandom = "ID")
res <- weighted_posteriors(BFmods)[1:3]
plot(eti(res))
# Compare to brms::posterior_average
fit1 <- brm(rating ~ treat + period + carry,
data = inhaler,
save_all_pars = TRUE)
fit2 <- brm(rating ~ period + carry,
data = inhaler,
save_all_pars = TRUE)
res_BT <- weighted_posteriors(fit1, fit2)
res_brms <- brms::posterior_average(fit1, fit2, weights = "marglik", missing = 0)[, 1:4]
plot(eti(res_BT))
plot(eti(res_brms))
}
}
\references{
\itemize{
\item Clyde, M., Desimone, H., & Parmigiani, G. (1996). Prediction via orthogonalized model mixing. Journal of the American Statistical Association, 91(435), 1197-1208.
\item Hinne, M., Gronau, Q. F., van den Bergh, D., and Wagenmakers, E. (2019, March 25). A conceptual introduction to Bayesian Model Averaging. \doi{10.31234/osf.io/wgb64}
\item Rouder, J. N., Haaf, J. M., & Vandekerckhove, J. (2018). Bayesian inference for psychology, part IV: Parameter estimation and Bayes factors. Psychonomic bulletin & review, 25(1), 102-113.
\item van den Bergh, D., Haaf, J. M., Ly, A., Rouder, J. N., & Wagenmakers, E. J. (2019). A cautionary note on estimating effect size.
}
}
\seealso{
\code{\link{bayesfactor_inclusion}} for Bayesian model averaging.
}
bayestestR/man/distribution.Rd 0000644 0001762 0000144 00000006324 13610203766 016171 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/distribution.R
\name{distribution}
\alias{distribution}
\alias{distribution_normal}
\alias{distribution_binomial}
\alias{distribution_cauchy}
\alias{distribution_poisson}
\alias{distribution_student}
\alias{distribution_chisquared}
\alias{distribution_uniform}
\alias{distribution_beta}
\alias{distribution_tweedie}
\alias{distribution_gamma}
\alias{distribution_custom}
\alias{distribution_mixture_normal}
\alias{rnorm_perfect}
\title{Empirical Distributions}
\usage{
distribution(type = "normal", ...)
distribution_normal(n, mean = 0, sd = 1, random = FALSE, ...)
distribution_binomial(n, size = 1, prob = 0.5, random = FALSE, ...)
distribution_cauchy(n, location = 0, scale = 1, random = FALSE, ...)
distribution_poisson(n, lambda = 1, random = FALSE, ...)
distribution_student(n, df, ncp, random = FALSE, ...)
distribution_chisquared(n, df, ncp = 0, random = FALSE, ...)
distribution_uniform(n, min = 0, max = 1, random = FALSE, ...)
distribution_beta(n, shape1, shape2, ncp = 0, random = FALSE, ...)
distribution_tweedie(n, xi = NULL, mu, phi, power = NULL, random = FALSE, ...)
distribution_gamma(n, shape, scale = 1, random = FALSE, ...)
distribution_custom(n, type = "norm", ..., random = FALSE)
distribution_mixture_normal(n, mean = c(-3, 3), sd = 1, random = FALSE, ...)
rnorm_perfect(n, mean = 0, sd = 1)
}
\arguments{
\item{type}{Can be any of the names from base R's \link[stats]{Distributions}, like \code{"cauchy"}, \code{"pois"} or \code{"beta"}.}
\item{...}{Arguments passed to or from other methods.}
\item{n}{number of observations. If \code{length(n) > 1}, the length
is taken to be the number required.}
\item{mean}{vector of means.}
\item{sd}{vector of standard deviations.}
\item{random}{Generate near-perfect or random (simple wrappers for the base R \code{r*} functions) distributions.}
\item{size}{number of trials (zero or more).}
\item{prob}{probability of success on each trial.}
\item{location}{location and scale parameters.}
\item{scale}{location and scale parameters.}
\item{lambda}{vector of (non-negative) means.}
\item{df}{degrees of freedom (\eqn{> 0}, maybe non-integer). \code{df
= Inf} is allowed.}
\item{ncp}{non-centrality parameter \eqn{\delta}{delta};
currently except for \code{rt()}, only for \code{abs(ncp) <= 37.62}.
If omitted, use the central t distribution.}
\item{min}{lower and upper limits of the distribution. Must be finite.}
\item{max}{lower and upper limits of the distribution. Must be finite.}
\item{shape1}{non-negative parameters of the Beta distribution.}
\item{shape2}{non-negative parameters of the Beta distribution.}
\item{xi}{the value of \eqn{\xi}{xi} such that the variance is
\eqn{\mbox{var}[Y]=\phi\mu^{\xi}}{var(Y) = phi * mu^xi}}
\item{mu}{the mean}
\item{phi}{the dispersion}
\item{power}{a synonym for \eqn{\xi}{xi}}
\item{shape}{shape and scale parameters. Must be positive,
\code{scale} strictly.}
}
\description{
Generate a sequence of n-quantiles, i.e., a sample of size \code{n} with a near-perfect distribution.
}
\examples{
library(bayestestR)
x <- distribution(n = 10)
plot(density(x))
x <- distribution(type = "gamma", n = 100, shape = 2)
plot(density(x))
}
bayestestR/man/describe_posterior.Rd 0000644 0001762 0000144 00000017050 13616544116 017341 0 ustar ligges users % 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.stanmvreg}
\alias{describe_posterior.MCMCglmm}
\alias{describe_posterior.brmsfit}
\alias{describe_posterior.BFBayesFactor}
\title{Describe Posterior Distributions}
\usage{
describe_posterior(
posteriors,
centrality = "median",
dispersion = FALSE,
ci = 0.89,
ci_method = "hdi",
test = c("p_direction", "rope"),
rope_range = "default",
rope_ci = 0.89,
...
)
\method{describe_posterior}{numeric}(
posteriors,
centrality = "median",
dispersion = FALSE,
ci = 0.89,
ci_method = "hdi",
test = c("p_direction", "rope"),
rope_range = "default",
rope_ci = 0.89,
bf_prior = NULL,
BF = 1,
...
)
\method{describe_posterior}{stanreg}(
posteriors,
centrality = "median",
dispersion = FALSE,
ci = 0.89,
ci_method = "hdi",
test = c("p_direction", "rope"),
rope_range = "default",
rope_ci = 0.89,
bf_prior = NULL,
diagnostic = c("ESS", "Rhat"),
priors = FALSE,
effects = c("fixed", "random", "all"),
parameters = NULL,
BF = 1,
...
)
\method{describe_posterior}{stanmvreg}(
posteriors,
centrality = "median",
dispersion = FALSE,
ci = 0.89,
ci_method = "hdi",
test = "p_direction",
rope_range = "default",
rope_ci = 0.89,
bf_prior = NULL,
diagnostic = c("ESS", "Rhat"),
priors = FALSE,
effects = c("fixed", "random", "all"),
parameters = NULL,
...
)
\method{describe_posterior}{MCMCglmm}(
posteriors,
centrality = "median",
dispersion = FALSE,
ci = 0.89,
ci_method = "hdi",
test = c("p_direction", "rope"),
rope_range = "default",
rope_ci = 0.89,
diagnostic = "ESS",
parameters = NULL,
...
)
\method{describe_posterior}{brmsfit}(
posteriors,
centrality = "median",
dispersion = FALSE,
ci = 0.89,
ci_method = "hdi",
test = c("p_direction", "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,
BF = 1,
...
)
\method{describe_posterior}{BFBayesFactor}(
posteriors,
centrality = "median",
dispersion = FALSE,
ci = 0.89,
ci_method = "hdi",
test = c("p_direction", "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. Character (vector) or list with one or more of these options: \code{"median"}, \code{"mean"}, \code{"MAP"} or \code{"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 CI (between 0 and 1)
to be estimated. Default to \code{.89} (89\%) for Bayesian models and \code{.95} (95\%) for frequentist models.}
\item{ci_method}{The type of index used for Credible Interval. Can be
\code{"HDI"} (default, see \code{\link[bayestestR:hdi]{hdi}}), \code{"ETI"}
(see \code{\link[bayestestR:eti]{eti}}) or \code{"SI"}
(see \code{\link[bayestestR:si]{si}}).}
\item{test}{The indices of effect existence to compute. Character (vector) or
list with one or more of these options: \code{"p_direction"} (or \code{"pd"}),
\code{"rope"}, \code{"p_map"}, \code{"equivalence_test"} (or \code{"equitest"}),
\code{"bayesfactor"} (or \code{"bf"}) or \code{"all"} to compute all tests.
For each "test", the corresponding \pkg{bayestestR} function is called
(e.g. \code{\link[bayestestR:rope]{rope}} or \code{\link[bayestestR:p_direction]{p_direction}}) and its results
included in the summary output.}
\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 / SI. Used if the input is a posterior, otherwise (in the case of models) ignored.}
\item{BF}{The amount of support required to be included in the support interval.}
\item{diagnostic}{Diagnostic metrics to compute. Character (vector) or list with one or more of these options: \code{"ESS"}, \code{"Rhat"}, \code{"MCSE"} or \code{"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.
}
\details{
One or more components of point estimates (like posterior mean or median),
intervals and tests can be ommitted from the summary output by setting the
related argument to \code{NULL}. For example, \code{test = NULL} and
\code{centrality = NULL} would only return the HDI (or CI).
}
\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))
\dontrun{
# 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))
}
}
}
\references{
\itemize{
\item \href{https://easystats.github.io/bayestestR/articles/indicesEstimationComparison.html}{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}
}
}
bayestestR/man/hdi.Rd 0000644 0001762 0000144 00000013074 13616544116 014221 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hdi.R
\name{hdi}
\alias{hdi}
\alias{hdi.numeric}
\alias{hdi.data.frame}
\alias{hdi.MCMCglmm}
\alias{hdi.sim.merMod}
\alias{hdi.sim}
\alias{hdi.emmGrid}
\alias{hdi.stanreg}
\alias{hdi.brmsfit}
\alias{hdi.BFBayesFactor}
\title{Highest Density Interval (HDI)}
\usage{
hdi(x, ...)
\method{hdi}{numeric}(x, ci = 0.89, verbose = TRUE, ...)
\method{hdi}{data.frame}(x, ci = 0.89, verbose = TRUE, ...)
\method{hdi}{MCMCglmm}(x, ci = 0.89, verbose = TRUE, ...)
\method{hdi}{sim.merMod}(
x,
ci = 0.89,
effects = c("fixed", "random", "all"),
parameters = NULL,
verbose = TRUE,
...
)
\method{hdi}{sim}(x, ci = 0.89, parameters = NULL, verbose = TRUE, ...)
\method{hdi}{emmGrid}(x, ci = 0.89, verbose = TRUE, ...)
\method{hdi}{stanreg}(
x,
ci = 0.89,
effects = c("fixed", "random", "all"),
parameters = NULL,
verbose = TRUE,
...
)
\method{hdi}{brmsfit}(
x,
ci = 0.89,
effects = c("fixed", "random", "all"),
component = c("conditional", "zi", "zero_inflated", "all"),
parameters = NULL,
verbose = TRUE,
...
)
\method{hdi}{BFBayesFactor}(x, ci = 0.89, verbose = TRUE, ...)
}
\arguments{
\item{x}{Vector representing a posterior distribution. Can also be a
\code{stanreg}, \code{brmsfit} or a \code{BayesFactor} model.}
\item{...}{Currently not used.}
\item{ci}{Value or vector of probability of the (credible) interval - CI (between 0 and 1)
to be estimated. Default to \code{.89} (89\%).}
\item{verbose}{Toggle off warnings.}
\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.}
}
\value{
A data frame with following columns:
\itemize{
\item \code{Parameter} The model parameter(s), if \code{x} is a model-object. If \code{x} is a vector, this column is missing.
\item \code{CI} The probability of the credible interval.
\item \code{CI_low}, \code{CI_high} The lower and upper credible interval limits for the parameters.
}
}
\description{
Compute the \strong{Highest Density Interval (HDI)} of posterior distributions. All points within this interval have a higher probability density than points outside the interval. The HDI can be used in the context of uncertainty characterisation of posterior distributions as \strong{Credible Interval (CI)}.
}
\details{
Unlike equal-tailed intervals (see \code{eti()}) that typically exclude 2.5\%
from each tail of the distribution and always include the median, the HDI is
\emph{not} equal-tailed and therefore always includes the mode(s) of posterior
distributions.
\cr \cr
By default, \code{hdi()} and \code{eti()} return the 89\% intervals (\code{ci = 0.89}),
deemed to be more stable than, for instance, 95\% intervals (\cite{Kruschke, 2014}).
An effective sample size of at least 10.000 is recommended if 95\% intervals
should be computed (\cite{Kruschke, 2014, p. 183ff}). Moreover, 89 indicates
the arbitrariness of interval limits - its only remarkable property is being
the highest prime number that does not exceed the already unstable 95\%
threshold (\cite{McElreath, 2015}).
\cr \cr
A 90\% equal-tailed interval (ETI) has 5\% of the distribution on either
side of its limits. It indicates the 5th percentile and the 95h percentile.
In symmetric distributions, the two methods of computing credible intervals,
the ETI and the \link[=hdi]{HDI}, return similar results.
\cr \cr
This is not the case for skewed distributions. Indeed, it is possible that
parameter values in the ETI have lower credibility (are less probable) than
parameter values outside the ETI. This property seems undesirable as a summary
of the credible values in a distribution.
\cr \cr
On the other hand, the ETI range does change when transformations are applied
to the distribution (for instance, for a log odds scale to probabilities):
the lower and higher bounds of the transformed distribution will correspond
to the transformed lower and higher bounds of the original distribution.
On the contrary, applying transformations to the distribution will change
the resulting HDI.
}
\examples{
library(bayestestR)
posterior <- rnorm(1000)
hdi(posterior, ci = .89)
hdi(posterior, ci = c(.80, .90, .95))
df <- data.frame(replicate(4, rnorm(100)))
hdi(df)
hdi(df, ci = c(.80, .90, .95))
\dontrun{
library(rstanarm)
model <- stan_glm(mpg ~ wt + gear, data = mtcars, chains = 2, iter = 200, refresh = 0)
hdi(model)
hdi(model, ci = c(.80, .90, .95))
library(emmeans)
hdi(emtrends(model, ~1, "wt"))
library(brms)
model <- brms::brm(mpg ~ wt + cyl, data = mtcars)
hdi(model)
hdi(model, ci = c(.80, .90, .95))
library(BayesFactor)
bf <- ttestBF(x = rnorm(100, 1, 1))
hdi(bf)
hdi(bf, ci = c(.80, .90, .95))
}
}
\references{
\itemize{
\item Kruschke, J. (2014). Doing Bayesian data analysis: A tutorial with R, JAGS, and Stan. Academic Press.
\item McElreath, R. (2015). Statistical rethinking: A Bayesian course with examples in R and Stan. Chapman and Hall/CRC.
}
}
\author{
Credits go to \href{https://rdrr.io/cran/ggdistribute/src/R/stats.R}{ggdistribute} and \href{https://github.com/mikemeredith/HDInterval}{HDInterval}.
}
bayestestR/man/effective_sample.Rd 0000644 0001762 0000144 00000004777 13616544116 016770 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/effective_sample.R
\name{effective_sample}
\alias{effective_sample}
\alias{effective_sample.brmsfit}
\alias{effective_sample.stanreg}
\alias{effective_sample.MCMCglmm}
\title{Effective Sample Size (ESS)}
\usage{
effective_sample(model, ...)
\method{effective_sample}{brmsfit}(
model,
effects = c("fixed", "random", "all"),
component = c("conditional", "zi", "zero_inflated", "all"),
parameters = NULL,
...
)
\method{effective_sample}{stanreg}(
model,
effects = c("fixed", "random", "all"),
parameters = NULL,
...
)
\method{effective_sample}{MCMCglmm}(
model,
effects = c("fixed", "random", "all"),
parameters = NULL,
...
)
}
\arguments{
\item{model}{A \code{stanreg}, \code{stanfit}, or \code{brmsfit} object.}
\item{...}{Currently not used.}
\item{effects}{Should results for fixed effects, random effects or both be returned?
Only applies to mixed models. May be abbreviated.}
\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.}
\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.}
}
\value{
A data frame with two columns: Parameter name and effective sample size (ESS).
}
\description{
This function returns the effective sample size (ESS).
}
\details{
\strong{Effective Sample (ESS)} should be as large as possible, altough for most applications, an effective sample size greater than 1,000 is sufficient for stable estimates (Bürkner, 2017). The ESS corresponds to the number of independent samples with the same estimation power as the N autocorrelated samples. It is is a measure of \dQuote{how much independent information there is in autocorrelated chains} (\emph{Kruschke 2015, p182-3}).
}
\examples{
\dontrun{
library(rstanarm)
model <- stan_glm(mpg ~ wt + gear, data = mtcars, chains = 2, iter = 200, refresh = 0)
effective_sample(model)
}
}
\references{
\itemize{
\item Kruschke, J. (2014). Doing Bayesian data analysis: A tutorial with R, JAGS, and Stan. Academic Press.
\item Bürkner, P. C. (2017). brms: An R package for Bayesian multilevel models using Stan. Journal of Statistical Software, 80(1), 1-28
}
}
bayestestR/man/estimate_density.Rd 0000644 0001762 0000144 00000006722 13616544116 017031 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/estimate_density.R
\name{estimate_density}
\alias{estimate_density}
\title{Density Estimation}
\usage{
estimate_density(
x,
method = "kernel",
precision = 2^10,
extend = FALSE,
extend_scale = 0.1,
bw = "SJ",
...
)
}
\arguments{
\item{x}{Vector representing a posterior distribution. Can also be a
\code{stanreg}, \code{brmsfit} or a \code{BayesFactor} model.}
\item{method}{Density estimation method. Can be \code{"kernel"} (default), \code{"logspline"} or \code{"KernSmooth"}.}
\item{precision}{Number of points of density data. See the \code{n} parameter in \link[=density]{density}.}
\item{extend}{Extend the range of the x axis by a factor of \code{extend_scale}.}
\item{extend_scale}{Ratio of range by which to extend the x axis. A value of \code{0.1} means that the x axis will be extended by \code{1/10} of the range of the data.}
\item{bw}{the smoothing bandwidth to be used. The kernels are scaled
such that this is the standard deviation of the smoothing kernel.
(Note this differs from the reference books cited below, and from S-PLUS.)
\code{bw} can also be a character string giving a rule to choose the
bandwidth. See \code{\link[stats]{bw.nrd}}. \cr The default,
\code{"nrd0"}, has remained the default for historical and
compatibility reasons, rather than as a general recommendation,
where e.g., \code{"SJ"} would rather fit, see also Venables and
Ripley (2002).
The specified (or computed) value of \code{bw} is multiplied by
\code{adjust}.
}
\item{...}{Currently not used.}
}
\description{
This function is a wrapper over different methods of density estimation. By default, it uses the base R \link{density} with by default uses a different smoothing bandwidth (\code{"SJ"}) from the legacy default implemented the base R \link{density} function (\code{"nrd0"}). However, Deng \& Wickham suggest that \code{method = "KernSmooth"} is the fastest and the most accurate.
}
\examples{
library(bayestestR)
set.seed(1)
x <- rnorm(250, 1)
# Methods
density_kernel <- estimate_density(x, method = "kernel")
density_logspline <- estimate_density(x, method = "logspline")
density_KernSmooth <- estimate_density(x, method = "KernSmooth")
density_mixture <- estimate_density(x, method = "mixture")
hist(x, prob = TRUE)
lines(density_kernel$x, density_kernel$y, col = "black", lwd = 2)
lines(density_logspline$x, density_logspline$y, col = "red", lwd = 2)
lines(density_KernSmooth$x, density_KernSmooth$y, col = "blue", lwd = 2)
lines(density_mixture$x, density_mixture$y, col = "green", lwd = 2)
# Extension
density_extended <- estimate_density(x, extend = TRUE)
density_default <- estimate_density(x, extend = FALSE)
hist(x, prob = TRUE)
lines(density_extended$x, density_extended$y, col = "red", lwd = 3)
lines(density_default$x, density_default$y, col = "black", lwd = 3)
df <- data.frame(replicate(4, rnorm(100)))
head(estimate_density(df))
\dontrun{
# rstanarm models
# -----------------------------------------------
library(rstanarm)
model <- stan_glm(mpg ~ wt + gear, data = mtcars, chains = 2, iter = 200, refresh = 0)
head(estimate_density(model))
library(emmeans)
head(estimate_density(emtrends(model, ~1, "wt")))
# brms models
# -----------------------------------------------
library(brms)
model <- brms::brm(mpg ~ wt + cyl, data = mtcars)
estimate_density(model)
}
}
\references{
Deng, H., & Wickham, H. (2011). Density estimation in R. Electronic publication.
}
bayestestR/man/bayesfactor_restricted.Rd 0000644 0001762 0000144 00000015145 13616544116 020210 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/bayesfactor_restricted.R
\name{bayesfactor_restricted}
\alias{bayesfactor_restricted}
\alias{bf_restricted}
\alias{bayesfactor_restricted.stanreg}
\alias{bayesfactor_restricted.brmsfit}
\alias{bayesfactor_restricted.emmGrid}
\title{Bayes Factors (BF) for Order Restricted Models}
\usage{
bayesfactor_restricted(
posterior,
hypothesis,
prior = NULL,
verbose = TRUE,
...
)
bf_restricted(posterior, hypothesis, prior = NULL, verbose = TRUE, ...)
\method{bayesfactor_restricted}{stanreg}(
posterior,
hypothesis,
prior = NULL,
verbose = TRUE,
effects = c("fixed", "random", "all"),
component = c("conditional", "zi", "zero_inflated", "all"),
...
)
\method{bayesfactor_restricted}{brmsfit}(
posterior,
hypothesis,
prior = NULL,
verbose = TRUE,
effects = c("fixed", "random", "all"),
component = c("conditional", "zi", "zero_inflated", "all"),
...
)
\method{bayesfactor_restricted}{emmGrid}(
posterior,
hypothesis,
prior = NULL,
verbose = TRUE,
...
)
}
\arguments{
\item{posterior}{A \code{stanreg} / \code{brmsfit} object, \code{emmGrid} or a data frame - representing a posterior distribution(s) from (see Details).}
\item{hypothesis}{A character vector specifying the restrictions as logical conditions (see examples below).}
\item{prior}{An object representing a prior distribution (see Details).}
\item{verbose}{Toggle off warnings.}
\item{...}{Currently not used.}
\item{effects}{Should results for fixed effects, random effects or both be returned?
Only applies to mixed models. May be abbreviated.}
\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.}
}
\value{
A data frame containing the Bayes factor representing evidence \emph{against} the un-restricted model.
}
\description{
This method computes Bayes factors for comparing a model with an order restrictions on its parameters
with the fully unrestricted model. \emph{Note that this method should only be used for confirmatory analyses}.
\cr \cr
The \code{bf_*} function is an alias of the main function.
\cr \cr
\strong{For more info, in particular on specifying correct priors for factors with more than 2 levels, see \href{https://easystats.github.io/bayestestR/articles/bayes_factors.html}{the Bayes factors vignette}.}
}
\details{
This method is used to compute Bayes factors for order-restricted models vs un-restricted
models by setting an order restriction on the prior and posterior distributions
(\cite{Morey & Wagenmakers, 2013}).
\cr\cr
(Though it is possible to use \code{bayesfactor_restricted()} to test interval restrictions,
it is more suitable for testing order restrictions; see examples).
\cr\cr
For the computation of Bayes factors, the model priors must be proper priors (at the very least
they should be \emph{not flat}, and it is preferable that they be \emph{informative}); As the priors for
the alternative get wider, the likelihood of the null value(s) increases, to the extreme that for completely
flat priors the null is infinitely more favorable than the alternative (this is called \emph{the Jeffreys-Lindley-Bartlett
paradox}). Thus, you should only ever try (or want) to compute a Bayes factor when you have an informed prior.
\cr\cr
(Note that by default, \code{brms::brm()} uses flat priors for fixed-effects.)
\subsection{Setting the correct \code{prior}}{
It is important to provide the correct \code{prior} for meaningful results.
\itemize{
\item When \code{posterior} is a \code{data.frame}, \code{prior} should also be a \code{data.frame}, with matching column order.
\item When \code{posterior} is a \code{stanreg} or \code{brmsfit} model: \itemize{
\item \code{prior} can be set to \code{NULL}, in which case prior samples are drawn internally.
\item \code{prior} can also be a model equvilant to \code{posterior} but with samples from the priors \emph{only}.
}
\item When \code{posterior} is an \code{emmGrid} object: \itemize{
\item \code{prior} should be the \code{stanreg} or \code{brmsfit} model used to create the \code{emmGrid} objects.
\item \code{prior} can also be an \code{emmGrid} object equvilant to \code{posterior} but created with a model of priors samples \emph{only}.
}
}}
\subsection{Interpreting Bayes Factors}{
A Bayes factor greater than 1 can be interpereted as evidence against the null,
at which one convention is that a Bayes factor greater than 3 can be considered
as "substantial" evidence against the null (and vice versa, a Bayes factor
smaller than 1/3 indicates substantial evidence in favor of the null-hypothesis)
(\cite{Wetzels et al. 2011}).
}
}
\examples{
library(bayestestR)
prior <- data.frame(
X = rnorm(100),
X1 = rnorm(100),
X3 = rnorm(100)
)
posterior <- data.frame(
X = rnorm(100, .4),
X1 = rnorm(100, -.2),
X3 = rnorm(100)
)
hyps <- c(
"X > X1 & X1 > X3",
"X > X1"
)
bayesfactor_restricted(posterior, hypothesis = hyps, prior = prior)
\dontrun{
# rstanarm models
# ---------------
if (require("rstanarm") && require("emmeans")) {
fit_stan <- stan_glm(mpg ~ wt + cyl + am,
data = mtcars
)
hyps <- c(
"am > 0 & cyl < 0",
"cyl < 0",
"wt - cyl > 0"
)
bayesfactor_restricted(fit_stan, hypothesis = hyps)
# emmGrid objects
# ---------------
# replicating http://bayesfactor.blogspot.com/2015/01/multiple-comparisons-with-bayesfactor-2.html
disgust_data <- read.table(url("http://www.learnbayes.org/disgust_example.txt"), header = TRUE)
contrasts(disgust_data$condition) <- contr.bayes # see vignette
fit_model <- stan_glm(score ~ condition, data = disgust_data, family = gaussian())
em_condition <- emmeans(fit_model, ~condition)
hyps <- c("lemon < control & control < sulfur")
bayesfactor_restricted(em_condition, prior = fit_model, hypothesis = hyps)
# > # Bayes Factor (Order-Restriction)
# >
# > Hypothesis P(Prior) P(Posterior) Bayes Factor
# > lemon < control & control < sulfur 0.17 0.75 4.49
# > ---
# > Bayes factors for the restricted model vs. the un-restricted model.
}
}
}
\references{
\itemize{
\item Morey, R. D., & Wagenmakers, E. J. (2014). Simple relation between Bayesian order-restricted and point-null hypothesis tests. Statistics & Probability Letters, 92, 121-124.
\item Morey, R. D., & Rouder, J. N. (2011). Bayes factor approaches for testing interval null hypotheses. Psychological methods, 16(4), 406.
\item Morey, R. D. (Jan, 2015). Multiple Comparisons with BayesFactor, Part 2 – order restrictions. Retrived from https://richarddmorey.org/category/order-restrictions/.
}
}
bayestestR/man/eti.Rd 0000644 0001762 0000144 00000012231 13616544116 014230 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/eti.R
\name{eti}
\alias{eti}
\alias{eti.numeric}
\alias{eti.data.frame}
\alias{eti.MCMCglmm}
\alias{eti.sim.merMod}
\alias{eti.sim}
\alias{eti.emmGrid}
\alias{eti.stanreg}
\alias{eti.brmsfit}
\alias{eti.BFBayesFactor}
\title{Equal-Tailed Interval (ETI)}
\usage{
eti(x, ...)
\method{eti}{numeric}(x, ci = 0.89, verbose = TRUE, ...)
\method{eti}{data.frame}(x, ci = 0.89, verbose = TRUE, ...)
\method{eti}{MCMCglmm}(x, ci = 0.89, verbose = TRUE, ...)
\method{eti}{sim.merMod}(
x,
ci = 0.89,
effects = c("fixed", "random", "all"),
parameters = NULL,
verbose = TRUE,
...
)
\method{eti}{sim}(x, ci = 0.89, parameters = NULL, verbose = TRUE, ...)
\method{eti}{emmGrid}(x, ci = 0.89, verbose = TRUE, ...)
\method{eti}{stanreg}(
x,
ci = 0.89,
effects = c("fixed", "random", "all"),
parameters = NULL,
verbose = TRUE,
...
)
\method{eti}{brmsfit}(
x,
ci = 0.89,
effects = c("fixed", "random", "all"),
component = c("conditional", "zi", "zero_inflated", "all"),
parameters = NULL,
verbose = TRUE,
...
)
\method{eti}{BFBayesFactor}(x, ci = 0.89, verbose = TRUE, ...)
}
\arguments{
\item{x}{Vector representing a posterior distribution. Can also be a
\code{stanreg}, \code{brmsfit} or a \code{BayesFactor} model.}
\item{...}{Currently not used.}
\item{ci}{Value or vector of probability of the (credible) interval - CI (between 0 and 1)
to be estimated. Default to \code{.89} (89\%).}
\item{verbose}{Toggle off warnings.}
\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.}
}
\value{
A data frame with following columns:
\itemize{
\item \code{Parameter} The model parameter(s), if \code{x} is a model-object. If \code{x} is a vector, this column is missing.
\item \code{CI} The probability of the credible interval.
\item \code{CI_low}, \code{CI_high} The lower and upper credible interval limits for the parameters.
}
}
\description{
Compute the \strong{Equal-Tailed Interval (ETI)} of posterior distributions using the quantiles method. The probability of being below this interval is equal to the probability of being above it. The ETI can be used in the context of uncertainty characterisation of posterior distributions as \strong{Credible Interval (CI)}.
}
\details{
Unlike equal-tailed intervals (see \code{eti()}) that typically exclude 2.5\%
from each tail of the distribution and always include the median, the HDI is
\emph{not} equal-tailed and therefore always includes the mode(s) of posterior
distributions.
\cr \cr
By default, \code{hdi()} and \code{eti()} return the 89\% intervals (\code{ci = 0.89}),
deemed to be more stable than, for instance, 95\% intervals (\cite{Kruschke, 2014}).
An effective sample size of at least 10.000 is recommended if 95\% intervals
should be computed (\cite{Kruschke, 2014, p. 183ff}). Moreover, 89 indicates
the arbitrariness of interval limits - its only remarkable property is being
the highest prime number that does not exceed the already unstable 95\%
threshold (\cite{McElreath, 2015}).
\cr \cr
A 90\% equal-tailed interval (ETI) has 5\% of the distribution on either
side of its limits. It indicates the 5th percentile and the 95h percentile.
In symmetric distributions, the two methods of computing credible intervals,
the ETI and the \link[=hdi]{HDI}, return similar results.
\cr \cr
This is not the case for skewed distributions. Indeed, it is possible that
parameter values in the ETI have lower credibility (are less probable) than
parameter values outside the ETI. This property seems undesirable as a summary
of the credible values in a distribution.
\cr \cr
On the other hand, the ETI range does change when transformations are applied
to the distribution (for instance, for a log odds scale to probabilities):
the lower and higher bounds of the transformed distribution will correspond
to the transformed lower and higher bounds of the original distribution.
On the contrary, applying transformations to the distribution will change
the resulting HDI.
}
\examples{
library(bayestestR)
posterior <- rnorm(1000)
eti(posterior)
eti(posterior, ci = c(.80, .89, .95))
df <- data.frame(replicate(4, rnorm(100)))
eti(df)
eti(df, ci = c(.80, .89, .95))
\dontrun{
library(rstanarm)
model <- stan_glm(mpg ~ wt + gear, data = mtcars, chains = 2, iter = 200, refresh = 0)
eti(model)
eti(model, ci = c(.80, .89, .95))
library(emmeans)
eti(emtrends(model, ~1, "wt"))
library(brms)
model <- brms::brm(mpg ~ wt + cyl, data = mtcars)
eti(model)
eti(model, ci = c(.80, .89, .95))
library(BayesFactor)
bf <- ttestBF(x = rnorm(100, 1, 1))
eti(bf)
eti(bf, ci = c(.80, .89, .95))
}
}
bayestestR/man/bayesfactor_models.Rd 0000644 0001762 0000144 00000013277 13616544116 017327 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/bayesfactor_models.R
\name{bayesfactor_models}
\alias{bayesfactor_models}
\alias{bf_models}
\title{Bayes Factors (BF) for model comparison}
\usage{
bayesfactor_models(..., denominator = 1, verbose = TRUE)
bf_models(..., denominator = 1, verbose = TRUE)
}
\arguments{
\item{...}{Fitted models (see details), all fit on the same data, or a single \code{BFBayesFactor} object (see 'Details').}
\item{denominator}{Either an integer indicating which of the models to use as the denominator,
or a model to be used as a denominator. Ignored for \code{BFBayesFactor}.}
\item{verbose}{Toggle off warnings.}
}
\value{
A data frame containing the models' formulas (reconstructed fixed and random effects) and their BFs, that prints nicely.
}
\description{
This function computes or extracts Bayes factors from fitted models.
\cr \cr
The \code{bf_*} function is an alias of the main function.
}
\details{
If the passed models are supported by \pkg{insight} the DV of all models will be tested for equality
(else this is assumed to be true), and the models' terms will be extracted (allowing for follow-up
analysis with \code{bayesfactor_inclusion}).
\itemize{
\item For \code{brmsfit} or \code{stanreg} models, Bayes factors are computed using the \CRANpkg{bridgesampling} package.
\itemize{
\item \code{brmsfit} models must have been fitted with \code{save_all_pars = TRUE}.
\item \code{stanreg} models must have been fitted with a defined \code{diagnostic_file}.
}
\item For \code{BFBayesFactor}, \code{bayesfactor_models()} is mostly a wraparoud \code{BayesFactor::extractBF()}.
\item For all other model types (supported by \CRANpkg{insight}), BIC approximations are used to compute Bayes factors.
}
In order to correctly and precisely estimate Bayes factors, a rule of thumb are
the 4 P's: \strong{P}roper \strong{P}riors and \strong{P}lentiful \strong{P}osterior
(i.e. probably at leat 40,000 samples instead of the default of 4,000).
\cr \cr
A Bayes factor greater than 1 can be interpereted as evidence against the compared-to
model (the denominator). One convention is that a Bayes factor greater than 3 can be considered
as "substantial" evidence against the denominator model (and vice versa, a Bayes factor
smaller than 1/3 indicates substantial evidence in favor of the denominator model)
(\cite{Wetzels et al. 2011}).
\cr \cr
See also \href{https://easystats.github.io/bayestestR/articles/bayes_factors.html}{the Bayes factors vignette}.
}
\examples{
# With lm objects:
# ----------------
lm1 <- lm(Sepal.Length ~ 1, data = iris)
lm2 <- lm(Sepal.Length ~ Species, data = iris)
lm3 <- lm(Sepal.Length ~ Species + Petal.Length, data = iris)
lm4 <- lm(Sepal.Length ~ Species * Petal.Length, data = iris)
bayesfactor_models(lm1, lm2, lm3, lm4, denominator = 1)
bayesfactor_models(lm2, lm3, lm4, denominator = lm1) # same result
bayesfactor_models(lm1, lm2, lm3, lm4, denominator = lm1) # same result
\dontrun{
# With lmerMod objects:
# ---------------------
if (require("lme4")) {
lmer1 <- lmer(Sepal.Length ~ Petal.Length + (1 | Species), data = iris)
lmer2 <- lmer(Sepal.Length ~ Petal.Length + (Petal.Length | Species), data = iris)
lmer3 <- lmer(
Sepal.Length ~ Petal.Length + (Petal.Length | Species) + (1 | Petal.Width),
data = iris
)
bayesfactor_models(lmer1, lmer2, lmer3, denominator = 1)
bayesfactor_models(lmer1, lmer2, lmer3, denominator = lmer1)
}
# rstanarm models
# ---------------------
# (note that a unique diagnostic_file MUST be specified in order to work)
if (require("rstanarm")) {
stan_m0 <- stan_glm(Sepal.Length ~ 1,
data = iris,
family = gaussian(),
diagnostic_file = file.path(tempdir(), "df0.csv")
)
stan_m1 <- stan_glm(Sepal.Length ~ Species,
data = iris,
family = gaussian(),
diagnostic_file = file.path(tempdir(), "df1.csv")
)
stan_m2 <- stan_glm(Sepal.Length ~ Species + Petal.Length,
data = iris,
family = gaussian(),
diagnostic_file = file.path(tempdir(), "df2.csv")
)
bayesfactor_models(stan_m1, stan_m2, denominator = stan_m0)
}
# brms models
# --------------------
# (note the save_all_pars MUST be set to TRUE in order to work)
if (require("brms")) {
brm1 <- brm(Sepal.Length ~ 1, data = iris, save_all_pars = TRUE)
brm2 <- brm(Sepal.Length ~ Species, data = iris, save_all_pars = TRUE)
brm3 <- brm(
Sepal.Length ~ Species + Petal.Length,
data = iris,
save_all_pars = TRUE
)
bayesfactor_models(brm1, brm2, brm3, denominator = 1)
}
# BayesFactor
# ---------------------------
if (require("BayesFactor")) {
data(puzzles)
BF <- anovaBF(RT ~ shape * color + ID,
data = puzzles,
whichRandom = "ID", progress = FALSE
)
BF
bayesfactor_models(BF) # basically the same
}
}
}
\references{
\itemize{
\item Gronau, Q. F., Wagenmakers, E. J., Heck, D. W., and Matzke, D. (2019). A simple method for comparing complex models: Bayesian model comparison for hierarchical multinomial processing tree models using Warp-III bridge sampling. Psychometrika, 84(1), 261-284.
\item Kass, R. E., and Raftery, A. E. (1995). Bayes Factors. Journal of the American Statistical Association, 90(430), 773-795.
\item Robert, C. P. (2016). The expected demise of the Bayes factor. Journal of Mathematical Psychology, 72, 33–37.
\item Wagenmakers, E. J. (2007). A practical solution to the pervasive problems of p values. Psychonomic bulletin & review, 14(5), 779-804.
\item Wetzels, R., Matzke, D., Lee, M. D., Rouder, J. N., Iverson, G. J., and Wagenmakers, E.-J. (2011). Statistical Evidence in Experimental Psychology: An Empirical Comparison Using 855 t Tests. Perspectives on Psychological Science, 6(3), 291–298. \doi{10.1177/1745691611406923}
}
}
\author{
Mattan S. Ben-Shachar
}
bayestestR/man/figures/ 0000755 0001762 0000144 00000000000 13620150641 014614 5 ustar ligges users bayestestR/man/figures/unnamed-chunk-16-1.png 0000644 0001762 0000144 00000163752 13607554753 020500 0 ustar ligges users PNG
IHDR
. }PLTE : f :: :f : f!333: : f:: :::::f:ff:f:f:::MMMMMnMMMnnMnMnMf f: f::f:ff:ff:ffffffffffnMMnMnnMnnnnnnnnnMMnMnnȎȎ: f:ffffېnMnȫf f::f۶ې۶ȎMȎnȫې:ېf۶f۶۶۶ې۶n䫎Ȏȫ cfȎې۶x xE pHYs E4 E4Ƶ IDATxݎya (;8R < 0A4
ZUs6Z3{ _ _ M # D " v `; A ؎ lG # D " v `; A ؎ lG # D " v `; A ؎ lG # D " v `; A ؎ lG # D "_
[](https://cran.r-project.org/package=bayestestR)
[](https://cran.r-project.org/package=bayestestR)
[](https://travis-ci.org/easystats/bayestestR)
[](https://codecov.io/gh/easystats/bayestestR)
[](https://doi.org/10.21105/joss.01541)
***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](https://doi.org/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](https://doi.org/10.3389/fpsyg.2019.02767)
## Installation
Run the following:
``` r
install.packages(bayestestR)
```
## Documentation
[](https://easystats.github.io/bayestestR/)
[](https://easystats.github.io/blog/posts/)
[](https://easystats.github.io/bayestestR/reference/index.html)
Click on the buttons above to access the package
[**documentation**](https://easystats.github.io/bayestestR/) and the
[**easystats blog**](https://easystats.github.io/blog/posts/), and
check-out these vignettes:
#### Tutorials
- [Get Started with Bayesian
Analysis](https://easystats.github.io/bayestestR/articles/bayestestR.html)
- [Example 1: Initiation to Bayesian
models](https://easystats.github.io/bayestestR/articles/example1.html)
- [Example 2: Confirmation of Bayesian
skills](https://easystats.github.io/bayestestR/articles/example2.html)
- [Example 3: Become a Bayesian
master](https://easystats.github.io/bayestestR/articles/example3.html)
#### Articles
- [Credible Intervals
(CI)](https://easystats.github.io/bayestestR/articles/credible_interval.html)
- [Probability of Direction
(pd)](https://easystats.github.io/bayestestR/articles/probability_of_direction.html)
- [Region of Practical Equivalence
(ROPE)](https://easystats.github.io/bayestestR/articles/region_of_practical_equivalence.html)
- [Bayes Factors
(BF)](https://easystats.github.io/bayestestR/articles/bayes_factors.html)
- [Comparison of
Point-Estimates](https://easystats.github.io/bayestestR/articles/indicesEstimationComparison.html)
- [Comparison of Indices of Effect
Existence](https://easystats.github.io/bayestestR/articles/indicesExistenceComparison.html)
- [Reporting
Guidelines](https://easystats.github.io/bayestestR/articles/guidelines.html)
# Features
In the Bayesian framework, parameters are estimated in a probabilistic
fashion as *distributions*. These distributions can be summarised and
described by **reporting 4 types of indices**:
- [**Centrality**](https://easystats.github.io/bayestestR/articles/indicesEstimationComparison.html)
- `mean()`, `median()` or
[**`map_estimate()`**](https://easystats.github.io/bayestestR/reference/map_estimate.html)
for an estimation of the mode.
- [**`point_estimate()`**](https://easystats.github.io/bayestestR/reference/point_estimate.html)
can be used to get them at once and can be run directly on
models.
- [**Uncertainty**](https://easystats.github.io/bayestestR/articles/credible_interval.html)
- [**`hdi()`**](https://easystats.github.io/bayestestR/reference/hdi.html)
for *Highest Density Intervals (HDI)* or
[**`eti()`**](https://easystats.github.io/bayestestR/reference/eti.html)
for *Equal-Tailed Intervals (ETI)*.
- [**`ci()`**](https://easystats.github.io/bayestestR/reference/ci.html)
can be used as a general method for Confidence and Credible
Intervals (CI).
- [**Effect
Existence**](https://easystats.github.io/bayestestR/articles/indicesExistenceComparison.html):
whether an effect is different from 0.
- [**`p_direction()`**](https://easystats.github.io/bayestestR/reference/p_direction.html)
for a Bayesian equivalent of the frequentist *p*-value (see
[Makowski et
al., 2019](https://doi.org/10.3389/fpsyg.2019.02767))
- [**`p_pointnull()`**](https://easystats.github.io/bayestestR/reference/p_map.html)
represents the odds of null hypothesis (*h0 = 0*) compared to
the most likely hypothesis (the MAP).
- [**`bf_pointnull()`**](https://easystats.github.io/bayestestR/reference/bayesfactor_parameters.html)
for a classic *Bayes Factor (BF)* assessing the likelihood of
effect presence against its absence (*h0 = 0*).
- [**Effect
Significance**](https://easystats.github.io/bayestestR/articles/indicesExistenceComparison.html):
whether the effect size can be considered as non-negligible.
- [**`p_rope()`**](https://easystats.github.io/bayestestR/reference/p_rope.html)
is the probability of the effect falling inside a [*Region of
Practical Equivalence
(ROPE)*](https://easystats.github.io/bayestestR/articles/region_of_practical_equivalence.html).
- [**`bf_rope()`**](https://easystats.github.io/bayestestR/reference/bayesfactor_parameters.html)
computes a Bayes factor against the null as defined by a region
(the ROPE).
- [**`p_significance()`**](https://easystats.github.io/bayestestR/reference/p_significance.html)
that combines a region of equivalence with the probability of
direction.
[**`describe_posterior()`**](https://easystats.github.io/bayestestR/reference/describe_posterior.html)
is the master function with which you can compute all of the indices
cited below at once.
``` r
describe_posterior(
rnorm(1000),
centrality = "median",
test = c("p_direction", "p_significance")
)
## Parameter Median CI CI_low CI_high pd ps
## 1 Posterior -0.047 89 -1.7 1.4 0.52 0.48
```
`describe_posterior()` works for many objects, including more complex
*brmsfit*-models. For better readability, the output is separated by
model components:
``` r
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"
)
```
## # Description of Posterior Distributions
##
## # Fixed Effects (Conditional Model)
##
## Parameter | Median | Mean | MAP | CI | CI_low | CI_high | pd | ps | ESS | Rhat
## ------------------------------------------------------------------------------------------
## Intercept | 1.319 | 1.186 | 1.450 | 89 | 0.049 | 2.275 | 0.940 | 0.920 | 78 | 1.005
## child | -1.162 | -1.162 | -1.175 | 89 | -1.320 | -0.980 | 1.000 | 1.000 | 172 | 0.996
## camper | 0.727 | 0.731 | 0.737 | 89 | 0.587 | 0.858 | 1.000 | 1.000 | 233 | 0.996
##
## # Fixed Effects (Zero-Inflated Model)
##
## Parameter | Median | Mean | MAP | CI | CI_low | CI_high | pd | ps | ESS | Rhat
## ------------------------------------------------------------------------------------------
## Intercept | -0.778 | -0.731 | -0.890 | 89 | -1.893 | 0.218 | 0.876 | 0.840 | 92 | 1.004
## child | 1.888 | 1.882 | 1.906 | 89 | 1.302 | 2.304 | 1.000 | 1.000 | 72 | 1.015
## camper | -0.840 | -0.838 | -0.778 | 89 | -1.337 | -0.231 | 0.992 | 0.988 | 182 | 0.998
##
## # Random Effects (Conditional Model)
##
## Parameter | Median | Mean | MAP | CI | CI_low | CI_high | pd | ps | ESS | Rhat
## ------------------------------------------------------------------------------------------
## persons 1 | -1.315 | -1.233 | -1.397 | 89 | -2.555 | -0.031 | 0.940 | 0.924 | 80 | 1.004
## persons 2 | -0.380 | -0.264 | -0.542 | 89 | -1.451 | 1.008 | 0.660 | 0.632 | 78 | 1.006
## persons 3 | 0.307 | 0.438 | 0.136 | 89 | -0.728 | 1.588 | 0.708 | 0.644 | 77 | 1.003
## persons 4 | 1.207 | 1.331 | 1.030 | 89 | 0.290 | 2.537 | 0.960 | 0.960 | 78 | 1.004
##
## # Random Effects (Zero-Inflated Model)
##
## Parameter | Median | Mean | MAP | CI | CI_low | CI_high | pd | ps | ESS | Rhat
## ------------------------------------------------------------------------------------------
## persons 1 | 1.355 | 1.319 | 1.366 | 89 | 0.368 | 2.659 | 0.956 | 0.952 | 91 | 1.005
## persons 2 | 0.382 | 0.357 | 0.509 | 89 | -0.726 | 1.488 | 0.724 | 0.668 | 99 | 1.000
## persons 3 | -0.117 | -0.142 | -0.103 | 89 | -1.162 | 1.128 | 0.580 | 0.512 | 94 | 0.997
## persons 4 | -1.166 | -1.270 | -1.024 | 89 | -2.462 | -0.061 | 0.972 | 0.960 | 113 | 0.997
*bayestestR* also includes [**many other
features**](https://easystats.github.io/bayestestR/reference/index.html)
useful for your Bayesian analsyes. Here are some more examples:
## Point-estimates
``` r
library(bayestestR)
posterior <- distribution_gamma(10000, 1.5) # Generate a skewed distribution
centrality <- point_estimate(posterior) # Get indices of centrality
centrality
## # Point Estimates
##
## Median | Mean | MAP
## --------------------
## 1.18 | 1.50 | 0.51
```
As for other [**easystats**](https://github.com/easystats) packages,
`plot()` methods are available from the
[**see**](http://easystats.github.io/see) package for many functions:
While the **median** and the **mean** are available through base R
functions,
[**`map_estimate()`**](https://easystats.github.io/bayestestR/reference/map_estimate.html)
in *bayestestR* can be used to directly find the **Highest Maximum A
Posteriori (MAP)** estimate of a posterior, *i.e.*, the value associated
with the highest probability density (the “peak” of the posterior
distribution). In other words, it is an estimation of the *mode* for
continuous parameters.
## Uncertainty (CI)
[**`hdi()`**](https://easystats.github.io/bayestestR/reference/hdi.html)
computes the **Highest Density Interval (HDI)** of a posterior
distribution, i.e., the interval which contains all points within the
interval have a higher probability density than points outside the
interval. The HDI can be used in the context of Bayesian posterior
characterisation as **Credible Interval (CI)**.
Unlike equal-tailed intervals (see
[`eti()`](https://easystats.github.io/bayestestR/reference/eti.html))
that typically exclude 2.5% from each tail of the distribution, the HDI
is *not* equal-tailed and therefore always includes the mode(s) of
posterior distributions.
By default, `hdi()` returns the 89% intervals (`ci = 0.89`), deemed to
be more stable than, for instance, 95% intervals. An effective sample
size of at least 10.000 is recommended if 95% intervals should be
computed (Kruschke, 2015). Moreover, 89 indicates the arbitrariness of
interval limits - its only remarkable property is being the highest
prime number that does not exceed the already unstable 95% threshold
(McElreath, 2018).
``` r
posterior <- distribution_chisquared(100, 3)
hdi(posterior, ci = .89)
## # Highest Density Interval
##
## 89% HDI
## ------------
## [0.11, 6.05]
eti(posterior, ci = .89)
## # Equal-Tailed Interval
##
## 89% ETI
## ------------
## [0.42, 7.27]
```
## Existence and Significance Testing
### Probability of Direction (*pd*)
[**`p_direction()`**](https://easystats.github.io/bayestestR/reference/p_direction.html)
computes the **Probability of Direction** (***p*d**, also known as the
Maximum Probability of Effect - *MPE*). It varies between 50% and 100%
(*i.e.*, `0.5` and `1`) and can be interpreted as the probability
(expressed in percentage) that a parameter (described by its posterior
distribution) is strictly positive or negative (whichever is the most
probable). It is mathematically defined as the proportion of the
posterior distribution that is of the median’s sign. Although
differently expressed, this index is fairly similar (*i.e.*, is strongly
correlated) to the frequentist ***p*-value**.
**Relationship with the p-value**: In most cases, it seems that the *pd*
corresponds to the frequentist one-sided *p*-value through the formula
`p-value = (1-pd/100)` and to the two-sided *p*-value (the most commonly
reported) through the formula `p-value = 2*(1-pd/100)`. Thus, a `pd` of
`95%`, `97.5%` `99.5%` and `99.95%` corresponds approximately to a
two-sided *p*-value of respectively `.1`, `.05`, `.01` and `.001`. See
the [*reporting
guidelines*](https://easystats.github.io/bayestestR/articles/guidelines.html).
``` r
posterior <- distribution_normal(100, 0.4, 0.2)
p_direction(posterior)
## pd = 98.00%
```
### ROPE
[**`rope()`**](https://easystats.github.io/bayestestR/reference/rope.html)
computes the proportion (in percentage) of the HDI (default to the 89%
HDI) of a posterior distribution that lies within a region of practical
equivalence.
Statistically, the probability of a posterior distribution of being
different from 0 does not make much sense (the probability of it being
different from a single point being infinite). Therefore, the idea
underlining ROPE is to let the user define an area around the null value
enclosing values that are *equivalent to the null* value for practical
purposes (Kruschke & Liddell, 2018, p. @kruschke2018rejecting).
Kruschke suggests that such null value could be set, by default, to the
-0.1 to 0.1 range of a standardized parameter (negligible effect size
according to Cohen, 1988). This could be generalized: For instance, for
linear models, the ROPE could be set as `0 +/- .1 * sd(y)`. This ROPE
range can be automatically computed for models using the
[rope\_range](https://easystats.github.io/bayestestR/reference/rope_range.html)
function.
Kruschke suggests using the proportion of the 95% (or 90%, considered
more stable) HDI that falls within the ROPE as an index for
“null-hypothesis” testing (as understood under the Bayesian framework,
see
[equivalence\_test](https://easystats.github.io/bayestestR/reference/equivalence_test.html)).
``` r
posterior <- distribution_normal(100, 0.4, 0.2)
rope(posterior, range = c(-0.1, 0.1))
## # Proportion of samples inside the ROPE [-0.10, 0.10]:
##
## inside ROPE
## -----------
## 1.11 %
```
### Bayes Factor
[**`bayesfactor_parameters()`**](https://easystats.github.io/bayestestR/reference/bayesfactor_parameters.html)
computes Bayes factors against the null (either a point or an interval),
bases on prior and posterior samples of a single parameter. This Bayes
factor indicates the degree by which the mass of the posterior
distribution has shifted further away from or closer to the null
value(s) (relative to the prior distribution), thus indicating if the
null value has become less or more likely given the observed data.
When the null is an interval, the Bayes factor is computed by comparing
the prior and posterior odds of the parameter falling within or outside
the null; When the null is a point, a Savage-Dickey density ratio is
computed, which is also an approximation of a Bayes factor comparing the
marginal likelihoods of the model against a model in which the tested
parameter has been restricted to the point null (Wagenmakers, Lodewyckx,
Kuriyal, & Grasman, 2010).
``` r
prior <- rnorm(1000, mean = 0, sd = 1)
posterior <- rnorm(1000, mean = 1, sd = 0.7)
bayesfactor_parameters(posterior, prior, direction = "two-sided", null = 0)
## # Bayes Factor (Savage-Dickey density ratio)
##
## BF
## ----
## 2.03
##
## * Evidence Against The Null: [0]
```
*The lollipops represent the density of a point-null on the prior
distribution (the blue lollipop on the dotted distribution) and on the
posterior distribution (the red lollipop on the yellow distribution).
The ratio between the two - the Savage-Dickey ratio - indicates the
degree by which the mass of the parameter distribution has shifted away
from or closer to the null.*
For more info, see [the Bayes factors
vignette](https://easystats.github.io/bayestestR/articles/bayes_factors.html).
## Utilities
### Find ROPE’s appropriate range
[**`rope_range()`**](https://easystats.github.io/bayestestR/reference/rope_range.html):
This function attempts at automatically finding suitable “default”
values for the Region Of Practical Equivalence (ROPE). Kruschke (2018)
suggests that such null value could be set, by default, to a range from
`-0.1` to `0.1` of a standardized parameter (negligible effect size
according to Cohen, 1988), which can be generalised for linear models to
`-0.1 * sd(y), 0.1 * sd(y)`. For logistic models, the parameters
expressed in log odds ratio can be converted to standardized difference
through the formula `sqrt(3)/pi`, resulting in a range of `-0.05` to
`0.05`.
``` r
rope_range(model)
```
### Density Estimation
[**`estimate_density()`**](https://easystats.github.io/bayestestR/reference/estimate_density.html):
This function is a wrapper over different methods of density estimation.
By default, it uses the base R `density` with by default uses a
different smoothing bandwidth (`"SJ"`) from the legacy default
implemented the base R `density` function (`"nrd0"`). However, Deng &
Wickham suggest that `method = "KernSmooth"` is the fastest and the most
accurate.
### Perfect Distributions
[**`distribution()`**](https://easystats.github.io/bayestestR/reference/distribution.html):
Generate a sample of size n with near-perfect distributions.
``` r
distribution(n = 10)
## [1] -1.28 -0.88 -0.59 -0.34 -0.11 0.11 0.34 0.59 0.88 1.28
```
### Probability of a Value
[**`density_at()`**](https://easystats.github.io/bayestestR/reference/density_at.html):
Compute the density of a given point of a distribution.
``` r
density_at(rnorm(1000, 1, 1), 1)
## [1] 0.39
```
# References