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, gsSurv, or nSurv.
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.

Value

Output is an object of the same class as input x; i.e., gsDesign with integer vector for n.I, gsSurv with integer vector n.I and integer total sample size, or nSurv with integer d and integer total sample size n. 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.

An nSurv object is converted through the corresponding single-analysis gsSurv representation and returned as an nSurv object. Its required event count d is rounded in the same way as the final event count for a gsSurv object, and its total sample size n is rounded according to ratio.

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. For a single-analysis survival design, the fixed efficacy boundary is retained and its power is recomputed at the integer final event count without invoking multi-look group sequential calculations.

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.

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)
#> Group sequential design (method=; k=3 analyses; Two-sided asymmetric with non-binding futility)
#> HR=0.300 vs HR0=0.700 | alpha=0.025 (sided=2) | power=90.0%
#> N=9172.0 subjects | D=69.0 events | T=24.0 study duration | accrual=16.0 Accrual duration | minfup=8.0 minimum follow-up | ratio=3 randomization ratio (experimental/control)
#> 
#> Spending functions:
#>   Efficacy bounds derived using a Hwang-Shih-DeCani spending function with gamma = -4.
#>   Futility bounds derived using a Lan-DeMets O'Brien-Fleming approximation spending function (no parameters).
#> 
#> Analysis summary:
#>    Analysis              Value Efficacy Futility
#>   IA 1: 45%                  Z   2.8273   0.0695
#>     N: 8678        p (1-sided)   0.0023   0.4723
#>  Events: 31       ~HR at bound   0.2167   0.6801
#>   Month: 15 P(Cross) if HR=0.7   0.0023   0.5277
#>             P(Cross) if HR=0.3   0.2863   0.0141
#>   IA 2: 70%                  Z   2.5197   1.1139
#>     N: 9172        p (1-sided)   0.0059   0.1327
#>  Events: 48       ~HR at bound   0.3022   0.4829
#>   Month: 19 P(Cross) if HR=0.7   0.0071   0.8716
#>             P(Cross) if HR=0.3   0.6265   0.0486
#>       Final                  Z   2.0035   2.0035
#>     N: 9172        p (1-sided)   0.0226   0.0226
#>  Events: 69       ~HR at bound   0.4010   0.4010
#>   Month: 24 P(Cross) if HR=0.7   0.0230   0.9770
#>             P(Cross) if HR=0.3   0.9027   0.0973
#> 
#> Key inputs (names preserved):
#>                                desc    item  value   input
#>                     Accrual rate(s)   gamma 573.25   gamma
#>            Accrual rate duration(s)       R     16       R
#>              Control hazard rate(s) lambdaC  0.001 lambdaC
#>             Control dropout rate(s)     eta      0     eta
#>        Experimental dropout rate(s)    etaE      0    etaE
#>  Event and dropout rate duration(s)       S   NULL       S