% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/eval_oc_bin_2arm.R
\name{eval_oc_bin_2arm}
\alias{eval_oc_bin_2arm}
\title{Evaluate Multiple Scenarios for a Two-Arm Comparative Trial with Binary Endpoint}
\usage{
eval_oc_bin_2arm(
  if.prior,
  nf.prior,
  prior.t = nf.prior,
  theta,
  theta.t,
  n.t,
  n,
  delta,
  method = c("SAM", "rMAP", "NP"),
  cutoff,
  alternative = c("greater", "less"),
  margin = 0,
  weight_rMAP = 0.5,
  method.w = "LRT",
  prior.odds = 1,
  rel.tol = 1e-08
)
}
\arguments{
\item{if.prior}{Informative prior constructed based on historical data for
the control arm, represented (approximately) as a beta mixture prior.}

\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{theta}{A vector of true control arm response rates.}

\item{theta.t}{A vector of true treatment arm response rates.}

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

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

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

\item{method}{Borrowing methods to evaluate. Any subset of
\code{c("SAM", "rMAP", "NP")}.}

\item{cutoff}{Posterior probability cutoff specification. Either a single
numeric value applied to all methods, or a named numeric vector/list with
method-specific cutoffs, for example
\code{c(SAM = 0.94, rMAP = 0.96, NP = 0.95)}.}

\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{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{rel.tol}{Relative tolerance passed to scenario-level numerical
integration used in \code{\link{post_summary_bin_2arm}}.}
}
\value{
A data frame with one row per scenario-method combination and columns:
\describe{
  \item{scenario}{Scenario index.}
  \item{theta}{True control arm response rate.}
  \item{theta.t}{True treatment arm response rate.}
  \item{delta_true}{True treatment effect, \eqn{\tau = \theta_t - \theta}.}
  \item{method}{Borrowing method used.}
  \item{alternative}{Direction of the posterior decision.}
  \item{cutoff}{Posterior probability cutoff used.}
  \item{margin}{Clinical margin used for inference.}
  \item{reject_prob}{Repeated-sampling rejection probability.}
  \item{bias}{Bias of the posterior mean estimator of \eqn{\theta}.}
  \item{rmse}{Root mean squared error of the posterior mean estimator of \eqn{\theta}.}
  \item{mean_weight}{Average borrowing weight under the specified method.}
}
}
\description{
The \code{eval_oc_bin_2arm} function is designed to evaluate
repeated-sampling operating characteristics for multiple scenarios in a
two-arm comparative trial with a binary endpoint under one or more
borrowing strategies: self-adapting mixture prior (SAM), robust MAP prior
with fixed weight (rMAP), or non-informative prior (NP).
}
\details{
For each scenario, the function computes the repeated-sampling rejection
probability, bias, RMSE, and mean borrowing weight using
\code{\link{eval_scenario_bin_2arm}}.


The vectors \code{theta} and \code{theta.t} must have the same length.
Each pair \code{(theta[i], theta.t[i])} defines one scenario.

The \code{cutoff} argument may be common across methods or method-specific.
This is useful when each borrowing method is calibrated separately before
operating characteristics are evaluated.
}
