get_OC: Generating Operating Characteristics of SAM Priors Using...

In SAMprior: Self-Adapting Mixture (SAM) Priors

Generating Operating Characteristics of SAM Priors Using Analytical Engines

Description

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

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

if.prior	Informative prior constructed from historical data, represented (approximately) as a mixture of conjugate distributions.
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 if.prior.
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 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.
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.
delta	Clinically significant difference used for the SAM prior.
n	Sample size for the control arm.
n.t	Sample size for the treatment arm.
target	Target type I error used to calibrate the posterior probability cutoff for each method. The default value is typically 0.05.
if.rMAP	Whether to evaluate the operating characteristics of the robust MAP prior for comparison. The default value is FALSE.
weight.rMAP	Weight assigned to the informative prior component (0 \le weight.rMAP \le 1) for the robust MAP prior.
theta	A vector of the response rate (binary endpoints) or mean (continuous endpoints) for the control arm.
theta.t	A vector of the response rate (binary endpoints) or mean (continuous endpoints) for the treatment arm.
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.
rel.tol	Tolerance passed to numerical root finding.
oc_rel.tol	Relative tolerance passed to operating characteristic evaluation.
interval	Search interval for the posterior probability cutoff.
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.
...	Additional parameters. For continuous endpoints, this includes sigma.

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 target. Specifically, calibration is based on the first value of theta. Let \theta = \code{theta}[1] denote the control-arm parameter under the calibration scenario. Then the treatment-arm parameter is set to \theta_t = \theta + margin when alternative = "greater", and to \theta_t = \theta - margin when alternative = "less". Thus, when margin = 0, calibration is performed under the null scenario \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.

Value

A data frame with one row per scenario-method combination. The columns are:

Scenarios

Scenario index.

theta

True control-arm parameter value.

theta.t

True treatment-arm parameter value.

Methods

Borrowing method, one of "NP", "rMAP", or "SAM".

Cutoffs

Calibrated posterior probability cutoff for the method.

Bias of theta

Bias of the posterior mean estimator of \theta.

RMSE of theta

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

Weight

Average borrowing weight under the method.

Probability of Rejection

Repeated-sampling rejection probability.

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. 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. Biometrics 2014;70(4):1023-1032.

See Also

eval_oc_bin_2arm, eval_oc_cont_2arm, calibrate_cutoff_bin_2arm, calibrate_cutoff_cont_2arm

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

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