bayesfactor_restricted {bayestestR}  R Documentation 
Bayes Factors (BF) for Order Restricted Models
Description
This method computes Bayes factors for comparing a model with an order restrictions on its parameters
with the fully unrestricted model. Note that this method should only be used for confirmatory analyses.
The bf_*
function is an alias of the main function.
For more info, in particular on specifying correct priors for factors with more than 2 levels,
see the Bayes factors vignette.
Usage
bayesfactor_restricted(
posterior,
hypothesis,
prior = NULL,
verbose = TRUE,
...
)
bf_restricted(posterior, hypothesis, prior = NULL, verbose = TRUE, ...)
## S3 method for class 'stanreg'
bayesfactor_restricted(
posterior,
hypothesis,
prior = NULL,
verbose = TRUE,
effects = c("fixed", "random", "all"),
component = c("conditional", "zi", "zero_inflated", "all"),
...
)
## S3 method for class 'brmsfit'
bayesfactor_restricted(
posterior,
hypothesis,
prior = NULL,
verbose = TRUE,
effects = c("fixed", "random", "all"),
component = c("conditional", "zi", "zero_inflated", "all"),
...
)
## S3 method for class 'blavaan'
bayesfactor_restricted(
posterior,
hypothesis,
prior = NULL,
verbose = TRUE,
...
)
## S3 method for class 'emmGrid'
bayesfactor_restricted(
posterior,
hypothesis,
prior = NULL,
verbose = TRUE,
...
)
## S3 method for class 'bayesfactor_restricted'
as.logical(x, which = c("posterior", "prior"), ...)
Arguments
posterior 
A 
hypothesis 
A character vector specifying the restrictions as logical conditions (see examples below). 
prior 
An object representing a prior distribution (see Details). 
verbose 
Toggle off warnings. 
... 
Currently not used. 
effects 
Should results for fixed effects, random effects or both be returned? Only applies to mixed models. May be abbreviated. 
component 
Should results for all parameters, parameters for the conditional model or the zeroinflated part of the model be returned? May be abbreviated. Only applies to brmsmodels. 
x 
An object of class 
which 
Should the logical matrix be of the posterior or prior distribution(s)? 
Details
This method is used to compute Bayes factors for orderrestricted models vs unrestricted
models by setting an order restriction on the prior and posterior distributions
(Morey & Wagenmakers, 2013).
(Though it is possible to use bayesfactor_restricted()
to test interval restrictions,
it is more suitable for testing order restrictions; see examples).
Value
A data frame containing the (log) Bayes factor representing evidence
against the unrestricted model (Use as.numeric()
to extract the
nonlog Bayes factors; see examples). (A bool_results
attribute contains
the results for each sample, indicating if they are included or not in the
hypothesized restriction.)
Setting the correct prior
For the computation of Bayes factors, the model priors must be proper priors
(at the very least they should be not flat, and it is preferable that
they be 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 the JeffreysLindleyBartlett paradox). Thus, you should
only ever try (or want) to compute a Bayes factor when you have an informed
prior.
(Note that by default, brms::brm()
uses flat priors for fixedeffects;
See example below.)
It is important to provide the correct prior
for meaningful results.
When
posterior
is a numerical vector,prior
should also be a numerical vector.When
posterior
is adata.frame
,prior
should also be adata.frame
, with matching column order.When
posterior
is astanreg
,brmsfit
or other supported Bayesian model:
prior
can be set toNULL
, in which case prior samples are drawn internally. 
prior
can also be a model equivalent toposterior
but with samples from the priors only. Seeunupdate()
. 
Note: When
posterior
is abrmsfit_multiple
model,prior
must be provided.

When
posterior
is anemmGrid
/emm_list
object:
prior
should also be anemmGrid
/emm_list
object equivalent toposterior
but created with a model of priors samples only. Seeunupdate()
. 
prior
can also be the original (posterior) model. If so, the function will try to update theemmGrid
/emm_list
to use theunupdate()
d priormodel. (This cannot be done forbrmsfit
models.) 
Note: When the
emmGrid
has undergone any transformations ("log"
,"response"
, etc.), orregrid
ing, thenprior
must be anemmGrid
object, as stated above.

Interpreting Bayes Factors
A Bayes factor greater than 1 can be interpreted 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 nullmodel) (Wetzels et al. 2011).
References
Morey, R. D., & Wagenmakers, E. J. (2014). Simple relation between Bayesian orderrestricted and pointnull hypothesis tests. Statistics & Probability Letters, 92, 121124.
Morey, R. D., & Rouder, J. N. (2011). Bayes factor approaches for testing interval null hypotheses. Psychological methods, 16(4), 406.
Morey, R. D. (Jan, 2015). Multiple Comparisons with BayesFactor, Part 2 – order restrictions. Retrieved from https://richarddmorey.org/category/orderrestrictions/.
Examples
set.seed(444)
library(bayestestR)
prior < data.frame(
A = rnorm(500),
B = rnorm(500),
C = rnorm(500)
)
posterior < data.frame(
A = rnorm(500, .4, 0.7),
B = rnorm(500, .2, 0.4),
C = rnorm(500, 0, 0.5)
)
hyps < c(
"A > B & B > C",
"A > B & A > C",
"C > A"
)
(b < bayesfactor_restricted(posterior, hypothesis = hyps, prior = prior))
bool < as.logical(b, which = "posterior")
head(bool)
see::plots(
plot(estimate_density(posterior)),
# distribution **conditional** on the restrictions
plot(estimate_density(posterior[bool[, hyps[1]], ])) + ggplot2::ggtitle(hyps[1]),
plot(estimate_density(posterior[bool[, hyps[2]], ])) + ggplot2::ggtitle(hyps[2]),
plot(estimate_density(posterior[bool[, hyps[3]], ])) + ggplot2::ggtitle(hyps[3]),
guides = "collect"
)
# rstanarm models
# 
data("mtcars")
fit_stan < rstanarm::stan_glm(mpg ~ wt + cyl + am,
data = mtcars, refresh = 0
)
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/multiplecomparisonswithbayesfactor2.html
data("disgust")
contrasts(disgust$condition) < contr.equalprior_pairs # see vignette
fit_model < rstanarm::stan_glm(score ~ condition, data = disgust, family = gaussian())
em_condition < emmeans::emmeans(fit_model, ~condition, data = disgust)
hyps < c("lemon < control & control < sulfur")
bayesfactor_restricted(em_condition, prior = fit_model, hypothesis = hyps)
# > # Bayes Factor (OrderRestriction)
# >
# > Hypothesis P(Prior) P(Posterior) BF
# > lemon < control & control < sulfur 0.17 0.75 4.49
# > 
# > Bayes factors for the restricted model vs. the unrestricted model.