gsDesign (version 3.10.1)

simBinomialSeasonalExact: Simulate exact-binomial seasonal monitoring scenarios

Description

Simulate seasonal rare-event trials monitored with exact-binomial efficacy bounds derived from a `gsSurv` design. This helper supports fixed enrollment and a simple blinded information-adaptive enrollment rule while keeping the spending framework fixed through the original `gsSurv` design object.

The function summarizes empirical rejection rates (Type I error or power), futility stopping rates (binding interpretation), Monte Carlo standard errors, average final events, average total enrollment, and average number of informative looks.

Usage

simBinomialSeasonalExact(
  gsD,
  ve = c(0.3, 0.8),
  nsim = c(600, 600),
  control_event_rate = c(0.003, 0.003),
  season_length = 0.5,
  dropout_rate = 0.1,
  planned_counts = NULL,
  timing = NULL,
  enroll_control_per_look = NULL,
  enroll_experimental_per_look = NULL,
  adaptive = c(FALSE, TRUE),
  adapt_looks = NULL,
  max_multiplier = 2,
  usTime = NULL,
  lsTime = NULL,
  final_full_spending = FALSE,
  seed = NULL,
  return_trials = FALSE
)

Value

A list with:

`summary`

Data frame with scenario-level summaries.

`planned`

List with planned counts, exact design object, and planned/calibrated enrollment by look.

`inputs`

List of simulation inputs used.

`trials`

Optional trial-level data frame (`NULL` unless `return_trials = TRUE`).

Arguments

gsD

A `gsSurv` object with `test.type` 1 or 4.

ve

Numeric vector of vaccine efficacy (or prevention efficacy) scenarios to simulate. Each value must be finite and less than 1. `ve = 0` corresponds to equal event rates (superiority null); `ve < 0` corresponds to experimental-arm event rates above control (non-inferiority margin or harmful scenarios).

nsim

Integer scalar or vector giving the number of simulations per element of `ve`.

control_event_rate

Numeric scalar or vector with control seasonal event probabilities corresponding to `ve`.

season_length

Numeric scalar > 0 giving season duration in years.

dropout_rate

Seasonal dropout probability in `[0, 1)`.

planned_counts

Optional increasing integer vector of planned cumulative events at analyses. If `NULL`, these are derived from `timing * toInteger(gsD)$n.I[k]`.

timing

Optional increasing cumulative spending-time vector ending at 1 used to derive `planned_counts` when `planned_counts = NULL`.

enroll_control_per_look

Optional control-arm enrollment by look (scalar or length `k` integer vector). If both enrollment vectors are `NULL`, defaults are derived from the seasonal accrual pattern in `gsD`.

enroll_experimental_per_look

Optional experimental-arm enrollment by look (scalar or length `k` integer vector). If `NULL` and `enroll_control_per_look` is supplied, this is set using `gsD$ratio`.

adaptive

Logical vector specifying whether to simulate fixed and/or adaptive enrollment scenarios.

adapt_looks

Integer vector of look indices after which adaptation can be applied (default: all interim looks).

max_multiplier

Maximum multiplicative enrollment increase at a look when adaptation is enabled.

usTime

Optional upper spending-time override passed to [toBinomialExact()]. If `NULL`, spending time defaults to `1 / k, 2 / k, ..., 1`.

lsTime

Optional lower spending-time override for `test.type = 4`. If `NULL`, this defaults to `usTime`.

final_full_spending

Logical scalar. If `TRUE`, force full alpha spending at the final analysis even when the final observed total event count is below planned final events.

seed

Optional integer seed for reproducibility.

return_trials

Logical. If `TRUE`, return trial-level simulation outcomes.

See Also

[toBinomialExact()], [repeatedPValueBinomialExact()], [sequentialPValueBinomialExact()]

Examples

x <- gsSurv(
  k = 3, test.type = 4, alpha = 0.025, beta = 0.1, timing = c(1 / 3, 2 / 3),
  sfu = sfHSD, sfupar = 1, sfl = sfHSD, sflpar = -2,
  lambdaC = -log(1 - 0.003) / 0.5,
  hr = 0.2, hr0 = 0.7, eta = -log(1 - 0.1) / 0.5,
  gamma = c(1, 0, 1, 0, 1, 0), R = c(2, 10, 2, 10, 2, 10),
  T = 42, minfup = 6, ratio = 3
) |> toInteger()

simBinomialSeasonalExact(
  gsD = x,
  ve = c(0.3, 0.8),
  nsim = c(50, 50),
  control_event_rate = c(0.003, 0.003),
  seed = 123
)$summary