runCalibratedSAM: Run a Calibrated Simulation Using SAM Priors

Description

Performs a two-step simulation.

Calibration Step: It first runs a simulation under the null hypothesis (using *.calib parameters) to determine the posterior probability thresholds (quantiles) needed to control the Type I Error Rate at the specified typeIER.cal level.
Main Simulation Step: It then uses these calibrated thresholds to run the main simulation (using parameters nc, nt, pc, pt) to evaluate final operating characteristics (e.g., Type I Error or Power) and bias.

Usage

runCalibratedSAM(
  nsim = 1000,
  pch,
  delta_threshold,
  nche.c,
  nc.calib,
  nt.calib,
  pc.calib,
  xt.cal = NULL,
  xc.cal = NULL,
  typeIER.cal = 0.1,
  nche,
  nc,
  nt,
  pc,
  pt,
  xt = NULL,
  xc = NULL,
  nf.prior = RBesT::mixbeta(c(1, 0.001, 0.001)),
  seed.hist = 1000,
  seed.gMAP = 2000,
  seed.SAM = 3000,
  seed.cal = 4000
)

Value

A list with the following components:

Sim_Result: A numeric vector (length 3) with the final simulation result (Type I Error or Power) for the "SAMprior", "MAP", and "Noninfo" methods.
pc.PMD: Posterior Mean Difference (Bias) for the three methods.
pc.PSDD: Posterior SD of the Difference (Bias) for the three methods.
pc.PM: A matrix (3 x nsim) of posterior means for the control rate for each simulation iteration.
Calibration_Thresholds: A matrix (1x3) containing the decision thresholds (quantiles) determined during the calibration step for the SAM, rMAP, and Non-info methods.

Arguments

nsim: The total number of simulation trials to run for both the calibration and main simulation steps.
pch: Historical control response rate (used to generate HistData for the RBesT::gMAP() prior).
delta_threshold: The CSD (Clinically Significant Difference) threshold used for the SAM prior in runSAM().
nche.c: Sample size for the historical control data (HistData).
nc.calib: Control group sample size for the calibration step.
nt.calib: Treatment group sample size for the calibration step.
pc.calib: Control response rate for the calibration step. This is also used as the treatment response rate in this step to simulate the null hypothesis.
xt.cal: (Optional) A vector of pre-simulated treatment outcomes for the calibration step. If NULL, data is simulated internally.
xc.cal: (Optional) A vector of pre-simulated control outcomes for the calibration step. If NULL, data is simulated internally.
typeIER.cal: The target Type I Error rate to control for during the calibration step. Defaults to 0.1.
nche: Historical control sample size. (Note: This parameter is defined in the function signature but not explicitly used in the function body; nche.c is used for calibration data generation.)
nc: Control group sample size for the main simulation step.
nt: Treatment group sample size for the main simulation step.
pc: Control response rate for the main simulation step.
pt: Treatment response rate for the main simulation step. (Note: Set pt = pc for Type I Error, or pt > pc for Power).
xt: (Optional) A vector of pre-simulated treatment outcomes for the main simulation. If NULL, data is simulated internally.
xc: (Optional) A vector of pre-simulated control outcomes for the main simulation. Examples use RBesT::mixbeta(). If NULL, data is simulated internally.
nf.prior: The non-informative prior to use. Defaults to RBesT::mixbeta(c(1, 0.001, 0.001)).
seed.hist: Seed for generating historical data.
seed.gMAP: Seed for the RBesT::gMAP() function.
seed.SAM: Seed for the main runSAM simulation call.
seed.cal: Seed for the calibration runSAM call.

Details

This function wraps the core runSAM() function by adding a calibration layer. It derives historical data priors using RBesT::gMAP() and RBesT::automixfit() based on nche.c and pch.

The calibration step (runSAM with ...calib parameters) finds the (1 - typeIER.cal) quantiles for the posterior distributions (SAM, rMAP, Non-info) under the null.

The main simulation step (runSAM with main parameters) then calculates the proportion of simulations where the posterior probability exceeds these calibrated thresholds. This proportion represents the final Type I Error or Power.

Examples

Run this code

# \donttest{
# Example uses functions from the RBesT package
library(RBesT)

sim_power_pc30 <- runCalibratedSAM(
   nsim = 100,
   pch = 0.30,
   delta_threshold = 0.1,
   nche.c = 180,
   nc.calib = 45,
   nt.calib = 45,
   pc.calib = 0.3,
   typeIER.cal = 0.10,
   nche = 180,
   nc = 45,
   nt = 45,
   pc = 0.30,
   pt = 0.50
)

print(sim_power_pc30$Sim_Result)
# }