% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/bayesfactor-methods.R
\name{bayesfactor_methods}
\alias{bayesfactor_methods}
\alias{as.matrix.bayestestRBF}
\alias{update.bayesfactor_models}
\alias{as.numeric.bayestestRBF}
\alias{as.logical.bayesfactor_restricted}
\title{Methods for Bayes factors}
\usage{
\method{as.matrix}{bayestestRBF}(x, log = TRUE, ...)

\method{update}{bayesfactor_models}(object, subset = NULL, reference = NULL, ...)

\method{as.numeric}{bayestestRBF}(x, log = FALSE, ...)

\method{as.logical}{bayesfactor_restricted}(x, which = c("posterior", "prior"), ...)
}
\arguments{
\item{x, object}{Bayes factor object}

\item{log}{Return log(BF) (default), or BF values.}

\item{...}{Additional arguments (currently not used).}

\item{subset}{Vector of model indices to keep or remove.}

\item{reference}{Index of model to reference to, or \code{"top"} to
reference to the best model, or \code{"bottom"} to reference to the worst
model.}

\item{which}{Should the logical matrix be of the posterior or prior distribution(s)?}
}
\value{
\itemize{
\item \code{as.numeric()} / \code{as.double()}: a numeric vector of (log)
Bayes factors.
\item \code{as.logical()}: a logical data frame with a column for each
order-restricted hypothesis.
\item \code{as.matrix()}: a square matrix of (log) Bayes factors, with rows as
denominators and columns as numerators.
\item \code{update()}: an updated \code{bayesfactor_models} object.
}
}
\description{
Methods for Bayes factors
}
\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()}.
}

\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{Prior and posterior considerations}{

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}osteriors.
\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}) (Note that by default, \code{brms::brm()} uses flat priors for
fixed-effects); Wide priors result in smaller marginal likelihoods, and thus
models with wider priors are trivially less likely than models with narrower
priors - where, at the extreme, that a model with completely flat priors is
infinitely less favorable than a point null model (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
Additionally, for models using MCMC estimation the number of posterior
samples needed for testing is substantially larger than for estimation (the
default of 4000 samples may not be enough in many cases). A conservative rule
of thumb is to obtain 10 times more samples than would be required for
estimation (\emph{Gronau, Singmann, & Wagenmakers, 2017}). If less than 40,000
samples are detected, a warning is issued.
}

