toBinomialExact: Translate survival design bounds to exact binomial bounds

In gsDesign: Group Sequential Design

Translate survival design bounds to exact binomial bounds

Description

Translate survival design bounds to exact binomial bounds

Usage

toBinomialExact(
  x,
  observedEvents = NULL,
  alpha = NULL,
  usTime = NULL,
  lsTime = NULL,
  maxSpend = FALSE
)

Arguments

x	An object of class gsSurv; i.e., an object generated by the gsSurv() function.
observedEvents	If NULL (default), targeted timing of analyses will come from x$n.I. Otherwise, this should be vector of increasing positive integers with at most 1 value >= x$n.IPlan and of length at least 2. Only one value can be greater than or equal to x$maxn.IPlan. This determines the case count at each analysis performed. Primarily, this is used for updating a design at the time of analysis.
alpha	Optional alpha level for deriving updated exact efficacy bounds. If NULL, the alpha level from x is used.
usTime	Optional upper spending-time override (length k or k - 1, with final value appended as 1 if needed). If NULL, this defaults to observedEvents / x$maxn.IPlan (capped at 1) when observedEvents is supplied, or to the planned design timing otherwise.
lsTime	Optional lower spending-time override for test.type = 4 (same length and monotonicity requirements as usTime). If NULL, it defaults to usTime.
maxSpend	Logical scalar. If 'TRUE', force full alpha spending (and, for 'test.type = 4', full beta spending) at the final analysis even when 'observedEvents[k] < x$maxn.IPlan'. This keeps earlier analysis spending unchanged and applies the override only at the last look.

Details

Only test.type 1 (one-sided) and test.type 4 (non-binding futility) are supported. Other test types (including test.type 7 and 8 with harm bounds) will produce an error.

The exact binomial routine gsBinomialExact has requirements that may not be satisfied by the initial asymptotic approximation. Thus, the approximations are updated to satisfy the following requirements of gsBinomialExact: a (the efficacy bound) must be positive, non-decreasing, and strictly less than n.I b (the futility bound) must be positive, non-decreasing, strictly greater than a n.I - b must be non-decreasing and >= 0

With 'observedEvents', spending times are based on observedEvents / x$maxn.IPlan. If maxSpend = TRUE, the final spending time is set to 1 so all remaining spending is used at the last look. If x$testLower is present (for example from gsSurv() with selective futility looks), futility spending is flattened at analyses where testLower = FALSE.

Value

An object of class gsBinomialExact.

See Also

gsBinomialExact

Examples

# The following code derives the group sequential design using the method
# of Lachin and Foulkes

x <- gsSurv(
  k = 3,                 # 3 analyses
  test.type = 4,         # Non-binding futility bound 1 (no futility bound) and 4 are allowable
  alpha = .025,          # 1-sided Type I error
  beta = .1,             # Type II error (1 - power)
  timing = c(0.45, 0.7), # Proportion of final planned events at interims
  sfu = sfHSD,           # Efficacy spending function
  sfupar = -4,           # Parameter for efficacy spending function
  sfl = sfLDOF,          # Futility spending function; not needed for test.type = 1
  sflpar = 0,            # Parameter for futility spending function
  lambdaC = .001,        # Exponential failure rate
  hr = 0.3,              # Assumed proportional hazard ratio (1 - vaccine efficacy = 1 - VE)
  hr0 = 0.7,             # Null hypothesis VE
  eta = 5e-04,           # Exponential dropout rate
  gamma = 10,            # Piecewise exponential enrollment rates
  R = 16,                # Time period durations for enrollment rates in gamma
  T = 24,                # Planned trial duration
  minfup = 8,            # Planned minimum follow-up
  ratio = 3              # Randomization ratio (experimental:control)
)
# Convert bounds to exact binomial bounds
toBinomialExact(x)
# Update bounds at time of analysis
toBinomialExact(x, observedEvents = c(20,55,80))
# Update exact efficacy bounds using a different alpha level
toBinomialExact(x, observedEvents = c(20,55,80), alpha = 0.01)
# Explicit spending-time override
toBinomialExact(x, observedEvents = c(20, 55, 80), usTime = c(.25, .65, 1))
# Optionally force full spending at final look when final events are below plan
toBinomialExact(x, observedEvents = c(20, 55, 75), maxSpend = TRUE)

gsDesign documentation built on July 20, 2026, 9:06 a.m.