% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hypothesis.R
\name{hypothesis}
\alias{hypothesis}
\title{Test hypotheses and compute evidence ratios from posterior draws}
\usage{
hypothesis(object, hypotheses, ci = 0.95, ...)
}
\arguments{
\item{object}{A \code{smoothbp_fit} object.}

\item{hypotheses}{A character vector of hypothesis strings.}

\item{ci}{Width of the credible interval (0 < ci < 1). Default 0.95.}

\item{...}{Unused.}
}
\value{
An object of class \code{c("smoothbp_hypothesis", "data.frame")}
with one row per hypothesis and columns:
\describe{
\item{\code{Hypothesis}}{The original hypothesis string.}
\item{\code{Estimate}}{Posterior mean of the contrast.}
\item{\code{Est.Error}}{Posterior SD of the contrast.}
\item{\code{CI.lower}, \code{CI.upper}}{Credible interval bounds.}
\item{\code{P(H)}}{Posterior probability of the hypothesis.}
\item{\code{Evid.Ratio}}{Evidence ratio \eqn{P(H)/(1-P(H))}.}
\item{\code{Star}}{Informal star coding based on the evidence ratio.}
}
}
\description{
Evaluates one or more hypothesis expressions against the posterior draws of
a \code{smoothbp_fit} object, returning posterior probabilities and evidence
ratios.
}
\section{Hypothesis syntax}{


Write hypotheses as character strings using exact parameter names as they
appear in \code{fit$param_names} (e.g. \code{"b2_(Intercept)"},
\code{"omega_(Intercept)"}). No backtick-quoting is needed; the function
handles special characters internally.

Two forms are accepted:

\describe{
\item{Directional}{An expression containing \code{>}, \code{<},
\code{>=}, or \code{<=}.  The hypothesis is evaluated as a contrast:
the left-hand side minus the right-hand side (direction-adjusted), and
\eqn{P(H \mid \text{data})} is the proportion of posterior draws
satisfying the condition.
Examples: \code{"b2_(Intercept) > 0"},
\code{"omega_(Intercept) < 4"},
\code{"b2_(Intercept) - b1_(Intercept) > 0"}.}
\item{Contrast}{A numeric expression without a comparison operator.  The
function summarises the posterior distribution of the derived quantity
and reports \eqn{P(\text{expression} > 0)} as the directional
probability.
Example: \code{"b2_(Intercept) - b1_(Intercept)"}.}
}

Point-null hypotheses (\code{==}) are not supported because they require
the Savage-Dickey density ratio; use \code{bayestestR::rope()} for
interval-based equivalence testing instead.
}

\section{Evidence ratio interpretation}{


\deqn{ER = \frac{P(H \mid \text{data})}{1 - P(H \mid \text{data})}}

An ER of 19 corresponds to \eqn{P(H) = 0.95}; ER = 1 means the posterior
is equally split.  Star codes: \code{***} ER > 99, \code{**} ER > 19,
\code{*} ER > 3.
}

\examples{
\dontrun{
# Is the change in slope positive?
hypothesis(fit, "b2_(Intercept) > 0")

# Does the change-point fall before time 4?
hypothesis(fit, "omega_(Intercept) < 4")

# Multiple hypotheses at once
hypothesis(fit, c(
  "b2_(Intercept) > 0",
  "omega_(Intercept) < 4",
  "b2_(Intercept) - b1_(Intercept) > 0"
))

# Posterior summary of a contrast (no comparison operator)
hypothesis(fit, "b2_(Intercept) - b1_(Intercept)")
}

}
