calibrate_cutoff_bin_2arm: Calibrate Posterior Probability Cutoff for a Two-Arm...

In SAMprior: Self-Adapting Mixture (SAM) Priors

Calibrate Posterior Probability Cutoff for a Two-Arm Comparative Trial with Binary Endpoint

Description

The calibrate_cutoff_bin_2arm function is designed to calibrate the posterior probability cutoff for a two-arm comparative trial with a binary endpoint under one borrowing strategy: self-adapting mixture prior (SAM), robust MAP prior with fixed weight (rMAP), or non-informative prior (NP).

Usage

calibrate_cutoff_bin_2arm(
  if.prior,
  nf.prior,
  prior.t = nf.prior,
  target = 0.05,
  n.t,
  n,
  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-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 for the mixture.
prior.t	Prior used for the treatment arm. If missing, the default value is set to be nf.prior.
target	Target rejection probability under the calibration scenario, typically the desired type I error rate when the calibration scenario corresponds to the null hypothesis.
n.t	Sample size for the treatment arm.
n	Sample size for the control arm.
theta.t	The response rate for the treatment arm under the calibration scenario.
theta	The response rate for the control arm under the calibration scenario.
delta	Clinically significant difference used for the SAM prior. This argument is only used when method = "SAM".
method	Borrowing strategy for the control arm. Must be one of "SAM", "rMAP", or "NP".
alternative	Direction of the posterior decision. Must be one of "greater" (for superiority) or "less" (for inferiority).
margin	Clinical margin. Must be non-negative. Default 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.
interval	Search interval for the posterior probability cutoff. The default is from 0.5 to 0.999.
rel.tol	Tolerance passed to uniroot.
oc_rel.tol	Relative tolerance passed to scenario-level calculations.

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 eval_scenario_bin_2arm matches target. Under null scenarios, this corresponds to calibration of the type I error.

Value

A list with the following elements:

cutoff

Calibrated posterior probability cutoff.

objective

Value of the root-finding objective at the solution.

target

Target rejection probability.

method

Borrowing method used.

alternative

Direction of the posterior decision.

margin

Clinical margin used for inference.

theta

True control-arm response rate under the calibration scenario.

theta.t

True treatment-arm response rate under the calibration scenario.

interval

Search interval used for calibration.

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