% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/get_OC.R
\name{get_OC}
\alias{get_OC}
\title{Generating Operating Characteristics of SAM Priors Using Analytical Engines}
\usage{
get_OC(
  if.prior,
  theta.h,
  method.w,
  prior.odds,
  nf.prior,
  prior.t = nf.prior,
  delta,
  n,
  n.t,
  target = 0.05,
  if.rMAP = FALSE,
  weight.rMAP = 0.5,
  theta,
  theta.t,
  alternative = c("greater", "less"),
  margin = 0,
  rel.tol = 1e-05,
  oc_rel.tol = 1e-06,
  interval = c(0.5, 0.999),
  n_sd_int = 8,
  ...
)
}
\arguments{
\item{if.prior}{Informative prior constructed from historical data,
represented (approximately) as a mixture of conjugate distributions.}

\item{theta.h}{Estimate of the treatment effect based on historical data.
Included for interface compatibility. If missing, the default value is set
to the posterior mean estimate from \code{if.prior}.}

\item{method.w}{Methods used to determine the mixture weight for SAM priors.
The default method is LRT (Likelihood Ratio Test), the alternative option can
be 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{nf.prior}{Non-informative prior used as the robustifying component
for the control arm prior.}

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

\item{delta}{Clinically significant difference used for the SAM prior.}

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

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

\item{target}{Target type I error used to calibrate the posterior probability
cutoff for each method. The default value is typically 0.05.}

\item{if.rMAP}{Whether to evaluate the operating characteristics of the
robust MAP prior for comparison. The default value is \code{FALSE}.}

\item{weight.rMAP}{Weight assigned to the informative prior component
(\eqn{0 \le} \code{weight.rMAP} \eqn{\le 1}) for the robust MAP prior.}

\item{theta}{A vector of the response rate (binary endpoints) or mean
(continuous endpoints) for the control arm.}

\item{theta.t}{A vector of the response rate (binary endpoints) or mean
(continuous endpoints) for the treatment arm.}

\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 a non-negative scalar. The default
value is \code{0}.}

\item{rel.tol}{Tolerance passed to numerical root finding.}

\item{oc_rel.tol}{Relative tolerance passed to operating characteristic
evaluation.}

\item{interval}{Search interval for the posterior probability cutoff.}

\item{n_sd_int}{Half-width of the numerical integration region for each arm,
expressed as a multiple of the corresponding standard error. Used for
continuous endpoints only.}

\item{...}{Additional parameters. For continuous endpoints, this includes
\code{sigma}.}
}
\value{
A data frame with one row per scenario-method combination. The
columns are:
\describe{
  \item{Scenarios}{Scenario index.}
  \item{theta}{True control-arm parameter value.}
  \item{theta.t}{True treatment-arm parameter value.}
  \item{Methods}{Borrowing method, one of \code{"NP"}, \code{"rMAP"}, or \code{"SAM"}.}
  \item{Cutoffs}{Calibrated posterior probability cutoff for the method.}
  \item{Bias of theta}{Bias of the posterior mean estimator of \eqn{\theta}.}
  \item{RMSE of theta}{Root mean squared error of the posterior mean estimator of \eqn{\theta}.}
  \item{Weight}{Average borrowing weight under the method.}
  \item{Probability of Rejection}{Repeated-sampling rejection probability.}
}
}
\description{
The \code{get_OC} function generates operating characteristics of SAM
priors using the analytical operating characteristic engines for two-arm
trials with binary or continuous endpoints. As an option, the operating
characteristics of robust MAP priors can also be generated for comparison.
}
\details{
Compared with the original simulation-based implementation, this function
does not rely on trial simulation. Instead, it first calibrates the
posterior probability cutoff for each borrowing method to achieve the
target type I error, and then evaluates operating characteristics
analytically across the requested scenarios.


For each borrowing method, the function first calibrates the posterior
probability cutoff so that the repeated-sampling rejection probability under
the boundary null scenario equals the target type I error \code{target}.
Specifically, calibration is based on the first value of \code{theta}. Let
\eqn{\theta = \code{theta}[1]} denote the control-arm parameter under the
calibration scenario. Then the treatment-arm parameter is set to
\eqn{\theta_t = \theta + margin} when \code{alternative = "greater"}, and
to \eqn{\theta_t = \theta - margin} when \code{alternative = "less"}.
Thus, when \code{margin = 0}, calibration is performed under the null
scenario \eqn{\theta_t = \theta}, corresponding to no treatment effect
difference between the treatment and control arms. After the cutoff is
calibrated, the function evaluates the operating characteristics across all
requested scenarios using the analytical two-arm engines.
}
\examples{
## Example: operating characteristics for a two-arm binary trial
## using a SAM prior without rMAP comparison

## Informative prior constructed from historical data
if.prior <- mixbeta(c(1, 20, 40))

## Evaluate operating characteristics
OC <- get_OC(
  if.prior = if.prior,
  nf.prior = mixbeta(c(1, 1, 1)),   ## Non-informative prior for control mixture
  prior.t = mixbeta(c(1, 1, 1)),    ## Prior for treatment arm
  delta = 0.2,                      ## Clinically significant difference for SAM
  n = 50,                           ## Sample size for control arm
  n.t = 100,                        ## Sample size for treatment arm
  target = 0.05,                    ## Target type I error for cutoff calibration
  if.rMAP = FALSE,                  ## Do not include rMAP comparison
  theta = c(summary(if.prior)["mean"], summary(if.prior)["mean"]),
  theta.t = c(summary(if.prior)["mean"], 0.50),
  alternative = "greater",          ## Superiority test
  margin = 0                        ## Clinical margin
)

OC

}
\references{
Yang P, Zhao Y, Nie L, Vallejo J, Yuan Y.
SAM: Self-adapting mixture prior to dynamically borrow information from
historical data in clinical trials.
\emph{Biometrics} 2023;79(4):2857-2868.

Schmidli H, Gsteiger S, Roychoudhury S, O'Hagan A, Spiegelhalter D,
Neuenschwander B.
Robust meta-analytic-predictive priors in clinical trials with historical
control information.
\emph{Biometrics} 2014;70(4):1023-1032.
}
\seealso{
\code{\link{eval_oc_bin_2arm}},
\code{\link{eval_oc_cont_2arm}}, \code{\link{calibrate_cutoff_bin_2arm}},
\code{\link{calibrate_cutoff_cont_2arm}}
}
