This function uses the option "stop" for the error-handling behavior of the foreach loop. This will cause the entire function to stop when errors are encountered and return the first error encountered instead of returning errors for each individual simulation.
Usage
sim_gs_n(
n_sim = 1000,
sample_size = 500,
stratum = data.frame(stratum = "All", p = 1),
enroll_rate = data.frame(duration = c(2, 2, 10), rate = c(3, 6, 9)),
fail_rate = data.frame(stratum = "All", duration = c(3, 100), fail_rate = log(2)/c(9,
18), hr = c(0.9, 0.6), dropout_rate = rep(0.001, 2)),
block = rep(c("experimental", "control"), 2),
test = wlr,
cut = NULL,
...
)Arguments
- n_sim
Number of simulations to perform.
- sample_size
Total sample size per simulation.
- stratum
A data frame with stratum specified in
stratum, probability (incidence) of each stratum inp.- enroll_rate
Piecewise constant enrollment rates by time period. Note that these are overall population enrollment rates and the
stratumargument controls the random distribution between stratum.- fail_rate
Piecewise constant control group failure rates, hazard ratio for experimental vs. control, and dropout rates by stratum and time period.
- block
As in
sim_pw_surv(). Vector of treatments to be included in each block.- test
One or more test functions such as
wlr(),rmst(), ormilestone()(maxcombo()can only be applied by itself). If a single test function is provided, it will be applied at each cut. Alternatively a list of functions created bycreate_test(). The list form is experimental and currently limited. It only accepts one test per cutting (in the future multiple tests may be accepted), and all the tests must consistently return the same exact results (again this may be more flexible in the future). Importantly, note that the simulated data set is always passed as the first positional argument to each test function provided.- cut
A list of cutting functions created by
create_cut(), see examples.- ...
Arguments passed to the test function(s) provided by the argument
test.
Details
WARNING: This experimental function is a work-in-progress. The function arguments will change as we add additional features.
Examples
library(gsDesign2)
# Parameters for enrollment
enroll_rampup_duration <- 4 # Duration for enrollment ramp up
enroll_duration <- 16 # Total enrollment duration
enroll_rate <- define_enroll_rate(
duration = c(
enroll_rampup_duration,
enroll_duration - enroll_rampup_duration
),
rate = c(10, 30)
)
# Parameters for treatment effect
delay_effect_duration <- 3 # Delay treatment effect in months
median_ctrl <- 9 # Survival median of the control arm
median_exp <- c(9, 14) # Survival median of the experimental arm
dropout_rate <- 0.001
fail_rate <- define_fail_rate(
duration = c(delay_effect_duration, 100),
fail_rate = log(2) / median_ctrl,
hr = median_ctrl / median_exp,
dropout_rate = dropout_rate
)
# Other related parameters
alpha <- 0.025 # Type I error
beta <- 0.1 # Type II error
ratio <- 1 # Randomization ratio (experimental:control)
# Define cuttings of 2 IAs and 1 FA
# IA1
# The 1st interim analysis will occur at the later of the following 3 conditions:
# - At least 20 months have passed since the start of the study.
# - At least 100 events have occurred.
# - At least 20 months have elapsed after enrolling 200/400 subjects, with a
# minimum of 20 months follow-up.
# However, if events accumulation is slow, we will wait for a maximum of 24 months.
ia1_cut <- create_cut(
planned_calendar_time = 20,
target_event_overall = 100,
max_extension_for_target_event = 24,
min_n_overall = 200,
min_followup = 20
)
# IA2
# The 2nd interim analysis will occur at the later of the following 3 conditions:
# - At least 32 months have passed since the start of the study.
# - At least 250 events have occurred.
# - At least 10 months after IA1.
# However, if events accumulation is slow, we will wait for a maximum of 34 months.
ia2_cut <- create_cut(
planned_calendar_time = 32,
target_event_overall = 200,
max_extension_for_target_event = 34,
min_time_after_previous_analysis = 10
)
# FA
# The final analysis will occur at the later of the following 2 conditions:
# - At least 45 months have passed since the start of the study.
# - At least 300 events have occurred.
fa_cut <- create_cut(
planned_calendar_time = 45,
target_event_overall = 350
)
# Example 1: regular logrank test at all 3 analyses
sim_gs_n(
n_sim = 3,
sample_size = 400,
enroll_rate = enroll_rate,
fail_rate = fail_rate,
test = wlr,
cut = list(ia1 = ia1_cut, ia2 = ia2_cut, fa = fa_cut),
weight = fh(rho = 0, gamma = 0)
)
#> Backend uses sequential processing.
#> sim_id method parameter analysis cut_date n event estimate
#> 1 1 WLR FH(rho=0, gamma=0) 1 24.00000 400 250 -12.57078
#> 2 1 WLR FH(rho=0, gamma=0) 2 32.00000 400 310 -17.51259
#> 3 1 WLR FH(rho=0, gamma=0) 3 45.00000 400 358 -21.52904
#> 4 2 WLR FH(rho=0, gamma=0) 1 24.00000 400 220 -19.00067
#> 5 2 WLR FH(rho=0, gamma=0) 2 32.00000 400 293 -24.11786
#> 6 2 WLR FH(rho=0, gamma=0) 3 48.45114 400 350 -28.11068
#> 7 3 WLR FH(rho=0, gamma=0) 1 24.00000 400 230 -31.62822
#> 8 3 WLR FH(rho=0, gamma=0) 2 32.00000 400 293 -45.31045
#> 9 3 WLR FH(rho=0, gamma=0) 3 46.46267 400 350 -46.75292
#> se z info info0
#> 1 7.887852 1.593688 62.17600 62.50
#> 2 8.772686 1.996264 77.17742 77.50
#> 3 9.344122 2.304019 89.09244 89.25
#> 4 7.405081 2.565896 54.10909 55.00
#> 5 8.519054 2.831049 72.71672 73.25
#> 6 9.268839 3.032816 87.26857 87.50
#> 7 7.505597 4.213951 55.03930 57.25
#> 8 8.380172 5.406863 71.20137 73.25
#> 9 8.995231 5.197523 86.80229 87.25
# Example 2: weighted logrank test by FH(0, 0.5) at all 3 analyses
sim_gs_n(
n_sim = 3,
sample_size = 400,
enroll_rate = enroll_rate,
fail_rate = fail_rate,
test = wlr,
cut = list(ia1 = ia1_cut, ia2 = ia2_cut, fa = fa_cut),
weight = fh(rho = 0, gamma = 0.5)
)
#> Backend uses sequential processing.
#> sim_id method parameter analysis cut_date n event estimate
#> 1 1 WLR FH(rho=0, gamma=0.5) 1 24.00000 400 245 -16.50548
#> 2 1 WLR FH(rho=0, gamma=0.5) 2 32.00000 400 301 -23.42510
#> 3 1 WLR FH(rho=0, gamma=0.5) 3 48.63895 400 350 -29.26789
#> 4 2 WLR FH(rho=0, gamma=0.5) 1 24.00000 400 235 -11.77665
#> 5 2 WLR FH(rho=0, gamma=0.5) 2 32.00000 400 306 -19.93688
#> 6 2 WLR FH(rho=0, gamma=0.5) 3 45.00000 400 354 -21.77563
#> 7 3 WLR FH(rho=0, gamma=0.5) 1 24.00000 400 251 -10.39589
#> 8 3 WLR FH(rho=0, gamma=0.5) 2 32.00000 400 311 -15.69293
#> 9 3 WLR FH(rho=0, gamma=0.5) 3 45.00000 400 351 -23.93377
#> se z info info0
#> 1 4.328381 3.813315 18.88178 19.22492
#> 2 5.228555 4.480225 28.23240 28.52001
#> 3 5.941521 4.925993 38.32056 38.35251
#> 4 4.197528 2.805615 17.39599 17.73274
#> 5 5.343826 3.730824 29.31233 29.52026
#> 6 6.075010 3.584461 39.38479 39.39131
#> 7 4.461681 2.330039 19.73170 20.02419
#> 8 5.461761 2.873236 30.26142 30.44120
#> 9 6.040813 3.962012 38.55789 38.69142
# Example 3: weighted logrank test by MB(3) at all 3 analyses
sim_gs_n(
n_sim = 3,
sample_size = 400,
enroll_rate = enroll_rate,
fail_rate = fail_rate,
test = wlr,
cut = list(ia1 = ia1_cut, ia2 = ia2_cut, fa = fa_cut),
weight = mb(delay = 3)
)
#> Backend uses sequential processing.
#> sim_id method parameter analysis cut_date n event
#> 1 1 WLR MB(delay = 3, max_weight = Inf) 1 24.00000 400 238
#> 2 1 WLR MB(delay = 3, max_weight = Inf) 2 32.00000 400 302
#> 3 1 WLR MB(delay = 3, max_weight = Inf) 3 47.15475 400 350
#> 4 2 WLR MB(delay = 3, max_weight = Inf) 1 24.00000 400 237
#> 5 2 WLR MB(delay = 3, max_weight = Inf) 2 32.00000 400 303
#> 6 2 WLR MB(delay = 3, max_weight = Inf) 3 45.20750 400 350
#> 7 3 WLR MB(delay = 3, max_weight = Inf) 1 24.00000 400 243
#> 8 3 WLR MB(delay = 3, max_weight = Inf) 2 32.00000 400 313
#> 9 3 WLR MB(delay = 3, max_weight = Inf) 3 45.00000 400 357
#> estimate se z info info0
#> 1 -18.60515 9.225778 2.016648 85.01425 85.94064
#> 2 -33.00297 10.453127 3.157234 109.63020 111.19639
#> 3 -39.37570 11.182331 3.521243 129.06298 129.84679
#> 4 -34.44971 9.123798 3.775808 82.54939 84.76665
#> 5 -33.74696 10.343061 3.262763 109.39914 109.92600
#> 6 -39.16912 11.112993 3.524624 127.51540 127.84250
#> 7 -11.15905 9.490882 1.175765 90.25296 90.68305
#> 8 -24.41722 10.826117 2.255400 118.18035 118.93501
#> 9 -20.40203 11.597863 1.759119 136.58643 136.69339
# Example 4: weighted logrank test by early zero (6) at all 3 analyses
sim_gs_n(
n_sim = 3,
sample_size = 400,
enroll_rate = enroll_rate,
fail_rate = fail_rate,
test = wlr,
cut = list(ia1 = ia1_cut, ia2 = ia2_cut, fa = fa_cut),
weight = early_zero(6)
)
#> Backend uses sequential processing.
#> sim_id method parameter analysis cut_date n
#> 1 1 WLR Xu 2017 with first 6 months of 0 weights 1 24.00000 400
#> 2 1 WLR Xu 2017 with first 6 months of 0 weights 2 32.00000 400
#> 3 1 WLR Xu 2017 with first 6 months of 0 weights 3 47.13787 400
#> 4 2 WLR Xu 2017 with first 6 months of 0 weights 1 24.00000 400
#> 5 2 WLR Xu 2017 with first 6 months of 0 weights 2 32.00000 400
#> 6 2 WLR Xu 2017 with first 6 months of 0 weights 3 45.00000 400
#> 7 3 WLR Xu 2017 with first 6 months of 0 weights 1 24.00000 400
#> 8 3 WLR Xu 2017 with first 6 months of 0 weights 2 32.00000 400
#> 9 3 WLR Xu 2017 with first 6 months of 0 weights 3 45.00000 400
#> event estimate se z info info0
#> 1 237 -18.920929 4.895593 3.8648903 22.08247 24.25
#> 2 292 -21.572976 6.083195 3.5463235 37.20395 38.00
#> 3 350 -22.773420 7.128240 3.1948166 52.32857 52.50
#> 4 228 -3.935264 4.452137 0.8839045 19.98750 20.00
#> 5 302 -15.029990 6.131008 2.4514713 37.97386 38.25
#> 6 356 -20.604103 7.031002 2.9304649 51.98077 52.00
#> 7 232 -18.075149 4.637207 3.8978528 21.01124 22.25
#> 8 296 -23.442295 6.003295 3.9049051 37.97386 38.25
#> 9 355 -33.405996 6.903375 4.8390814 52.95755 53.00
# Example 5: RMST at all 3 analyses
sim_gs_n(
n_sim = 3,
sample_size = 400,
enroll_rate = enroll_rate,
fail_rate = fail_rate,
test = rmst,
cut = list(ia1 = ia1_cut, ia2 = ia2_cut, fa = fa_cut),
tau = 20
)
#> Backend uses sequential processing.
#> sim_id method parameter analysis cut_date n event estimate se
#> 1 1 RMST 20 1 24.00000 400 219 1.851347 0.7877281
#> 2 1 RMST 20 2 32.00000 400 289 1.580564 0.7638273
#> 3 1 RMST 20 3 48.05091 400 350 1.585474 0.7629744
#> 4 2 RMST 20 1 24.00000 400 246 2.586267 0.7527348
#> 5 2 RMST 20 2 32.00000 400 312 2.587050 0.7150500
#> 6 2 RMST 20 3 45.00000 400 359 2.584614 0.7151244
#> 7 3 RMST 20 1 24.00000 400 255 1.073489 0.7554547
#> 8 3 RMST 20 2 32.00000 400 307 1.093229 0.7386015
#> 9 3 RMST 20 3 45.73872 400 350 1.078624 0.7385753
#> z
#> 1 2.350235
#> 2 2.069269
#> 3 2.078017
#> 4 3.435827
#> 5 3.617999
#> 6 3.614216
#> 7 1.420985
#> 8 1.480133
#> 9 1.460411
# Example 6: Milestone at all 3 analyses
sim_gs_n(
n_sim = 3,
sample_size = 400,
enroll_rate = enroll_rate,
fail_rate = fail_rate,
test = milestone,
cut = list(ia1 = ia1_cut, ia2 = ia2_cut, fa = fa_cut),
ms_time = 10
)
#> Backend uses sequential processing.
#> sim_id method parameter analysis cut_date n event estimate se
#> 1 1 milestone 10 1 24.00000 400 246 0.1580116 0.1447503
#> 2 1 milestone 10 2 32.00000 400 303 0.1795608 0.1431238
#> 3 1 milestone 10 3 45.82652 400 350 0.1795608 0.1431238
#> 4 2 milestone 10 1 24.00000 400 224 0.2113400 0.1533437
#> 5 2 milestone 10 2 32.00000 400 294 0.2024538 0.1491677
#> 6 2 milestone 10 3 49.28090 400 350 0.2024538 0.1491677
#> 7 3 milestone 10 1 24.00000 400 236 0.5697039 0.1515794
#> 8 3 milestone 10 2 32.00000 400 302 0.5343102 0.1489729
#> 9 3 milestone 10 3 45.00000 400 353 0.5343102 0.1489729
#> z
#> 1 1.091615
#> 2 1.254583
#> 3 1.254583
#> 4 1.378211
#> 5 1.357223
#> 6 1.357223
#> 7 3.758453
#> 8 3.586626
#> 9 3.586626
# Warning: this example will be executable when we add info info0 to the milestone test
# Example 7: WLR with fh(0, 0.5) test at IA1,
# WLR with mb(6, Inf) at IA2, and milestone test at FA
ia1_test <- create_test(wlr, weight = fh(rho = 0, gamma = 0.5))
ia2_test <- create_test(wlr, weight = mb(delay = 6, w_max = Inf))
fa_test <- create_test(milestone, ms_time = 10)
if (FALSE) { # \dontrun{
sim_gs_n(
n_sim = 3,
sample_size = 400,
enroll_rate = enroll_rate,
fail_rate = fail_rate,
test = list(ia1 = ia1_test, ia2 = ia2_test, fa = fa_test),
cut = list(ia1 = ia1_cut, ia2 = ia2_cut, fa = fa_cut)
)
} # }
# WARNING: Multiple tests per cut will be enabled in a future version.
# Currently does not work.
# Example 8: At IA1, we conduct 3 tests, LR, WLR with fh(0, 0.5), and RMST test.
# At IA2, we conduct 2 tests, LR and WLR with early zero (6).
# At FA, we conduct 2 tests, LR and milestone test.
ia1_test <- list(
test1 = create_test(wlr, weight = fh(rho = 0, gamma = 0)),
test2 = create_test(wlr, weight = fh(rho = 0, gamma = 0.5)),
test3 = create_test(rmst, tau = 20)
)
ia2_test <- list(
test1 = create_test(wlr, weight = fh(rho = 0, gamma = 0)),
test2 = create_test(wlr, weight = early_zero(6))
)
fa_test <- list(
test1 = create_test(wlr, weight = fh(rho = 0, gamma = 0)),
test3 = create_test(milestone, ms_time = 20)
)
if (FALSE) { # \dontrun{
sim_gs_n(
n_sim = 3,
sample_size = 400,
enroll_rate = enroll_rate,
fail_rate = fail_rate,
test = list(ia1 = ia1_test, ia2 = ia2_test, fa = fa_test),
cut = list(ia1 = ia1_cut, ia2 = ia2_cut, fa = fa_cut)
)
} # }
# Example 9: regular logrank test at all 3 analyses in parallel
plan("multisession", workers = 2)
sim_gs_n(
n_sim = 3,
sample_size = 400,
enroll_rate = enroll_rate,
fail_rate = fail_rate,
test = wlr,
cut = list(ia1 = ia1_cut, ia2 = ia2_cut, fa = fa_cut),
weight = fh(rho = 0, gamma = 0)
)
#> Using 2 cores with backend multisession
#> sim_id method parameter analysis cut_date n event estimate
#> 1 1 WLR FH(rho=0, gamma=0) 1 24.00000 400 248 -26.3733415
#> 2 1 WLR FH(rho=0, gamma=0) 2 32.00000 400 297 -33.7139897
#> 3 1 WLR FH(rho=0, gamma=0) 3 49.48058 400 350 -43.5100032
#> 4 2 WLR FH(rho=0, gamma=0) 1 24.00000 400 252 -16.6522149
#> 5 2 WLR FH(rho=0, gamma=0) 2 32.00000 400 311 -27.3457636
#> 6 2 WLR FH(rho=0, gamma=0) 3 45.00000 400 365 -30.7707629
#> 7 3 WLR FH(rho=0, gamma=0) 1 24.00000 400 244 -0.7435234
#> 8 3 WLR FH(rho=0, gamma=0) 2 32.00000 400 309 -11.1651888
#> 9 3 WLR FH(rho=0, gamma=0) 3 45.82981 400 350 -14.0634534
#> se z info info0
#> 1 7.819346 3.37283233 61.09274 62.00
#> 2 8.529700 3.95254108 73.33333 74.25
#> 3 9.120774 4.77042874 86.94000 87.50
#> 4 7.901828 2.10738769 62.32937 63.00
#> 5 8.711323 3.13910551 76.97749 77.75
#> 6 9.333920 3.29666040 90.77747 91.00
#> 7 7.804786 0.09526506 60.96311 61.00
#> 8 8.758474 1.27478698 77.01618 77.25
#> 9 9.286413 1.51441180 87.39714 87.50
plan("sequential")