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, 6, or 8 (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' or '8', full beta spending; for 'test.type = 6', full lower-bound spending under the null; and, for 'test.type = 8', full harm spending under the null) 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

Test types 1 (one-sided), 4 (non-binding beta-spending futility), 6 (non-binding lower-bound spending under the null), and 8 (non-binding futility and harm) are supported for full conversion. For Type 8, the exact upper event-count stopping probability is partitioned into mutually exclusive futility and harm components. Binding designs (types 2, 3, 5, and 7) are outside the non-binding exact-efficacy framework. Exact repeated and sequential efficacy p-values can nevertheless be computed for non-binding types 1, 4, 6, and 8 with repeatedPValueBinomialExact() and sequentialPValueBinomialExact(), which intentionally ignore non-binding lower and harm bounds.

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 upper event-count stopping bound for futility, harm, or the Type 6 lower bound) must be positive, non-decreasing, and 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 lower-bound looks), lower-bound spending is flattened at analyses where testLower = FALSE.

Value

An object of class gsBinomialExact. The returned object also records 'test.type', 'alpha', applicable 'astar', 'testLower', and applicable 'testHarm'. For ‘test.type = 6', the exact object’s upper event-count bound represents the non-binding lower stopping bound, with its first probability column calibrated under the null hypothesis. For 'test.type = 8', 'upper' represents all upper event-count stops, while 'futility' and 'harm' partition those stops into mutually exclusive components.

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 Aug. 29, 2026, 5:08 p.m.