eval_oc_bin_2arm: Evaluate Multiple Scenarios for a Two-Arm Comparative Trial...

In SAMprior: Self-Adapting Mixture (SAM) Priors

Evaluate Multiple Scenarios for a Two-Arm Comparative Trial with Binary Endpoint

Description

The 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).

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

if.prior	Informative prior constructed based on historical data for the control arm, represented (approximately) as a beta mixture prior.
nf.prior	Non-informative prior used as the robustifying component for the control arm prior.
prior.t	Prior used for the treatment arm. If missing, the default value is set to be nf.prior.
theta	A vector of true control arm response rates.
theta.t	A vector of true treatment arm response rates.
n.t	Sample size for the treatment arm.
n	Sample size for the control arm.
delta	Clinically significant difference used for the SAM prior. This argument is only used when method = "SAM".
method	Borrowing methods to evaluate. Any subset of c("SAM", "rMAP", "NP").
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 c(SAM = 0.94, rMAP = 0.96, NP = 0.95).
alternative	Direction of the posterior decision. Must be one of "greater" (for superiority) or "less" (for inferiority).
margin	Clinical margin. Must be a non-negative scalar. The default value is 0.
weight_rMAP	Weight assigned to the informative prior component (0 \leq weight_rMAP \leq 1) for the robust MAP prior. This argument is only used when method = "rMAP". The default value is 0.5.
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 SAM_weight for more details.
prior.odds	The prior probability of H_0 being true compared to the prior probability of H_1 being true using PPR method. The default value is 1. See SAM_weight for more details.
rel.tol	Relative tolerance passed to scenario-level numerical integration used in post_summary_bin_2arm.

Details

For each scenario, the function computes the repeated-sampling rejection probability, bias, RMSE, and mean borrowing weight using eval_scenario_bin_2arm.

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

The 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.

Value

A data frame with one row per scenario-method combination and columns:

scenario

Scenario index.

theta

True control arm response rate.

theta.t

True treatment arm response rate.

delta_true

True treatment effect, \tau = \theta_t - \theta.

method

Borrowing method used.

alternative

Direction of the posterior decision.

cutoff

Posterior probability cutoff used.

margin

Clinical margin used for inference.

reject_prob

Repeated-sampling rejection probability.

bias

Bias of the posterior mean estimator of \theta.

rmse

Root mean squared error of the posterior mean estimator of \theta.

mean_weight

Average borrowing weight under the specified method.

SAMprior documentation built on April 28, 2026, 1:07 a.m.