toInteger: Translate group sequential design to integer events (survival...

In gsDesign: Group Sequential Design

Translate group sequential design to integer events (survival designs) or sample size (other designs)

Description

Translate group sequential design to integer events (survival designs) or sample size (other designs)

Usage

toInteger(x, ratio = x$ratio, roundUpFinal = TRUE)

Arguments

x	An object of class gsDesign or gsSurv.
ratio	Usually corresponds to experimental:control sample size ratio. If an integer is provided, rounding is done to a multiple of ratio + 1. See details. If input is non integer, rounding is done to the nearest integer or nearest larger integer depending on roundUpFinal.
roundUpFinal	For non-survival designs, final sample size is rounded up to a multiple of ratio + 1 with the default roundUpFinal = TRUE if ratio is a non-negative integer. For survival designs, the final event count is rounded up with roundUpFinal = TRUE. If roundUpFinal = FALSE and ratio is a non-negative integer, sample size is rounded to the nearest multiple of ratio + 1. See details.

Details

It is useful to explicitly provide the argument ratio when a gsDesign object is input since gsDesign() does not have a ratio in return. ratio = 0, roundUpFinal = TRUE will just round up the sample size for non-survival designs. Since x <- gsSurv(ratio = M) returns a value for ratio, toInteger(x) will round to a multiple of M + 1 if M is a non-negative integer; otherwise, just rounding will occur. For 1:1 randomization, ratio = 1 gives an even final sample size. For 2:1 randomization, ratio = 2 gives a final sample size that is a multiple of 3. To just round without concern for randomization ratio, set ratio = 0. If toInteger(x, ratio = 3), rounding for final sample size is done to a multiple of 3 + 1 = 4; this could represent a 3:1 or 1:3 randomization ratio. For 3:2 randomization, ratio = 4 would ensure rounding sample size to a multiple of 5.

For a gsSurv object, x$n.I is an event-count schedule. toInteger() rounds the final planned event count (up when roundUpFinal = TRUE; otherwise to nearest integer, with a 0.01 tolerance), then derives interim integer event targets from x$timing * final_events. Interim counts are constrained to be positive and strictly increasing. Group sequential boundaries and spending are recomputed with gsDesign() at the integer event counts.

Total sample size for a survival design is then updated under a fixed calendar plan (same enrollment periods, study duration, and minimum follow-up). Enrollment rates are scaled proportionally to the final-event inflation factor and rounded to the nearest allocation multiple ratio + 1 (or rounded up when roundUpFinal = TRUE), with additional allocation-step adjustment only if needed to make the integer final event target achievable.

If fixed-calendar enrollment-rate inflation cannot make the integer final event target feasible, toInteger() falls back to a variable-duration solve and issues a warning. For a complete seasonal exact-binomial monitoring workflow, see vignette("MultiSeasonRareEvents", package = "gsDesign").

Selective-bound settings (testUpper, testLower, testHarm, and harm spending for test.type 7 or 8) are carried from the input design into the internal gsDesign() recomputation so skipped looks stay skipped after integer rounding.

Value

Output is an object of the same class as input x; i.e., gsDesign with integer vector for n.I or gsSurv with integer vector n.I and integer total sample size. See details.

See Also

gsSurv, toBinomialExact, vignette("MultiSeasonRareEvents", package = "gsDesign")

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 sample size to multiple of ratio + 1 = 4,
# with final event count rounded up by default.
toInteger(x)

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