Fix `text_summary` under stratified design

[LittleBeannie]

The text_summary function doesn't capture the treatment effect pattern correctly when it is a stratified design. Following is a couple of examples where it fails and some suggested ways to get it corrected.

2 strata with PH

gs_design_ahr

x <- gs_design_ahr(
  enroll_rate = define_enroll_rate(stratum = c("A", "B"), duration = c(12, 12), rate = c(1, 1)),
  fail_rate = define_fail_rate(stratum = c("A", "B"),
                               duration = c(Inf, Inf), 
                               fail_rate = log(2)/c(9, 18), 
                               hr = c(0.8, 0.6), 
                               dropout_rate = 0.001),
  alpha = 0.025,
  beta = 0.1,
  info_frac = NULL,
  analysis_time = c(24, 36),
  ratio = 1,
  binding = FALSE,
  upper = gs_spending_bound,
  upar = list(sf = gsDesign::sfLDOF, total_spend = 0.025),
  lower = gs_spending_bound,
  lpar = list(sf = gsDesign::sfLDOF, total_spend = 0.1),
  h1_spending = TRUE,
  test_upper = TRUE,
  test_lower = TRUE,
  info_scale = "h0_h1_info")

> x |> text_summary()
[1] "Asymmetric two-sided group sequential design with non-binding futility bound, 2 analyses, time-to-event outcome with sample size 538.3 and 388.2 events, 90 percent power, 2.5 percent (1-sided) Type I error to detect hazard ratio of 0.8 during the first Inf months and 0.6 thereafter. Enrollment and total study durations are assumed to be 24 and 36 months, respectively. Efficacy bounds derived using a Lan-DeMets O'Brien-Fleming approximation spending function (no parameters). Futility bounds derived using a Lan-DeMets O'Brien-Fleming approximation spending function (no parameters)."

The sentence "detect hazard ratio of 0.8 during the first Inf months and 0.6 thereafter" is not correct, which is suggested to be "detect hazard ratio of 0.8 in stratum A and 0.6 in stratum B".

gs_power_ahr

y <- gs_power_ahr(
  enroll_rate = x$enroll_rate,
  fail_rate = x$fail_rate,
  event = NULL,
  analysis_time = x$analysis$time,
  ratio = 1,
  binding = FALSE,
  upper = gs_spending_bound,
  upar = list(sf = gsDesign::sfLDOF, total_spend = 0.025),
  lower = gs_spending_bound,
  lpar = list(sf = gsDesign::sfLDOF, total_spend = 0.1),
  h1_spending = TRUE,
  test_upper = TRUE,
  test_lower = TRUE,
  info_scale = "h0_h1_info")

y |> text_summary()

[1] "Asymmetric two-sided group sequential design with non-binding futility bound, 2 analyses, time-to-event outcome with sample size 538.3 and 388.2 events, 2.5 percent (1-sided) Type I error. Enrollment and total study durations are assumed to be 24 and 36 months, respectively. Efficacy bounds derived using a Lan-DeMets O'Brien-Fleming approximation spending function (no parameters). Futility bounds derived using a Lan-DeMets O'Brien-Fleming approximation spending function (no parameters). With hazard ratio of 0.8 during the first Inf months and 0.6 thereafter, the power is 90 percent."

The sentence "With hazard ratio of 0.8 during the first Inf months and 0.6 thereafter" is not correct, which is suggested to be "With hazard ratio of 0.8 in stratum A and 0.6 in stratum B".

2 strata with 2-piece NPH

gs_design_ahr

x <- gs_design_ahr(
  enroll_rate = define_enroll_rate(stratum = c("A", "B"), duration = c(12, 12), rate = c(1, 1)),
  fail_rate = define_fail_rate(stratum = c("A", "A", "B", "B"),
                               duration = c(3, Inf, 3, Inf), 
                               fail_rate = log(2)/c(9, 9, 18, 18), 
                               hr = c(1, 0.8, 1, 0.6), 
                               dropout_rate = 0.001),
  alpha = 0.025,
  beta = 0.1,
  info_frac = NULL,
  analysis_time = c(24, 36),
  ratio = 1,
  binding = FALSE,
  upper = gs_spending_bound,
  upar = list(sf = gsDesign::sfLDOF, total_spend = 0.025),
  lower = gs_spending_bound,
  lpar = list(sf = gsDesign::sfLDOF, total_spend = 0.1),
  h1_spending = TRUE,
  test_upper = TRUE,
  test_lower = TRUE,
  info_scale = "h0_h1_info"
)

x |> text_summary()
[1] "Asymmetric two-sided group sequential design with non-binding futility bound, 2 analyses, time-to-event outcome with sample size 848.8 and 618.5 events, 90 percent power, 2.5 percent (1-sided) Type I error to detect hazard ratio of 1  during the first  3 months, 0.8  during the next  Inf months, 1  during the next  3 months  and  0.6  thereafter. Enrollment and total study durations are assumed to be 24 and 36 months, respectively. Efficacy bounds derived using a Lan-DeMets O'Brien-Fleming approximation spending function (no parameters). Futility bounds derived using a Lan-DeMets O'Brien-Fleming approximation spending function (no parameters)."

The sentence "detect hazard ratio of 1 during the first 3 months, 0.8 during the next Inf months, 1 during the next 3 months and 0.6 thereafter" is not correct, which is suggested to be "detect hazard ratio of 1 during the first 3 months, 0.8 thereafter in stratum A; hazard ratio of 1 during the first 3 months, 0.6 thereafter in stratum B".

gs_power_ahr

y <- gs_power_ahr(
  enroll_rate = x$enroll_rate,
  fail_rate = x$fail_rate,
  event = NULL,
  analysis_time = x$analysis$time,
  ratio = 1,
  binding = FALSE,
  upper = gs_spending_bound,
  upar = list(sf = gsDesign::sfLDOF, total_spend = 0.025),
  lower = gs_spending_bound,
  lpar = list(sf = gsDesign::sfLDOF, total_spend = 0.1),
  h1_spending = TRUE,
  test_upper = TRUE,
  test_lower = TRUE,
  info_scale = "h0_h1_info"
)

y |> text_summary()
[1] "Asymmetric two-sided group sequential design with non-binding futility bound, 2 analyses, time-to-event outcome with sample size 848.8 and 618.5 events, 2.5 percent (1-sided) Type I error. Enrollment and total study durations are assumed to be 24 and 36 months, respectively. Efficacy bounds derived using a Lan-DeMets O'Brien-Fleming approximation spending function (no parameters). Futility bounds derived using a Lan-DeMets O'Brien-Fleming approximation spending function (no parameters). With hazard ratio of 1  during the first  3 months, 0.8  during the next  Inf months, 1  during the next  3 months  and  0.6  thereafter, the power is 90 percent."

The sentence of "With hazard ratio of 1 during the first 3 months, 0.8 during the next Inf months, 1 during the next 3 months and 0.6 thereafter" is not correct, which is suggested to be "With hazard ratio of 1 during the first 3 months, 0.8 thereafter in stratum A; hazard ratio of 1 during the first 3 months, 0.6 thereafter in stratum B".

>2 strata with >=3 pieces NPH

For gs_design_ahr, we will have "detect piecewise hazard ratio in X strata", where X is the number of strata.
For gs_power_ahr, we will have "With piecewise hazard ratio in X strata", where X is the number of strata.

[jdblischak]

Do I also need to update the text summary of the enrollment rate when there is more than one strata?

gsDesign2/R/text_summary.R

Lines 183 to 188 in c92e9e2

	# ---------------------------------------- #
	# Add enrollment and study duration
	# ---------------------------------------- #
	out <- paste(out, ". Enrollment and total study durations are assumed to be ", round(sum(x$enroll_rate$duration), 1),
	" and ", round(max(x$analysis$time), 1), " ", time_unit, ", respectively.",
	sep = "")

For example, using one of your examples above, I think the duration of the enrollment period should be 12 months, but the text summary reports 24 months because it sums the duration per stratum:

library("gsDesign2")

x <- gs_design_ahr(
  enroll_rate = define_enroll_rate(
    stratum = c("A", "B"),
    duration = c(12, 12),
    rate = c(1, 1)
  ),
  fail_rate = define_fail_rate(
    stratum = c("A", "B"),
    duration = c(Inf, Inf),
    fail_rate = log(2)/c(9, 18),
    hr = c(0.8, 0.6),
    dropout_rate = 0.001
  ),
  alpha = 0.025,
  beta = 0.1,
  info_frac = NULL,
  analysis_time = c(24, 36),
  ratio = 1,
  binding = FALSE,
  upper = gs_spending_bound,
  upar = list(sf = gsDesign::sfLDOF, total_spend = 0.025),
  lower = gs_spending_bound,
  lpar = list(sf = gsDesign::sfLDOF, total_spend = 0.1),
  h1_spending = TRUE,
  test_upper = TRUE,
  test_lower = TRUE,
  info_scale = "h0_h1_info"
)

x$enroll_rate
## # A tibble: 2 × 3
##   stratum duration  rate
##   <chr>      <dbl> <dbl>
## 1 A             12  22.4
## 2 B             12  22.4
text_summary(x)
## [1] "Asymmetric two-sided group sequential design with non-binding futility bound, 2 analyses, time-to-event outcome with sample size 538.3 and 388.2 events, 90 percent power, 2.5 percent (1-sided) Type I error to detect hazard ratio of 0.8 during the first Inf months and 0.6 thereafter. Enrollment and total study durations are assumed to be 24 and 36 months, respectively. Efficacy bounds derived using a Lan-DeMets O'Brien-Fleming approximation spending function (no parameters). Futility bounds derived using a Lan-DeMets O'Brien-Fleming approximation spending function (no parameters)."