% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/compute_BF_distribution.R
\name{compute_BF_distribution}
\alias{compute_BF_distribution}
\title{Compute the Distribution of the Bayes Factor from Carlotti and Parast (2026)}
\usage{
compute_BF_distribution(
  n,
  V_S_true,
  V_S_zero = 0.5,
  a = 1,
  b = 1,
  BF_alternative
)
}
\arguments{
\item{n}{Integer. The sample size.}

\item{V_S_true}{Numeric. The true value of treatment effect on the surrogate.}

\item{V_S_zero}{Numeric. The hypothesized value of the surrogate's treatment effect under the null hypothesis (default is 0.5).}

\item{a}{Numeric. First shape parameter alpha for the Beta prior (default is 1).}

\item{b}{Numeric. Second shape parameter beta for the Beta prior (default is 1).}

\item{BF_alternative}{Character. The type of alternative hypothesis: either \code{"two_sided"} or \code{"greater"}.}
}
\value{
A data frame containing:
\itemize{
  \item \code{BF_values}: The possible values of the Bayes Factor.
  \item \code{BF_PMF}: The probability mass function for the Bayes Factor.
  \item \code{BF_CDF}: The cumulative distribution function for the Bayes Factor.
}
}
\description{
This function calculates the probability mass function and cumulative distribution 
function of the Bayes factor defined in \insertCite{carlotti2026bayesian;textual}{BSET} for the
following hypothesis test:
\deqn{\begin{cases}
H_0: V_S = V_S^{0} \\
H_1: V_S > V_S^{0}
\end{cases}}
where \eqn{V_S} is the surrogate's treatment effect on \eqn{S} measured as
the probability
\deqn{V_S = P(S_{1i} > S_{0i})}
and \eqn{V_S^{0}} is a hypothesized value under the null hypothesis. These
hypotheses can be tested by fitting the following Beta-binomial model to the
data:
\deqn{\hat{V}_S \mid V_S \sim \text{Binomial} (n, V_S)}
\deqn{p(V_S) = \frac{\text{Beta}(V_S \mid a, b)}{\int_{1/2}^{1} \text{Beta}(v \mid a, b) \, dv}, \quad V_S \in \left(\tfrac{1}{2}, 1\right),}
where \eqn{\hat{V}_S} is the sample estimate of the surrogate's treatment
effect on \eqn{S} computed as
\deqn{\hat{V}_S = \frac{1}{n} \sum\limits^{n}_{i=1} I(S_{1i} > S_{0i}).}
The Bayes factor is then computed as the ratio of the marginal likelihoods
under the alternatives:
\deqn{BF_{n} = \frac{B(a + n \hat{V}_S,\, b + n - n \hat{V}_S) \left(1 - F_{\text{Beta}(a + n \hat{V}_S,\, b + n - n \hat{V}_S)}\!\left(\frac{1}{2}\right)\right)}{B(a, b) \left(1 - F_{\text{Beta}(a, b)}\!\left(\frac{1}{2}\right)\right)} \cdot 2^n,}
where \eqn{B(a, b)} is the Beta function, \eqn{F_{\text{Beta}(a,b)}} is the
cumulative distribution function of the \eqn{\text{Beta}(a, b)} distribution,
and \eqn{a} and \eqn{b} are the shape parameters of the Beta prior.
Given the true value of \eqn{V_S}, the distribution of the Bayes factor can
be computed by evaluating \eqn{BF_n} for all possible values of
\eqn{\hat{V}_S} and their corresponding probabilities under the Binomial
distribution with parameters \eqn{n} and the true value of \eqn{V_S}.
This function is generally not intended to be called directly by the user
and is instead used internally within \code{BSET_no_X} and \code{BSET_X}.
}
\references{
\insertRef{carlotti2026bayesian}{BSET}
}
