API of `sim_pw_surv`

[LittleBeannie]

In gsDesign2, the failure rate and dropout rate are consolidated into a single table named fail_rate. However, in simtrial::sim_pw_surv, users are asked to input the failure rate and dropout rate separately, as shown below:

sim_pw_surv(n = 100, stratum = data.frame(stratum = "All", p = 1), block = c(rep("control", 2), rep("experimental", 2)),
          enroll_rate = data.frame(rate = 9, duration = 1),
          fail_rate = data.frame(stratum = rep("All", 4), period = rep(1:2, 2), treatment = c(rep("control", 2), rep("experimental", 2)),
                                 duration = rep(c(3, 1), 2), rate = log(2) / c(9, 9, 9, 18)),
          dropout_rate = data.frame(stratum = rep("All", 2), period = rep(1, 2), treatment = c("control", "experimental"),
                                  duration = rep(100, 2), rate = rep(.001, 2)))

It's important to mention that the table fail_rate and dropout_rate mentioned earlier includes a period column, which is not present in gsDesign2. To link gsDesign2 to simtrial, we utilize a function called to_sim_pw_surv.

xx <- to_sim_pw_surv(design$fail_rate)
sim_pw_surv(n = 100, stratum = data.frame(stratum = "All", p = 1), 
           enroll_rate = data.frame(rate = 9, duration = 1), block = c(rep("control", 2), rep("experimental", 2)),
           fail_rate = xx$fail_rate,
           dropout_rate = xx$dropout_rate)

I am considering whether we should align the API of sim_pw_surv with that of gsDesign2, such as

sim_pw_surv(n = 100, stratum = data.frame(stratum = "All", p = 1), 
           enroll_rate = data.frame(rate = 9, duration = 1), block = c(rep("control", 2), rep("experimental", 2)),
           fail_rate = data.frame(duration = ..., fail_rate = ..., hr = ..., dropout_rate = ...))

In this way, we could implement to_sim_pw_surv inside of sim_pw_surv, i.e.,

sim_pw_surv <- function(...) {
  # convert gsDeisgn2 fail rate table to simtrial fail and dropout table
  xx <- to_sim_pw_surv(fail_rate)
  ...
}

[LittleBeannie]

Decision: we will keep the API of sim_pw_surv as it is, as it provides more flexibility to allow the change points of dropout rate differs from the fail rate.