# Time-to-event endpoint design with calendar timing of analyses

Source:`R/gsSurvCalendar.R`

`gsSurvCalendar.Rd`

Time-to-event endpoint design with calendar timing of analyses

## Usage

```
gsSurvCalendar(
test.type = 4,
alpha = 0.025,
sided = 1,
beta = 0.1,
astar = 0,
sfu = gsDesign::sfHSD,
sfupar = -4,
sfl = gsDesign::sfHSD,
sflpar = -2,
calendarTime = c(12, 24, 36),
spending = c("information", "calendar"),
lambdaC = log(2)/6,
hr = 0.6,
hr0 = 1,
eta = 0,
etaE = NULL,
gamma = 1,
R = 12,
S = NULL,
minfup = 18,
ratio = 1,
r = 18,
tol = 1e-06
)
```

## Arguments

- test.type
Test type. See

`gsSurv`

.- alpha
Type I error rate. Default is 0.025 since 1-sided testing is default.

- sided
`1`

for 1-sided testing,`2`

for 2-sided testing.- beta
Type II error rate. Default is 0.10 (90% power);

`NULL`

if power is to be computed based on other input values.- astar
Normally not specified. If

`test.type = 5`

or`6`

,`astar`

specifies the total probability of crossing a lower bound at all analyses combined. This will be changed to`1 - alpha`

when default value of`0`

is used. Since this is the expected usage, normally`astar`

is not specified by the user.- sfu
A spending function or a character string indicating a boundary type (that is,

`"WT"`

for Wang-Tsiatis bounds,`"OF"`

for O'Brien-Fleming bounds and`"Pocock"`

for Pocock bounds). For one-sided and symmetric two-sided testing is used to completely specify spending (`test.type = 1`

,`2`

),`sfu`

. The default value is`sfHSD`

which is a Hwang-Shih-DeCani spending function.- sfupar
Real value, default is

`-4`

which is an O'Brien-Fleming-like conservative bound when used with the default Hwang-Shih-DeCani spending function. This is a real-vector for many spending functions. The parameter`sfupar`

specifies any parameters needed for the spending function specified by`sfu`

; this will be ignored for spending functions (`sfLDOF`

,`sfLDPocock`

) or bound types (`"OF"`

,`"Pocock"`

) that do not require parameters.- sfl
Specifies the spending function for lower boundary crossing probabilities when asymmetric, two-sided testing is performed (

`test.type = 3`

,`4`

,`5`

, or`6`

). Unlike the upper bound, only spending functions are used to specify the lower bound. The default value is`sfHSD`

which is a Hwang-Shih-DeCani spending function. The parameter`sfl`

is ignored for one-sided testing (`test.type = 1`

) or symmetric 2-sided testing (`test.type = 2`

).- sflpar
Real value, default is

`-2`

, which, with the default Hwang-Shih-DeCani spending function, specifies a less conservative spending rate than the default for the upper bound.- calendarTime
Vector of increasing positive numbers with calendar times of analyses. Time 0 is start of randomization.

- spending
Select between calendar-based spending and information-based spending.

- lambdaC
Scalar, vector or matrix of event hazard rates for the control group; rows represent time periods while columns represent strata; a vector implies a single stratum.

- hr
Hazard ratio (experimental/control) under the alternate hypothesis (scalar).

- hr0
Hazard ratio (experimental/control) under the null hypothesis (scalar).

- eta
Scalar, vector or matrix of dropout hazard rates for the control group; rows represent time periods while columns represent strata; if entered as a scalar, rate is constant across strata and time periods; if entered as a vector, rates are constant across strata.

- etaE
Matrix dropout hazard rates for the experimental group specified in like form as

`eta`

; if`NULL`

, this is set equal to`eta`

.- gamma
A scalar, vector or matrix of rates of entry by time period (rows) and strata (columns); if entered as a scalar, rate is constant across strata and time periods; if entered as a vector, rates are constant across strata.

- R
A scalar or vector of durations of time periods for recruitment rates specified in rows of

`gamma`

. Length is the same as number of rows in`gamma`

. Note that when variable enrollment duration is specified (input`T = NULL`

), the final enrollment period is extended as long as needed.- S
A scalar or vector of durations of piecewise constant event rates specified in rows of

`lambda`

,`eta`

and`etaE`

; this is`NULL`

if there is a single event rate per stratum (exponential failure) or length of the number of rows in`lambda`

minus 1, otherwise.- minfup
A non-negative scalar less than the maximum value in

`calendarTime`

. Enrollment will be cut off at the difference between the maximum value in`calendarTime`

and`minfup`

.- ratio
Randomization ratio of experimental treatment divided by control; normally a scalar, but may be a vector with length equal to number of strata.

- r
Integer value controlling grid for numerical integration as in Jennison and Turnbull (2000); default is 18, range is 1 to 80. Larger values provide larger number of grid points and greater accuracy. Normally

`r`

will not be changed by the user.- tol
Tolerance for error passed to the

`gsDesign`

function.

## Examples

```
# First example: while timing is calendar-based, spending is event-based
x <- gsSurvCalendar() %>% toInteger()
gsBoundSummary(x)
#> Analysis Value Efficacy Futility
#> IA 1: 29% Z 3.0856 -0.4349
#> N: 130 p (1-sided) 0.0010 0.6682
#> Events: 50 ~HR at bound 0.4178 1.1309
#> Month: 12 P(Cross) if HR=1 0.0010 0.3318
#> P(Cross) if HR=0.6 0.1018 0.0122
#> IA 2: 79% Z 2.3279 1.3991
#> N: 194 p (1-sided) 0.0100 0.0809
#> Events: 137 ~HR at bound 0.6718 0.7874
#> Month: 24 P(Cross) if HR=1 0.0106 0.9213
#> P(Cross) if HR=0.6 0.7505 0.0606
#> Final Z 2.0154 2.0154
#> N: 194 p (1-sided) 0.0219 0.0219
#> Events: 173 ~HR at bound 0.7361 0.7361
#> Month: 36 P(Cross) if HR=1 0.0228 0.9772
#> P(Cross) if HR=0.6 0.9001 0.0999
# Second example: both timing and spending are calendar-based
# This results in less spending at interims and leaves more for final analysis
y <- gsSurvCalendar(spending = "calendar") %>% toInteger()
gsBoundSummary(y)
#> Analysis Value Efficacy Futility
#> IA 1: 29% Z 3.0107 -0.3784
#> N: 126 p (1-sided) 0.0013 0.6474
#> Events: 49 ~HR at bound 0.4231 1.1142
#> Month: 12 P(Cross) if HR=1 0.0013 0.3526
#> P(Cross) if HR=0.6 0.1123 0.0148
#> IA 2: 79% Z 2.5581 1.1380
#> N: 188 p (1-sided) 0.0053 0.1276
#> Events: 133 ~HR at bound 0.6417 0.8209
#> Month: 24 P(Cross) if HR=1 0.0062 0.8785
#> P(Cross) if HR=0.6 0.6593 0.0437
#> Final Z 1.9854 1.9854
#> N: 188 p (1-sided) 0.0235 0.0235
#> Events: 168 ~HR at bound 0.7361 0.7361
#> Month: 36 P(Cross) if HR=1 0.0237 0.9763
#> P(Cross) if HR=0.6 0.9006 0.0994
# Note that calendar timing for spending relates to planned timing for y
# rather than timing in y after toInteger() conversion
# Values plugged into spending function for calendar time
y$usTime
#> [1] 0.3333333 0.6666667 1.0000000
# Actual calendar fraction from design after toInteger() conversion
y$T / max(y$T)
#> [1] 0.3317245 0.6637292 1.0000000
```