calibrate_cutoff_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

Description

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

Usage

calibrate_cutoff_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-06,
  ...
)

## S3 method for class 'betaMix'
calibrate_cutoff_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,
  ...
)

## S3 method for class 'normMix'
calibrate_cutoff_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-06,
  sigma.t,
  sigma,
  n_sd_int = 8,
  ...
)

Arguments

if.prior	Informative prior constructed from historical data, represented (approximately) as a mixture of conjugate distributions.
nf.prior	Non-informative prior used for the mixture and 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.
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 (binary endpoints) or mean (continuous endpoints) for the treatment arm under the calibration scenario.
theta	The response rate (binary endpoints) or mean (continuous endpoints) 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. For continuous endpoints this controls numerical integration in the operating-characteristic engine; for binary endpoints this controls numerical integration in posterior probability calculations.
...	Additional arguments required by the endpoint-specific method. For continuous endpoints, this includes sigma.t, sigma, and optionally n_sd_int.
sigma.t	Known sampling standard deviation in the treatment arm.
sigma	Known sampling standard deviation in the control arm.
n_sd_int	Half-width of the numerical integration region for each arm, expressed as a multiple of the corresponding standard error.

Details

For binary endpoints, the function dispatches to calibrate_cutoff_bin_2arm. For continuous endpoints, it dispatches to calibrate_cutoff_cont_2arm.

The function calibrates the posterior probability cutoff C for a two-arm comparative trial so that the repeated-sampling rejection probability under the specified calibration scenario equals target. Inference is based on the posterior probability of the treatment effect \theta_t - \theta, where \theta_t and \theta denote the treatment-arm and control-arm parameters, respectively.

For alternative = "greater", the posterior decision rule is based on

P(\theta_t - \theta > \Delta \mid D) > C,

where \Delta denotes the clinical margin and D denotes the observed data. Under the default settings, calibration is performed under the null scenario \theta_t = \theta = \theta_h, where \theta_h = E(\code{if.prior}) is the posterior mean of the informative prior constructed from historical data. This corresponds to a superiority test when \Delta = 0.

For alternative = "less", the posterior decision rule is based on

P(\theta_t - \theta < -\Delta \mid D) > C.

Calibration is again performed under the null scenario \theta_t = \theta = \theta_h, where \theta_h = E(\code{if.prior}). This corresponds to an inferiority test when \Delta = 0.

This function acts as a generic front-end and dispatches according to the class of if.prior. For binary endpoints, it calls calibrate_cutoff_bin_2arm. For continuous endpoints, it calls calibrate_cutoff_cont_2arm.

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 parameter under the calibration scenario.

theta.t

True treatment-arm parameter under the calibration scenario.

interval

Search interval used for calibration.

Methods (by class)

• calibrate_cutoff_2arm(betaMix): Calibrate the posterior probability cutoff for a two-arm binary endpoint.

• calibrate_cutoff_2arm(normMix): Calibrate the posterior probability cutoff for a two-arm continuous endpoint.

See Also

calibrate_cutoff_bin_2arm, calibrate_cutoff_cont_2arm

Examples

## Example: calibrate the posterior probability cutoff for a two-arm
## binary trial using a SAM prior for the control arm

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

## Sample sizes
n.t <- 100
n <- 50

## Calibrate the posterior probability cutoff
PPC <- calibrate_cutoff_2arm(
  if.prior = if.prior,             ## Informative prior from historical data
  nf.prior = mixbeta(c(1, 1, 1)),  ## Non-informative prior for SAM prior
  prior.t = mixbeta(c(1, 1, 1)),   ## Prior for treatment arm
  target = 0.05,                   ## Targeted type I error rate
  n.t = n.t,                       ## Sample size for treatment arm
  n = n,                           ## Sample size for control arm
  theta.t = summary(if.prior)["mean"],  ## True treatment-arm response rate
  theta = summary(if.prior)["mean"],    ## True control-arm response rate
  method = "SAM",                  ## Borrowing method
  delta = 0.2,                     ## Clinically significant difference
  alternative = "greater",         ## Superiority test
  margin = 0                       ## Clinical margin
)

PPC

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