Conflicts of `R` and `targetN` in `gsSurvPower()`

[LittleBeannie]

Example Used

The following example assumes the total sample size is 500 with a randomization ratio of 3:2 (experimental:control). It is a efficacy only design. The median of control arm is 15 months and HR is 0.7. There are 3 analyses in total (2 interim analyses and 1 final analyses) which is decided by information fraction of 1/3, 2/3 and 1. The enrollment is 12 months with a ramp-up during the first 6 months.

We use gsSurvPower() to calculate the power.

x <- gsSurvPower(
  k = 3,
  test.type = 1,
  alpha = 0.025,
  sided = 1,
  astar = 0,
  sfu = gsDesign::sfLDOF,
  sfupar = NULL,
  sfl = gsDesign::sfHSD,
  sflpar = -2,
  sfharm = gsDesign::sfHSD,
  sfharmparam = -2,
  spending = "information",
  # treatment effect
  S = NULL,
  lambdaC = log(2)/15,
  hr = 0.7,
  hr0 = 1,
  # dropout
  eta = 0.001,
  etaE = NULL,
  # sample size is 500, which is a multiplier of 5
  gamma = c(1, 2, 3, 4), 
  R = c(2, 2, 2, 6),
  targetN = 500,
  # analysis timing
  targetEvents = c(100, 200, 300),
  # randomization ratio is 3:2 (experimental:control)
  ratio = 1.5,
  testUpper = TRUE,
  testLower = FALSE,
  testHarm = FALSE,
  method = "LachinFoulkes")

Issues

The above code generate the following error message:

Error in gsSurvPower(k = 3, test.type = 1, alpha = 0.025, sided = 1, astar = 0,  : 
  Cannot specify both R and targetN

If I set R = NULL, we have error message again, which is less informative.

Error in dimnames(x) <- dn : 
  length of 'dimnames' [1] not equal to array extent

According to the help page of gsSurvPower(), we have that

targetN
Target total sample size. When specified, R is uniformly rescaled so that sum(gamma * R) == targetN, preserving the relative duration of each enrollment period. This is a convenience for "what-if" analyses where the enrollment rate changes but the target sample size stays the same (or vice versa). Cannot be used together with an explicit R.

It emphazes that targetN can't be used together with an explicit R. However, it also says "R is uniformly rescaled so that sum(gamma * R) == targetN". This is confusuing. We need an example turtoring the usage of targetN.