% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/calibrate_cutoff_cont_2arm.R
\name{calibrate_cutoff_cont_2arm}
\alias{calibrate_cutoff_cont_2arm}
\title{Calibrate Posterior Probability Cutoff for a Two-Arm Comparative Trial with Continuous Endpoint}
\usage{
calibrate_cutoff_cont_2arm(
  if.prior,
  nf.prior,
  prior.t = nf.prior,
  target = 0.05,
  n.t,
  n,
  sigma.t,
  sigma,
  theta.t = NULL,
  theta = NULL,
  delta,
  method = c("SAM", "rMAP", "NP"),
  alternative = c("greater", "less"),
  margin = 0,
  weight_rMAP = 0.5,
  method.w = "LRT",
  prior.odds = 1,
  interval = c(0.5, 0.999),
  rel.tol = 1e-05,
  oc_rel.tol = 1e-06,
  n_sd_int = 8
)
}
\arguments{
\item{if.prior}{Informative prior constructed based on historical data for
the control arm, represented (approximately) as a normal mixture prior.}

\item{nf.prior}{Non-informative prior used for the mixture.}

\item{prior.t}{Prior used for the treatment arm. If missing, the default
value is set to be \code{nf.prior}.}

\item{target}{Target rejection probability under the calibration scenario,
typically the desired type I error rate when the calibration scenario
corresponds to the null hypothesis.}

\item{n.t}{Sample size for the treatment arm.}

\item{n}{Sample size for the control arm.}

\item{sigma.t}{Known sampling standard deviation for the treatment arm.}

\item{sigma}{Known sampling standard deviation for the control arm.}

\item{theta.t}{The mean for the treatment arm under the calibration scenario.}

\item{theta}{The mean for the control arm under the calibration scenario.}

\item{delta}{Clinically significant difference used for the SAM prior.
This argument is only used when \code{method = "SAM"}.}

\item{method}{Borrowing strategy for the control arm. Must be one of
\code{"SAM"}, \code{"rMAP"}, or \code{"NP"}.}

\item{alternative}{Direction of the posterior decision. Must be one of
\code{"greater"} (for superiority) or \code{"less"} (for inferiority).}

\item{margin}{Clinical margin. Must be non-negative. Default is \code{0}.}

\item{weight_rMAP}{Weight assigned to the informative prior component
(\eqn{0 \leq} \code{weight_rMAP} \eqn{\leq 1}) for the robust MAP prior.
This argument is only used when \code{method = "rMAP"}. The default value is
0.5.}

\item{method.w}{Methods used to determine the mixture weight for SAM priors.
The default method is "LRT" (Likelihood Ratio Test), the alternative option
is "PPR" (Posterior Probability Ratio). See \code{\link{SAM_weight}} for
more details.}

\item{prior.odds}{The prior probability of \eqn{H_0} being true compared to
the prior probability of \eqn{H_1} being true using PPR method. The default
value is 1. See \code{\link{SAM_weight}} for more details.}

\item{interval}{Search interval for the posterior probability cutoff. The
default is from 0.5 to 0.999.}

\item{rel.tol}{Tolerance passed to \code{\link[stats]{uniroot}}.}

\item{oc_rel.tol}{Relative tolerance passed to scenario-level numerical
integration.}

\item{n_sd_int}{Half-width of the numerical integration region for each arm,
expressed as a multiple of the corresponding standard error.}
}
\value{
A list with the following elements:
\describe{
  \item{cutoff}{Calibrated posterior probability cutoff.}
  \item{objective}{Value of the root-finding objective at the solution.}
  \item{target}{Target rejection probability.}
  \item{method}{Borrowing method used.}
  \item{alternative}{Direction of the posterior decision.}
  \item{margin}{Clinical margin used for inference.}
  \item{theta}{True control-arm mean under the calibration scenario.}
  \item{theta.t}{True treatment-arm mean under the calibration scenario.}
  \item{interval}{Search interval used for calibration.}
}
}
\description{
The \code{calibrate_cutoff_cont_2arm} function is designed to calibrate the
posterior probability cutoff for a two-arm comparative trial with a
continuous endpoint under one borrowing strategy: self-adapting mixture prior
(SAM), robust MAP prior with fixed weight (rMAP), or non-informative prior
(NP).
}
\details{
The calibrated cutoff is chosen so that the repeated-sampling rejection
probability under a specified scenario equals the target value.


The function solves for the posterior probability cutoff such that the
scenario-level rejection probability returned by
\code{\link{eval_scenario_cont_2arm}} matches \code{target}. Under null
scenarios, this corresponds to calibration of the type I error.
}
