% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/brmsfit-methods.R, R/generics.R, R/misc-methods.R, R/plots.R
\name{hypothesis.brmsfit}
\alias{hypothesis}
\alias{hypothesis.brmsfit}
\alias{plot.brmshypothesis}
\alias{print.brmshypothesis}
\title{Non-linear hypothesis testing}
\usage{
\method{hypothesis}{brmsfit}(x, hypothesis, class = "b", group = "",
  alpha = 0.05, ...)

hypothesis(x, hypothesis, ...)

\method{print}{brmshypothesis}(x, digits = 2, chars = 20, ...)

\method{plot}{brmshypothesis}(x, N = 5, ignore_prior = FALSE,
  theme = ggplot2::theme(), ask = TRUE, plot = TRUE, chars = 20, ...)
}
\arguments{
\item{x}{An \code{R} object typically of class \code{brmsfit}.}

\item{hypothesis}{A character vector specifying one or more 
non-linear hypothesis concerning parameters of the model.}

\item{class}{A string specifying the class of parameters being tested. 
Default is "b" for population-level effects. 
Other typical options are "sd" or "cor". 
If \code{class = NULL}, all parameters can be tested
against each other, but have to be specified with their full name 
(see also \code{\link[brms:parnames]{parnames}})}

\item{group}{Name of a grouping factor to evaluate only 
group-level effects parameters related to this grouping factor.
Ignored if \code{class} is not \code{"sd"} or \code{"cor"}.}

\item{alpha}{The alpha-level of the tests (default is 0.05).}

\item{...}{Currently ignored.}

\item{digits}{Minimal number of significant digits, 
see \code{\link[base:print.default]{print.default}}.}

\item{chars}{Maximum number of characters of each hypothesis
to print or plot. If \code{NULL}, print the full hypotheses.
Defaults to \code{20}.}

\item{N}{The number of parameters plotted per page.}

\item{ignore_prior}{A flag indicating if prior distributions 
should also be plotted. Only used if priors were specified on
the relevant parameters.}

\item{theme}{A \code{\link[ggplot2:theme]{theme}} object 
modifying the appearance of the plots. 
For some basic themes see \code{\link[ggplot2:ggtheme]{ggtheme}}. 
Can be defined globally for the current session, via
\code{\link[ggplot2:theme_update]{theme_set}}.}

\item{ask}{logical; indicates if the user is prompted 
before a new page is plotted. 
Only used if \code{plot} is \code{TRUE}.}

\item{plot}{logical; indicates if plots should be
plotted directly in the active graphic device.
Defaults to \code{TRUE}.}
}
\value{
Summary statistics of the posterior distributions 
 related to the hypotheses.
}
\description{
Perform non-linear hypothesis testing for all model parameters.
}
\details{
Among others, \code{hypothesis} computes an 
 evidence ratio (\code{Evid.Ratio}) for each hypothesis. 
 For a directed hypothesis, this is just the posterior probability 
 under the hypothesis against its alternative.
 For an undirected (i.e. point) hypothesis the evidence ratio 
 is a Bayes factor between the hypothesis and its alternative.
 In order to calculate this Bayes factor, all parameters related 
 to the hypothesis must have proper priors
 and argument \code{sample_prior} of function \code{brm} 
 must be set to \code{TRUE}. 
 When interpreting Bayes factors, make sure 
 that your priors are reasonable and carefully chosen,
 as the result will depend heavily on the priors. 
 It particular, avoid using default priors.
}
\examples{
\dontrun{
## define priors
prior <- c(set_prior("normal(0,2)", class = "b"),
           set_prior("student_t(10,0,1)", class = "sigma"),
           set_prior("student_t(10,0,1)", class = "sd"))

## fit a linear mixed effects models
fit <- brm(time ~ age + sex + disease + (1 + age|patient),
           data = kidney, family = lognormal(),
           prior = prior, sample_prior = TRUE, 
           control = list(adapt_delta = 0.95))

## perform two-sided hypothesis testing
(hyp1 <- hypothesis(fit, "sexfemale = age + diseasePKD"))
plot(hyp1)
hypothesis(fit, "exp(age) - 3 = 0", alpha = 0.01)

## perform one-sided hypothesis testing
hypothesis(fit, "diseasePKD + diseaseGN - 3 < 0")

hypothesis(fit, "age < Intercept", 
           class = "sd", group  = "patient")

## test the amount of random intercept variance on all variance
h <- paste("sd_patient_Intercept^2 / (sd_patient_Intercept^2 +",
           "sd_patient_age^2 + sigma^2) = 0")
(hyp2 <- hypothesis(fit, h, class = NULL))
plot(hyp2)

## test more than one hypothesis at once
(hyp3 <- hypothesis(fit, c("diseaseGN = diseaseAN", 
                           "2 * diseaseGN - diseasePKD = 0")))
plot(hyp3, ignore_prior = TRUE)
}

}
\author{
Paul-Christian Buerkner \email{paul.buerkner@gmail.com}
}

