% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/compute_V_S_star.R
\name{compute_V_S_star}
\alias{compute_V_S_star}
\title{Compute \eqn{v_S} from Carlotti and Parast (2026)}
\usage{
compute_V_S_star(
  n,
  alpha = 0.05,
  beta = 0.2,
  V_S_zero = 0.5,
  a = 1,
  b = 1,
  BF_alternative = "greater",
  root_tolerance = 1e-16
)
}
\arguments{
\item{n}{Integer. Sample size.}

\item{alpha}{Numeric. Type I error rate (default is 0.05).}

\item{beta}{Numeric. Type II error rate (default is 0.2).}

\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"}.}

\item{root_tolerance}{Numeric. Tolerance level for the root-finding algorithm (default is 1e-16).}
}
\value{
A list containing:
\itemize{
  \item \code{BF_alpha}: The critical value of the Bayes factor corresponding to the specified alpha level.
  \item \code{V_S_star}: The value of \eqn{v_S} that satisfies the power constraint for the surrogate validation test.
}
}
\description{
This function determines the value \eqn{v_S} that is used to compute the
surrogate validation threshold \eqn{\eta} from \insertCite{carlotti2026bayesian;textual}{BSET}:
\deqn{\eta = \max \{v_Y - v_S, 0\},}
where \eqn{v_Y} is the hypothesized value of the treatment effect on the
primary outcome (typically set equal to the estimate computed on the
available data) and \eqn{v_S} is the value that satisfies the following power
constraint:
\deqn{P(\text{BF}_n \geq \text{BF}_{n, \alpha} \; | \; V_S = v_S) = 1 - \beta,}
where \eqn{\text{BF}_{n, \alpha}} is the \eqn{(1 - \alpha)} quantile of the
Bayes factor distribution under the null hypothesis \eqn{V_S = V^0_{S}}, and \eqn{1 - \beta} is the desired power of the
test. The function computes the distribution of the Bayes factor under the null
hypothesis, derives the critical value \eqn{\text{BF}_{n, \alpha}}, and then
uses a root-finding algorithm to solve for the value of \eqn{v_S} that
satisfies the power constraint.
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}
}
