% 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.blavaan}
\alias{bayesfactor_restricted.emmGrid}
\alias{bayesfactor_restricted.matrix}
\alias{bayesfactor_restricted.data.frame}
\title{Bayes Factors (BF) for Order Restricted Models}
\usage{
bayesfactor_restricted(posterior, ...)

bf_restricted(posterior, ...)

\method{bayesfactor_restricted}{stanreg}(
  posterior,
  hypothesis,
  prior = NULL,
  verbose = TRUE,
  effects = "fixed",
  component = "conditional",
  ...
)

\method{bayesfactor_restricted}{brmsfit}(
  posterior,
  hypothesis,
  prior = NULL,
  verbose = TRUE,
  effects = "fixed",
  component = "conditional",
  ...
)

\method{bayesfactor_restricted}{blavaan}(
  posterior,
  hypothesis,
  prior = NULL,
  verbose = TRUE,
  ...
)

\method{bayesfactor_restricted}{emmGrid}(
  posterior,
  hypothesis,
  prior = NULL,
  verbose = TRUE,
  ...
)

\method{bayesfactor_restricted}{matrix}(
  posterior,
  hypothesis,
  prior = NULL,
  verbose = TRUE,
  ...
)

\method{bayesfactor_restricted}{data.frame}(
  posterior,
  hypothesis,
  prior = NULL,
  rvar_col = NULL,
  ...
)
}
\arguments{
\item{posterior}{A \code{stanreg} / \code{brmsfit} object, \code{emmGrid} or a data frame - representing
a posterior distribution(s) from (see Details).}

\item{...}{Currently not used.}

\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{effects}{Should variables for fixed effects (\code{"fixed"}), random effects
(\code{"random"}) or both (\code{"all"}) be returned? Only applies to mixed models. May
be abbreviated.

For models of from packages \strong{brms} or \strong{rstanarm} there are additional
options:
\itemize{
\item \code{"fixed"} returns fixed effects.
\item \code{"random_variance"} return random effects parameters (variance and
correlation components, e.g. those parameters that start with \code{sd_} or
\code{cor_}).
\item \code{"grouplevel"} returns random effects group level estimates, i.e. those
parameters that start with \code{r_}.
\item \code{"random"} returns both \code{"random_variance"} and \code{"grouplevel"}.
\item \code{"all"} returns fixed effects and random effects variances.
\item \code{"full"} returns all parameters.
}}

\item{component}{Which type of parameters to return, such as parameters for
the conditional model, the zero-inflated part of the model, the dispersion
term, etc. See details in section \emph{Model Components}. May be abbreviated.
Note that the \emph{conditional} component also refers to the \emph{count} or \emph{mean}
component - names may differ, depending on the modeling package. There are
three convenient shortcuts (not applicable to \emph{all} model classes):
\itemize{
\item \code{component = "all"} returns all possible parameters.
\item If \code{component = "location"}, location parameters such as \code{conditional},
\code{zero_inflated}, \code{smooth_terms}, or \code{instruments} are returned (everything
that are fixed or random effects - depending on the \code{effects} argument -
but no auxiliary parameters).
\item For \code{component = "distributional"} (or \code{"auxiliary"}), components like
\code{sigma}, \code{dispersion}, \code{beta} or \code{precision} (and other auxiliary
parameters) are returned.
}}

\item{rvar_col}{A single character - the name of an \code{rvar} column in the data
frame to be processed. See example in \code{\link[=p_direction]{p_direction()}}.}
}
\value{
A data frame containing the (log) Bayes factor representing evidence
\emph{against} the un-restricted model (Use \code{as.numeric()} to extract the
non-log Bayes factors; see examples). (A \code{bool_results} attribute contains
the results for each sample, indicating if they are included or not in the
hypothesized restriction.)
}
\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 \verb{bf_*} function is an alias of the main function.
\cr \cr
\strong{For more info, 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).
\subsection{Additional methods}{

The resulting output is supported by the following methods:
\itemize{
\item \code{as.matrix()}: Extract a full matrix of (log-)Bayes factors between all
models (using the transitivity of Bayes factors).
\item \code{as.logical()}: Extract boolean vectors indicating which (prior/posterior)
samples are included in the hypothesized restriction.
\item \code{as.numeric()}: Extract the (possibly log-)Bayes factor values.
}

See examples and \link{bayesfactor_methods}.
}
}
\section{Obtaining prior samples}{


It is important to provide the correct \code{prior} for meaningful results,
to match the \code{posterior}-type input:
\itemize{
\item \strong{A numeric vector} - \code{prior} should also be a \emph{numeric vector}, representing the prior-distribution
\item \strong{A data frame} - \code{prior} should also be a \emph{data frame}, representing the prior-estimates, in matching column order.
\itemize{
\item If \code{rvar_col} is specified, \code{prior} should be \emph{the name of an \code{rvar} column} that represents the prior-estimates.
}
\item \strong{Supported Bayesian model (\code{stanreg}, \code{brmsfit}, etc.)}
\itemize{
\item \code{prior} should be \emph{a model an equivalent model with MCMC samples from the priors \strong{only}}. See \code{\link[=unupdate]{unupdate()}}.
\item If \code{prior} is set to \code{NULL}, \code{\link[=unupdate]{unupdate()}} is called internally (not supported for \code{brmsfit_multiple} model).
}
\item \strong{Output from a \code{{marginaleffects}} function} - \code{prior} should also be \emph{an equivalent output} from a \code{{marginaleffects}} function based on a prior-model
(See \code{\link[=unupdate]{unupdate()}}).
\item \strong{Output from an \code{{emmeans}} function}
\itemize{
\item \code{prior} should also be \emph{an equivalent output} from an \code{{emmeans}} function based on a prior-model (See \code{\link[=unupdate]{unupdate()}}).
\item \code{prior} can also be \emph{the original (posterior) model}, in which case the function
will try to "unupdate" the estimates (not supported if the estimates have undergone
any transformations -- \code{"log"}, \code{"response"}, etc. -- or any \code{regrid}ing).
}
}
}

\section{Transitivity of Bayes factors}{

For multiple inputs (models or hypotheses), the function will return multiple
Bayes factors between each model and \emph{the same} reference model (the
\code{denominator} or un-restricted model). However, we can take advantage of the
transitivity of Bayes factors - where if we have two Bayes factors for Model
\emph{A} and model \emph{B} against the \emph{same reference model C}, we can obtain a Bayes
factor for comparing model \emph{A} to model \emph{B} by dividing them:
\cr\cr
\deqn{BF_{AB} = \frac{BF_{AC}}{BF_{BC}} = \frac{\frac{ML_{A}}{ML_{C}}}{\frac{ML_{B}}{ML_{C}}} = \frac{ML_{A}}{ML_{B}}}
\cr\cr
(Where \emph{ML} is the \emph{marginal likelihood}.)
\cr\cr
A full matrix comparing all models can be obtained with \code{as.matrix()}.
}

\section{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
null-model). See also \code{effectsize::interpret_bf()}.
}

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

# See the matrix of BFs
as.matrix(b)

bool <- as.logical(b, which = "posterior")
head(bool)

\dontshow{if (require("see") && require("patchwork")) withAutoprint(\{ # examplesIf}

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"
)
\dontshow{\}) # examplesIf}
\dontshow{if (require("rstanarm")) withAutoprint(\{ # examplesIf}
\donttest{
# 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)
}
\dontshow{\}) # examplesIf}
\dontshow{if (require("rstanarm") && require("emmeans")) withAutoprint(\{ # examplesIf}
\donttest{
# emmGrid objects
# ---------------
# replicating http://bayesfactor.blogspot.com/2015/01/multiple-comparisons-with-bayesfactor-2.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 (Order-Restriction)
# >
# >                          Hypothesis P(Prior) P(Posterior)   BF
# >  lemon < control & control < sulfur     0.17         0.75 4.49
# > ---
# > Bayes factors for the restricted model vs. the un-restricted model.
}
\dontshow{\}) # examplesIf}
}
\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.
Retrieved from https://richarddmorey.org/category/order-restrictions/.
}
}
\seealso{
Other Bayes factors: 
\code{\link{bayesfactor_inclusion}()},
\code{\link{bayesfactor_models}()},
\code{\link{bayesfactor_parameters}()}
}
\concept{Bayes factors}
