Package 'gsDesign2'

Average hazard ratio under non-proportional hazards

Description

Provides a geometric average hazard ratio under various non-proportional hazards assumptions for either single or multiple strata studies. The piecewise exponential distribution allows a simple method to specify a distribution and enrollment pattern where the enrollment, failure and dropout rates changes over time.

Usage

ahr(
  enroll_rate = define_enroll_rate(duration = c(2, 2, 10), rate = c(3, 6, 9)),
  fail_rate = define_fail_rate(duration = c(3, 100), fail_rate = log(2)/c(9, 18), hr =
    c(0.9, 0.6), dropout_rate = 0.001),
  total_duration = 30,
  ratio = 1
)

Arguments

enroll_rate	An enroll_rate data frame with or without stratum created by define_enroll_rate().
fail_rate	A fail_rate data frame with or without stratum created by define_fail_rate().
total_duration	Total follow-up from start of enrollment to data cutoff; this can be a single value or a vector of positive numbers.
ratio	Experimental:Control randomization ratio.

Value

A data frame with time (from total_duration), ahr (average hazard ratio), n (sample size), event (expected number of events), info (information under given scenarios), and info0 (information under related null hypothesis) for each value of total_duration input.

Specification

The contents of this section are shown in PDF user manual only.

Examples

# Example 1: default
ahr()

# Example 2: default with multiple analysis times (varying total_duration)
ahr(total_duration = c(15, 30))

# Example 3: stratified population
enroll_rate <- define_enroll_rate(
  stratum = c(rep("Low", 2), rep("High", 3)),
  duration = c(2, 10, 4, 4, 8),
  rate = c(5, 10, 0, 3, 6)
)
fail_rate <- define_fail_rate(
  stratum = c(rep("Low", 2), rep("High", 2)),
  duration = c(1, Inf, 1, Inf),
  fail_rate = c(.1, .2, .3, .4),
  dropout_rate = .001,
  hr = c(.9, .75, .8, .6)
)
ahr(enroll_rate = enroll_rate, fail_rate = fail_rate, total_duration = c(15, 30))

---

Blinded estimation of average hazard ratio

Description

Based on blinded data and assumed hazard ratios in different intervals, compute a blinded estimate of average hazard ratio (AHR) and corresponding estimate of statistical information. This function is intended for use in computing futility bounds based on spending assuming the input hazard ratio (hr) values for intervals specified here.

Usage

ahr_blinded(
  surv = survival::Surv(time = simtrial::ex1_delayed_effect$month, event =
    simtrial::ex1_delayed_effect$evntd),
  intervals = c(3, Inf),
  hr = c(1, 0.6),
  ratio = 1
)

Arguments

surv	Input survival object (see survival::Surv()); note that only 0 = censored, 1 = event for survival::Surv().
intervals	Vector containing positive values indicating interval lengths where the exponential rates are assumed. Note that a final infinite interval is added if any events occur after the final interval specified.
hr	Vector of hazard ratios assumed for each interval.
ratio	Ratio of experimental to control randomization.

Value

A tibble with one row containing

• ahr - Blinded average hazard ratio based on assumed period-specific hazard ratios input in fail_rate and observed events in the corresponding intervals.

• event - Total observed number of events.

• info0 - Information under related null hypothesis.

• theta - Natural parameter for group sequential design representing expected incremental drift at all analyses.

Specification

The contents of this section are shown in PDF user manual only.

Examples

ahr_blinded(
  surv = survival::Surv(
    time = simtrial::ex2_delayed_effect$month,
    event = simtrial::ex2_delayed_effect$evntd
  ),
  intervals = c(4, 100),
  hr = c(1, .55),
  ratio = 1
)

---

Convert summary table of a fixed or group sequential design object to a gt object

Description

Convert summary table of a fixed or group sequential design object to a gt object

Usage

as_gt(x, ...)

## S3 method for class 'fixed_design_summary'
as_gt(x, title = NULL, footnote = NULL, ...)

## S3 method for class 'gs_design_summary'
as_gt(
  x,
  title = NULL,
  subtitle = NULL,
  colname_spanner = "Cumulative boundary crossing probability",
  colname_spannersub = c("Alternate hypothesis", "Null hypothesis"),
  footnote = NULL,
  display_bound = c("Efficacy", "Futility"),
  display_columns = NULL,
  display_inf_bound = FALSE,
  ...
)

Arguments

x	A summary object of a fixed or group sequential design.
...	Additional arguments (not used).
title	A string to specify the title of the gt table.
footnote	A list containing content, location, and attr. content is a vector of string to specify the footnote text; location is a vector of string to specify the locations to put the superscript of the footnote index; attr is a vector of string to specify the attributes of the footnotes, for example, c("colname", "title", "subtitle", "analysis", "spanner"); users can use the functions in the gt package to customize the table. To disable footnotes, use footnote = FALSE.
subtitle	A string to specify the subtitle of the gt table.
colname_spanner	A string to specify the spanner of the gt table.
colname_spannersub	A vector of strings to specify the spanner details of the gt table.
display_bound	A vector of strings specifying the label of the bounds. The default is c("Efficacy", "Futility").
display_columns	A vector of strings specifying the variables to be displayed in the summary table.
display_inf_bound	Logical, whether to display the +/-inf bound.

Value

A gt_tbl object.

Examples

# Fixed design examples ----

# Enrollment rate
enroll_rate <- define_enroll_rate(
  duration = 18,
  rate = 20
)

# Failure rates
fail_rate <- define_fail_rate(
  duration = c(4, 100),
  fail_rate = log(2) / 12,
  dropout_rate = .001,
  hr = c(1, .6)
)

# Study duration in months
study_duration <- 36

# Experimental / Control randomization ratio
ratio <- 1

# 1-sided Type I error
alpha <- 0.025

# Type II error (1 - power)
beta <- 0.1

# Example 1 ----
fixed_design_ahr(
  alpha = alpha, power = 1 - beta,
  enroll_rate = enroll_rate, fail_rate = fail_rate,
  study_duration = study_duration, ratio = ratio
) |>
  summary() |>
  as_gt()

# Example 2 ----
fixed_design_fh(
  alpha = alpha, power = 1 - beta,
  enroll_rate = enroll_rate, fail_rate = fail_rate,
  study_duration = study_duration, ratio = ratio
) |>
  summary() |>
  as_gt()

# Group sequential design examples ---

# Example 1 ----
# The default output

gs_design_ahr() |>
  summary() |>
  as_gt()

gs_power_ahr(lpar = list(sf = gsDesign::sfLDOF, total_spend = 0.1)) |>
  summary() |>
  as_gt()

gs_design_wlr() |>
  summary() |>
  as_gt()

gs_power_wlr(lpar = list(sf = gsDesign::sfLDOF, total_spend = 0.1)) |>
  summary() |>
  as_gt()

gs_power_combo() |>
  summary() |>
  as_gt()

gs_design_rd() |>
  summary() |>
  as_gt()

gs_power_rd() |>
  summary() |>
  as_gt()

# Example 2 ----
# Usage of title = ..., subtitle = ...
# to edit the title/subtitle
gs_power_wlr(lpar = list(sf = gsDesign::sfLDOF, total_spend = 0.1)) |>
  summary() |>
  as_gt(
    title = "Bound Summary",
    subtitle = "from gs_power_wlr"
  )

# Example 3 ----
# Usage of colname_spanner = ..., colname_spannersub = ...
# to edit the spanner and its sub-spanner
gs_power_wlr(lpar = list(sf = gsDesign::sfLDOF, total_spend = 0.1)) |>
  summary() |>
  as_gt(
    colname_spanner = "Cumulative probability to cross boundaries",
    colname_spannersub = c("under H1", "under H0")
  )

# Example 4 ----
# Usage of footnote = ...
# to edit the footnote
gs_power_wlr(lpar = list(sf = gsDesign::sfLDOF, total_spend = 0.1)) |>
  summary() |>
  as_gt(
    footnote = list(
      content = c(
        "approximate weighted hazard ratio to cross bound.",
        "wAHR is the weighted AHR.",
        "the crossing probability.",
        "this table is generated by gs_power_wlr."
      ),
      location = c("~wHR at bound", NA, NA, NA),
      attr = c("colname", "analysis", "spanner", "title")
    )
  )

# Example 5 ----
# Usage of display_bound = ...
# to either show efficacy bound or futility bound, or both(default)
gs_power_wlr(lpar = list(sf = gsDesign::sfLDOF, total_spend = 0.1)) |>
  summary() |>
  as_gt(display_bound = "Efficacy")

# Example 6 ----
# Usage of display_columns = ...
# to select the columns to display in the summary table
gs_power_wlr(lpar = list(sf = gsDesign::sfLDOF, total_spend = 0.1)) |>
  summary() |>
  as_gt(display_columns = c("Analysis", "Bound", "Nominal p", "Z", "Probability"))

---

Write summary table of a fixed or group sequential design object to an RTF file

Description

Write summary table of a fixed or group sequential design object to an RTF file

Usage

as_rtf(x, ...)

## S3 method for class 'fixed_design_summary'
as_rtf(
  x,
  title = NULL,
  footnote = NULL,
  col_rel_width = NULL,
  orientation = c("portrait", "landscape"),
  text_font_size = 9,
  file,
  ...
)

## S3 method for class 'gs_design_summary'
as_rtf(
  x,
  title = NULL,
  subtitle = NULL,
  colname_spanner = "Cumulative boundary crossing probability",
  colname_spannersub = c("Alternate hypothesis", "Null hypothesis"),
  footnote = NULL,
  display_bound = c("Efficacy", "Futility"),
  display_columns = NULL,
  display_inf_bound = TRUE,
  col_rel_width = NULL,
  orientation = c("portrait", "landscape"),
  text_font_size = 9,
  file,
  ...
)

Arguments

x	A summary object of a fixed or group sequential design.
...	Additional arguments (not used).
title	A string to specify the title of the RTF table.
footnote	A list containing content, location, and attr. content is a vector of string to specify the footnote text; location is a vector of string to specify the locations to put the superscript of the footnote index; attr is a vector of string to specify the attributes of the footnotes, for example, c("colname", "title", "subtitle", "analysis", "spanner"); users can use the functions in the gt package to customize the table.
col_rel_width	Column relative width in a vector e.g. c(2,1,1) refers to 2:1:1. Default is NULL for equal column width.
orientation	Orientation in 'portrait' or 'landscape'.
text_font_size	Text font size. To vary text font size by column, use numeric vector with length of vector equal to number of columns displayed e.g. c(9,20,40).
file	File path for the output.
subtitle	A string to specify the subtitle of the RTF table.
colname_spanner	A string to specify the spanner of the RTF table.
colname_spannersub	A vector of strings to specify the spanner details of the RTF table.
display_bound	A vector of strings specifying the label of the bounds. The default is c("Efficacy", "Futility").
display_columns	A vector of strings specifying the variables to be displayed in the summary table.
display_inf_bound	Logical, whether to display the +/-inf bound.

Value

as_rtf() returns the input x invisibly.

Examples

# Enrollment rate
enroll_rate <- define_enroll_rate(
  duration = 18,
  rate = 20
)

# Failure rates
fail_rate <- define_fail_rate(
  duration = c(4, 100),
  fail_rate = log(2) / 12,
  dropout_rate = .001,
  hr = c(1, .6)
)

# Study duration in months
study_duration <- 36

# Experimental / Control randomization ratio
ratio <- 1

# 1-sided Type I error
alpha <- 0.025

# Type II error (1 - power)
beta <- 0.1

# AHR ----
# under fixed power
x <- fixed_design_ahr(
  alpha = alpha, power = 1 - beta,
  enroll_rate = enroll_rate, fail_rate = fail_rate,
  study_duration = study_duration, ratio = ratio
) |> summary()
x |> as_rtf(file = tempfile(fileext = ".rtf"))
x |> as_rtf(title = "Fixed design", file = tempfile(fileext = ".rtf"))
x |> as_rtf(
  footnote = "Power computed with average hazard ratio method given the sample size",
  file = tempfile(fileext = ".rtf")
)
x |> as_rtf(text_font_size = 10, file = tempfile(fileext = ".rtf"))

# FH ----
# under fixed power
fixed_design_fh(
  alpha = alpha, power = 1 - beta,
  enroll_rate = enroll_rate, fail_rate = fail_rate,
  study_duration = study_duration, ratio = ratio
) |>
  summary() |>
  as_rtf(file = tempfile(fileext = ".rtf"))
#'

# the default output

gs_design_ahr() |>
  summary() |>
  as_rtf(file = tempfile(fileext = ".rtf"))

gs_power_ahr(lpar = list(sf = gsDesign::sfLDOF, total_spend = 0.1)) |>
  summary() |>
  as_rtf(file = tempfile(fileext = ".rtf"))

gs_design_wlr() |>
  summary() |>
  as_rtf(file = tempfile(fileext = ".rtf"))

gs_power_wlr(lpar = list(sf = gsDesign::sfLDOF, total_spend = 0.1)) |>
  summary() |>
  as_rtf(file = tempfile(fileext = ".rtf"))


gs_power_combo() |>
  summary() |>
  as_rtf(file = tempfile(fileext = ".rtf"))

gs_design_rd() |>
  summary() |>
  as_rtf(file = tempfile(fileext = ".rtf"))

gs_power_rd() |>
  summary() |>
  as_rtf(file = tempfile(fileext = ".rtf"))

# usage of title = ..., subtitle = ...
# to edit the title/subtitle
gs_power_wlr(lpar = list(sf = gsDesign::sfLDOF, total_spend = 0.1)) |>
  summary() |>
  as_rtf(
    title = "Bound Summary",
    subtitle = "from gs_power_wlr",
    file = tempfile(fileext = ".rtf")
  )

# usage of colname_spanner = ..., colname_spannersub = ...
# to edit the spanner and its sub-spanner
gs_power_wlr(lpar = list(sf = gsDesign::sfLDOF, total_spend = 0.1)) |>
  summary() |>
  as_rtf(
    colname_spanner = "Cumulative probability to cross boundaries",
    colname_spannersub = c("under H1", "under H0"),
    file = tempfile(fileext = ".rtf")
  )

# usage of footnote = ...
# to edit the footnote
gs_power_wlr(lpar = list(sf = gsDesign::sfLDOF, total_spend = 0.1)) |>
  summary() |>
  as_rtf(
    footnote = list(
      content = c(
        "approximate weighted hazard ratio to cross bound.",
        "wAHR is the weighted AHR.",
        "the crossing probability.",
        "this table is generated by gs_power_wlr."
      ),
      location = c("~wHR at bound", NA, NA, NA),
      attr = c("colname", "analysis", "spanner", "title")
    ),
    file = tempfile(fileext = ".rtf")
  )

# usage of display_bound = ...
# to either show efficacy bound or futility bound, or both(default)
gs_power_wlr(lpar = list(sf = gsDesign::sfLDOF, total_spend = 0.1)) |>
  summary() |>
  as_rtf(
    display_bound = "Efficacy",
    file = tempfile(fileext = ".rtf")
  )

# usage of display_columns = ...
# to select the columns to display in the summary table
gs_power_wlr(lpar = list(sf = gsDesign::sfLDOF, total_spend = 0.1)) |>
  summary() |>
  as_rtf(
    display_columns = c("Analysis", "Bound", "Nominal p", "Z", "Probability"),
    file = tempfile(fileext = ".rtf")
  )

---

Define enrollment rate

Description

Define the enrollment rate of subjects for a study as following a piecewise exponential distribution.

Usage

define_enroll_rate(duration, rate, stratum = "All")

Arguments

duration	A numeric vector of ordered piecewise study duration interval.
rate	A numeric vector of enrollment rate in each duration.
stratum	A character vector of stratum name.

Details

The duration are ordered piecewise for a duration equal to $t_i - t_{i-1}$, where $0 = t_0 < t_i < \cdots < t_M = \infty$. The enrollment rates are defined in each duration with the same length.

For a study with multiple strata, different duration and rates can be specified in each stratum.

Value

An enroll_rate data frame.

Examples

# Define enroll rate without stratum
define_enroll_rate(
  duration = c(2, 2, 10),
  rate = c(3, 6, 9)
)

# Define enroll rate with stratum
define_enroll_rate(
  duration = rep(c(2, 2, 2, 18), 3),
  rate = c((1:4) / 3, (1:4) / 2, (1:4) / 6),
  stratum = c(array("High", 4), array("Moderate", 4), array("Low", 4))
)

---

Define failure rate

Description

Define subject failure rate for a study with two treatment groups. Also supports stratified designs that have different failure rates in each stratum.

Usage

define_fail_rate(duration, fail_rate, dropout_rate, hr = 1, stratum = "All")

Arguments

duration	A numeric vector of ordered piecewise study duration interval.
fail_rate	A numeric vector of failure rate in each duration in the control group.
dropout_rate	A numeric vector of dropout rate in each duration.
hr	A numeric vector of hazard ratio between treatment and control group.
stratum	A character vector of stratum name.

Details

Define the failure and dropout rate of subjects for a study as following a piecewise exponential distribution. The duration are ordered piecewise for a duration equal to $t_i - t_{i-1}$, where $0 = t_0 < t_i < \cdots < t_M = \infty$. The failure rate, dropout rate, and hazard ratio in a study duration can be specified.

For a study with multiple strata, different duration, failure rates, dropout rates, and hazard ratios can be specified in each stratum.

Value

A fail_rate data frame.

Examples

# Define enroll rate
define_fail_rate(
  duration = c(3, 100),
  fail_rate = log(2) / c(9, 18),
  hr = c(.9, .6),
  dropout_rate = .001
)

# Define enroll rate with stratum
define_fail_rate(
  stratum = c(rep("Low", 2), rep("High", 2)),
  duration = 1,
  fail_rate = c(.1, .2, .3, .4),
  dropout_rate = .001,
  hr = c(.9, .75, .8, .6)
)

---

Piecewise constant expected accrual

Description

Computes the expected cumulative enrollment (accrual) given a set of piecewise constant enrollment rates and times.

Usage

expected_accrual(
  time = 0:24,
  enroll_rate = define_enroll_rate(duration = c(3, 3, 18), rate = c(5, 10, 20))
)

Arguments

time	Times at which enrollment is to be computed.
enroll_rate	An enroll_rate data frame with or without stratum created by define_enroll_rate().

Value

A vector with expected cumulative enrollment for the specified times.

Specification

The contents of this section are shown in PDF user manual only.

Examples

library(tibble)

# Example 1: default
expected_accrual()

# Example 2: unstratified design
expected_accrual(
  time = c(5, 10, 20),
  enroll_rate = define_enroll_rate(
    duration = c(3, 3, 18),
    rate = c(5, 10, 20)
  )
)

# Example 3: stratified design
expected_accrual(
  time = c(24, 30, 40),
  enroll_rate = define_enroll_rate(
    stratum = c("subgroup", "complement"),
    duration = c(33, 33),
    rate = c(30, 30)
  )
)

# Example 4: expected accrual over time
# Scenario 4.1: for the enrollment in the first 3 months,
# it is exactly 3 * 5 = 15.
expected_accrual(
  time = 3,
  enroll_rate = define_enroll_rate(duration = c(3, 3, 18), rate = c(5, 10, 20))
)

# Scenario 4.2: for the enrollment in the first 6 months,
# it is exactly 3 * 5 + 3 * 10 = 45.
expected_accrual(
  time = 6,
  enroll_rate = define_enroll_rate(duration = c(3, 3, 18), rate = c(5, 10, 20))
)

# Scenario 4.3: for the enrollment in the first 24 months,
# it is exactly 3 * 5 + 3 * 10 + 18 * 20 = 405.
expected_accrual(
  time = 24,
  enroll_rate = define_enroll_rate(duration = c(3, 3, 18), rate = c(5, 10, 20))
)

# Scenario 4.4: for the enrollment after 24 months,
# it is the same as that from the 24 months, since the enrollment is stopped.
expected_accrual(
  time = 25,
  enroll_rate = define_enroll_rate(duration = c(3, 3, 18), rate = c(5, 10, 20))
)

# Instead of compute the enrolled subjects one time point by one time point,
# we can also compute it once.
expected_accrual(
  time = c(3, 6, 24, 25),
  enroll_rate = define_enroll_rate(duration = c(3, 3, 18), rate = c(5, 10, 20))
)

---

Expected events observed under piecewise exponential model

Description

Computes expected events over time and by strata under the assumption of piecewise constant enrollment rates and piecewise exponential failure and censoring rates. The piecewise exponential distribution allows a simple method to specify a distribution and enrollment pattern where the enrollment, failure and dropout rates changes over time. While the main purpose may be to generate a trial that can be analyzed at a single point in time or using group sequential methods, the routine can also be used to simulate an adaptive trial design. The intent is to enable sample size calculations under non-proportional hazards assumptions for stratified populations.

Usage

expected_event(
  enroll_rate = define_enroll_rate(duration = c(2, 2, 10), rate = c(3, 6, 9)),
  fail_rate = define_fail_rate(duration = c(3, 100), fail_rate = log(2)/c(9, 18),
    dropout_rate = 0.001),
  total_duration = 25,
  simple = TRUE
)

Arguments

enroll_rate	An enroll_rate data frame with or without stratum created by define_enroll_rate().
fail_rate	A fail_rate data frame with or without stratum created by define_fail_rate().
total_duration	Total follow-up from start of enrollment to data cutoff.
simple	If default (TRUE), return numeric expected number of events, otherwise a data frame as described below.

Details

More periods will generally be supplied in output than those that are input. The intent is to enable expected event calculations in a tidy format to maximize flexibility for a variety of purposes.

Value

The default when simple = TRUE is to return the total expected number of events as a real number. Otherwise, when simple = FALSE, a data frame is returned with the following variables for each period specified in fail_rate:

• t: start of period.

• fail_rate: failure rate during the period.

• event: expected events during the period.

The records in the returned data frame correspond to the input data frame fail_rate.

Specification

Examples

library(gsDesign2)

# Default arguments, simple output (total event count only)
expected_event()

# Event count by time period
expected_event(simple = FALSE)

# Early cutoff
expected_event(total_duration = .5)

# Single time period example
expected_event(
  enroll_rate = define_enroll_rate(duration = 10, rate = 10),
  fail_rate = define_fail_rate(duration = 100, fail_rate = log(2) / 6, dropout_rate = .01),
  total_duration = 22,
  simple = FALSE
)

# Single time period example, multiple enrollment periods
expected_event(
  enroll_rate = define_enroll_rate(duration = c(5, 5), rate = c(10, 20)),
  fail_rate = define_fail_rate(duration = 100, fail_rate = log(2) / 6, dropout_rate = .01),
  total_duration = 22, simple = FALSE
)

# Single time period example, multiple strata
enroll_rate <- define_enroll_rate(
  stratum = rep(c("Biomarker-positive", "Biomarker-negative"), each = 4),
  duration = c(2, 2, 2, 6, 2, 2, 2, 6),
  rate = c(1:4, 1:4))
failure_rate <- define_fail_rate(
  stratum = rep(c("Biomarker-positive", "Biomarker-negative"), each = 2),
  duration = c(3, 100, 3, 100),
  fail_rate = log(2) / c(8, 12, 8, 10),
  dropout_rate = 0.001)
# Number of expected events by stratum
sapply(c("Biomarker-positive", "Biomarker-negative"),
       function(ss){
         expected_event(enroll_rate = enroll_rate[enroll_rate$stratum == ss, ],
                        fail_rate = failure_rate[failure_rate$stratum == ss, ],
                        total_duration = 36,
                        simple = TRUE)})

---

Predict time at which a targeted event count is achieved

Description

expected_time() is made to match input format with ahr() and to solve for the time at which the expected accumulated events is equal to an input target. Enrollment and failure rate distributions are specified as follows. The piecewise exponential distribution allows a simple method to specify a distribution and enrollment pattern where the enrollment, failure and dropout rates changes over time.

Usage

expected_time(
  enroll_rate = define_enroll_rate(duration = c(2, 2, 10), rate = c(3, 6, 9) * 5),
  fail_rate = define_fail_rate(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)),
  target_event = 150,
  ratio = 1,
  interval = c(0.01, 100)
)

Arguments

enroll_rate	An enroll_rate data frame with or without stratum created by define_enroll_rate().
fail_rate	A fail_rate data frame with or without stratum created by define_fail_rate().
target_event	The targeted number of events to be achieved.
ratio	Experimental:Control randomization ratio.
interval	An interval that is presumed to include the time at which expected event count is equal to target_event.

Value

A data frame with Time (computed to match events in target_event), AHR (average hazard ratio), Events (target_event input), info (information under given scenarios), and info0 (information under related null hypothesis) for each value of total_duration input.

Specification

Examples

# Example 1 ----
# default

expected_time()


# Example 2 ----
# check that result matches a finding using AHR()
# Start by deriving an expected event count
enroll_rate <- define_enroll_rate(duration = c(2, 2, 10), rate = c(3, 6, 9) * 5)
fail_rate <- define_fail_rate(
  duration = c(3, 100),
  fail_rate = log(2) / c(9, 18),
  hr = c(.9, .6),
  dropout_rate = .001
)
total_duration <- 20
xx <- ahr(enroll_rate, fail_rate, total_duration)
xx

# Next we check that the function confirms the timing of the final analysis.

expected_time(enroll_rate, fail_rate,
  target_event = xx$event, interval = c(.5, 1.5) * xx$time
)


# Example 3 ----
# In this example, we verify `expected_time()` by `ahr()`.

x <- ahr(
  enroll_rate = enroll_rate, fail_rate = fail_rate,
  ratio = 1, total_duration = 20
)

cat("The number of events by 20 months is ", x$event, ".\n")

y <- expected_time(
  enroll_rate = enroll_rate, fail_rate = fail_rate,
  ratio = 1, target_event = x$event
)

cat("The time to get ", x$event, " is ", y$time, "months.\n")

---

Fixed design under non-proportional hazards

Description

Computes fixed design sample size (given power) or power (given sample size) by:

• fixed_design_ahr() - Average hazard ratio method.

• fixed_design_fh() - Weighted logrank test with Fleming-Harrington weights (Farrington and Manning, 1990).

• fixed_design_mb() - Weighted logrank test with Magirr-Burman weights.

• fixed_design_lf() - Lachin-Foulkes method (Lachin and Foulkes, 1986).

• fixed_design_maxcombo() - MaxCombo method.

• fixed_design_rmst() - RMST method.

• fixed_design_milestone() - Milestone method.

Additionally, fixed_design_rd() provides fixed design for binary endpoint with treatment effect measuring in risk difference.

Usage

fixed_design_ahr(
  enroll_rate,
  fail_rate,
  alpha = 0.025,
  power = NULL,
  ratio = 1,
  study_duration = 36,
  event = NULL,
  info_scale = c("h0_h1_info", "h0_info", "h1_info")
)

fixed_design_fh(
  alpha = 0.025,
  power = NULL,
  ratio = 1,
  study_duration = 36,
  enroll_rate,
  fail_rate,
  rho = 0,
  gamma = 0,
  info_scale = c("h0_h1_info", "h0_info", "h1_info")
)

fixed_design_lf(
  alpha = 0.025,
  power = NULL,
  ratio = 1,
  study_duration = 36,
  enroll_rate,
  fail_rate
)

fixed_design_maxcombo(
  alpha = 0.025,
  power = NULL,
  ratio = 1,
  study_duration = 36,
  enroll_rate,
  fail_rate,
  rho = c(0, 0, 1),
  gamma = c(0, 1, 0),
  tau = rep(-1, 3)
)

fixed_design_mb(
  alpha = 0.025,
  power = NULL,
  ratio = 1,
  study_duration = 36,
  enroll_rate,
  fail_rate,
  tau = 6,
  w_max = Inf,
  info_scale = c("h0_h1_info", "h0_info", "h1_info")
)

fixed_design_milestone(
  alpha = 0.025,
  power = NULL,
  ratio = 1,
  enroll_rate,
  fail_rate,
  study_duration = 36,
  tau = NULL
)

fixed_design_rd(
  alpha = 0.025,
  power = NULL,
  ratio = 1,
  p_c,
  p_e,
  rd0 = 0,
  n = NULL,
  info_scale = c("h0_h1_info", "h0_info", "h1_info")
)

fixed_design_rmst(
  alpha = 0.025,
  power = NULL,
  ratio = 1,
  study_duration = 36,
  enroll_rate,
  fail_rate,
  tau = NULL
)

Arguments

enroll_rate	An enroll_rate data frame with or without stratum created by define_enroll_rate().
fail_rate	A fail_rate data frame with or without stratum created by define_fail_rate().
alpha	One-sided Type I error (strictly between 0 and 1).
power	Power (NULL to compute power or strictly between 0 and 1 - alpha otherwise).
ratio	Experimental:Control randomization ratio.
study_duration	Study duration.
event	A numerical vector specifying the targeted events at each analysis. See details.
info_scale	Information scale for calculation. Options are: "h0_h1_info" (default): variance under both null and alternative hypotheses is used. "h0_info": variance under null hypothesis is used. "h1_info": variance under alternative hypothesis is used.
rho	A vector of numbers paring with gamma and tau for MaxCombo test.
gamma	A vector of numbers paring with rho and tau for MaxCombo test.
tau	Test parameter in RMST.
w_max	Test parameter of Magirr-Burman method.
p_c	A numerical value of the control arm rate.
p_e	A numerical value of the experimental arm rate.
rd0	Risk difference under null hypothesis, default is 0.
n	Sample size. If NULL with power input, the sample size will be computed to achieve the targeted power

Value

A list of design characteristic summary.

Examples

# AHR method ----

# Example 1: given power and compute sample size
x <- fixed_design_ahr(
  alpha = .025, power = .9,
  enroll_rate = define_enroll_rate(duration = 18, rate = 1),
  fail_rate = define_fail_rate(
    duration = c(4, 100),
    fail_rate = log(2) / 12,
    hr = c(1, .6),
    dropout_rate = .001
  ),
  study_duration = 36
)
x |> summary()

# Example 2: given sample size and compute power
x <- fixed_design_ahr(
  alpha = .025,
  enroll_rate = define_enroll_rate(duration = 18, rate = 20),
  fail_rate = define_fail_rate(
    duration = c(4, 100),
    fail_rate = log(2) / 12,
    hr = c(1, .6),
    dropout_rate = .001
  ),
  study_duration = 36
)
x |> summary()

# WLR test with FH weights ----

# Example 1: given power and compute sample size
x <- fixed_design_fh(
  alpha = .025, power = .9,
  enroll_rate = define_enroll_rate(duration = 18, rate = 1),
  fail_rate = define_fail_rate(
    duration = c(4, 100),
    fail_rate = log(2) / 12,
    hr = c(1, .6),
    dropout_rate = .001
  ),
  study_duration = 36,
  rho = 1, gamma = 1
)
x |> summary()

# Example 2: given sample size and compute power
x <- fixed_design_fh(
  alpha = .025,
  enroll_rate = define_enroll_rate(duration = 18, rate = 20),
  fail_rate = define_fail_rate(
    duration = c(4, 100),
    fail_rate = log(2) / 12,
    hr = c(1, .6),
    dropout_rate = .001
  ),
  study_duration = 36,
  rho = 1, gamma = 1
)
x |> summary()

# LF method ----

# Example 1: given power and compute sample size
x <- fixed_design_lf(
  alpha = .025, power = .9,
  enroll_rate = define_enroll_rate(duration = 18, rate = 1),
  fail_rate = define_fail_rate(
    duration = 100,
    fail_rate = log(2) / 12,
    hr = .7,
    dropout_rate = .001
  ),
  study_duration = 36
)
x |> summary()

# Example 2: given sample size and compute power
x <- fixed_design_lf(
  alpha = .025,
  enroll_rate = define_enroll_rate(duration = 18, rate = 20),
  fail_rate = define_fail_rate(
    duration = 100,
    fail_rate = log(2) / 12,
    hr = .7,
    dropout_rate = .001
  ),
  study_duration = 36
)
x |> summary()

# MaxCombo test ----

# Example 1: given power and compute sample size
x <- fixed_design_maxcombo(
  alpha = .025, power = .9,
  enroll_rate = define_enroll_rate(duration = 18, rate = 1),
  fail_rate = define_fail_rate(
    duration = c(4, 100),
    fail_rate = log(2) / 12,
    hr = c(1, .6),
    dropout_rate = .001
  ),
  study_duration = 36,
  rho = c(0, 0.5), gamma = c(0, 0), tau = c(-1, -1)
)
x |> summary()

# Example 2: given sample size and compute power
x <- fixed_design_maxcombo(
  alpha = .025,
  enroll_rate = define_enroll_rate(duration = 18, rate = 20),
  fail_rate = define_fail_rate(
    duration = c(4, 100),
    fail_rate = log(2) / 12,
    hr = c(1, .6),
    dropout_rate = .001
  ),
  study_duration = 36,
  rho = c(0, 0.5), gamma = c(0, 0), tau = c(-1, -1)
)
x |> summary()

# WLR test with MB weights ----

# Example 1: given power and compute sample size
x <- fixed_design_mb(
  alpha = .025, power = .9,
  enroll_rate = define_enroll_rate(duration = 18, rate = 1),
  fail_rate = define_fail_rate(
    duration = c(4, 100),
    fail_rate = log(2) / 12,
    hr = c(1, .6),
    dropout_rate = .001
  ),
  study_duration = 36,
  tau = 4,
  w_max = 2
)
x |> summary()

# Example 2: given sample size and compute power
x <- fixed_design_mb(
  alpha = .025,
  enroll_rate = define_enroll_rate(duration = 18, rate = 20),
  fail_rate = define_fail_rate(
    duration = c(4, 100),
    fail_rate = log(2) / 12,
    hr = c(1, .6),
    dropout_rate = .001
  ),
  study_duration = 36,
  tau = 4,
  w_max = 2
)
x |> summary()

# Milestone method ----

# Example 1: given power and compute sample size
x <- fixed_design_milestone(
  alpha = .025, power = .9,
  enroll_rate = define_enroll_rate(duration = 18, rate = 1),
  fail_rate = define_fail_rate(
    duration = 100,
    fail_rate = log(2) / 12,
    hr = .7,
    dropout_rate = .001
  ),
  study_duration = 36,
  tau = 18
)
x |> summary()

# Example 2: given sample size and compute power
x <- fixed_design_milestone(
  alpha = .025,
  enroll_rate = define_enroll_rate(duration = 18, rate = 20),
  fail_rate = define_fail_rate(
    duration = 100,
    fail_rate = log(2) / 12,
    hr = .7,
    dropout_rate = .001
  ),
  study_duration = 36,
  tau = 18
)
x |> summary()

# Binary endpoint with risk differences ----

# Example 1: given power and compute sample size
x <- fixed_design_rd(
  alpha = 0.025, power = 0.9, p_c = .15, p_e = .1,
  rd0 = 0, ratio = 1
)
x |> summary()

# Example 2: given sample size and compute power
x <- fixed_design_rd(
  alpha = 0.025, power = NULL, p_c = .15, p_e = .1,
  rd0 = 0, n = 2000, ratio = 1
)
x |> summary()

# RMST method ----

# Example 1: given power and compute sample size
x <- fixed_design_rmst(
  alpha = .025, power = .9,
  enroll_rate = define_enroll_rate(duration = 18, rate = 1),
  fail_rate = define_fail_rate(
    duration = 100,
    fail_rate = log(2) / 12,
    hr = .7,
    dropout_rate = .001
  ),
  study_duration = 36,
  tau = 18
)
x |> summary()

# Example 2: given sample size and compute power
x <- fixed_design_rmst(
  alpha = .025,
  enroll_rate = define_enroll_rate(duration = 18, rate = 20),
  fail_rate = define_fail_rate(
    duration = 100,
    fail_rate = log(2) / 12,
    hr = .7,
    dropout_rate = .001
  ),
  study_duration = 36,
  tau = 18
)
x |> summary()

---

Default boundary generation

Description

gs_b() is the simplest version of a function to be used with the upper and lower arguments in gs_power_npe() and gs_design_npe() or the upper_bound and lower_bound arguments in gs_prob_combo() and pmvnorm_combo(). It simply returns the vector of Z-values in the input vector par or, if k is specified, par[k] is returned. Note that if bounds need to change with changing information at analyses, gs_b() should not be used. For instance, for spending function bounds use gs_spending_bound().

Usage

gs_b(par = NULL, k = NULL, ...)

Arguments

par	For gs_b(), this is just Z-values for the boundaries; can include infinite values.
k	Is NULL (default), return par, else return par[k].
...	Further arguments passed to or from other methods.

Value

Returns the vector input par if k is NULL, otherwise, par[k].

Specification

The contents of this section are shown in PDF user manual only.

Examples

# Simple: enter a vector of length 3 for bound
gs_b(par = 4:2)

# 2nd element of par
gs_b(par = 4:2, k = 2)

# Generate an efficacy bound using a spending function
# Use Lan-DeMets spending approximation of O'Brien-Fleming bound
# as 50%, 75% and 100% of final spending
# Information fraction
IF <- c(.5, .75, 1)
gs_b(par = gsDesign::gsDesign(
  alpha = .025, k = length(IF),
  test.type = 1, sfu = gsDesign::sfLDOF,
  timing = IF
)$upper$bound)

---

Bound summary table

Description

Summarizes the efficacy and futility bounds for each analysis.

Usage

gs_bound_summary(
  x,
  digits = 4,
  ddigits = 2,
  tdigits = 0,
  timename = "Month",
  alpha = NULL
)

Arguments

x	Design object.
digits	Number of digits past the decimal to be printed in the body of the table.
ddigits	Number of digits past the decimal to be printed for the natural parameter delta.
tdigits	Number of digits past the decimal point to be shown for estimated timing of each analysis.
timename	Text string indicating time unit.
alpha	Vector of alpha values to compute additional efficacy columns.

Value

A data frame

See Also

gsDesign::gsBoundSummary()

Examples

library(gsDesign2)

x <- gs_design_ahr(info_frac = c(.25, .75, 1), analysis_time = c(12, 25, 36))
gs_bound_summary(x)

x <- gs_design_wlr(info_frac = c(.25, .75, 1), analysis_time = c(12, 25, 36))
gs_bound_summary(x)

# Report multiple efficacy bounds (only supported for AHR designs)
x <- gs_design_ahr(analysis_time = 1:3*12, alpha = 0.0125)
gs_bound_summary(x, alpha = c(0.025, 0.05))

---

Conditional power computation with non-constant effect size for non-/crossing an upper boundary at analysis j given observed Z value at analysis i

Description

Conditional power computation with non-constant effect size for non-/crossing an upper boundary at analysis j given observed Z value at analysis i

Usage

gs_cp(x = NULL, theta = NULL, i = 1, zi = NULL)

Arguments

x	An object of type gsDesign2.
theta	Optional numeric vector with length $j-i+1$, which specifies the natural parameter for treatment effect of interim analysis $i$ through analysis $j$. The default is NULL.
i	Index of current analysis, with default of 1.
zi	Numeric scalar z-value observed at analysis $i$.

Details

We assume $Z_i, i = 1, ..., K$ are the z-statistics at an interim analysis i, respectively. We assume further $Z_i, i = 1, ..., K$ follows multivariate normal distribution

$E(Z_i) = \theta_i\sqrt{I_i}$

$Cov(Z_i, Z_j) = I_i/I_j$

. See https://merck.github.io/gsDesign2/articles/story-npe-background.html for assumption details.

The returned value is list of

$P(\{Z_j \geq b_j\} \& \{\cap_{m=i+1}^{j-1} a_m \leq Z_m < b_m\} \mid Z_i = z_i).$

$P(\{Z_j \geq b_j\} \& \{\cap_{m=i+1}^{j-1} Z_m < b_m\} \mid Z_i = z_i).$

$P(\{Z_j \leq b_j\} \& \{\cap_{m=i+1}^{j-1} a_m \leq Z_m < b_m\} \mid Z_i = z_i).$

Value

A list with the following elements:

prob_alpha

A numeric vector of $(\alpha_{i,i+1}, \ldots, \alpha_{i,j-1}, \alpha_{i,j})$, where $\alpha_{i,j} = P(\{Z_j \geq b_j\} \& \{\cap_{m=i+1}^{j-1} a_m \leq Z_m < b_m\} \mid Z_i = z_i)$.

prob_alpha_plus

A numeric vector of $(\alpha^+_{i,i+1}, \ldots, \alpha^+_{i,j-1}, \alpha^+_{i,j})$, where $\alpha^+_{i,j} = P(\{Z_j \geq b_j\} \& \{\cap_{m=i+1}^{j-1} Z_m < b_m\} \mid Z_i = z_i)$.

prob_beta

A numeric vector of $(\beta_{i,i+1}, \ldots, \beta_{i,j-1}, \beta_{i,j})$, where $\beta_{i,j} = P(\{Z_j \leq b_j\} \& \{\cap_{m=i+1}^{j-1} a_m \leq Z_m < b_m\} \mid Z_i = z_i)$.

Examples

library(gsDesign2)
library(gsDesign)
library(dplyr)
library(mvtnorm)
# Example 1
# original design ----
enroll_rate <- define_enroll_rate(duration = c(2, 2, 2, 18),
                                  rate = c(1, 2, 3, 4))
fail_rate <- define_fail_rate(duration = c(3, Inf),
                              fail_rate = log(2) / 10,
                              dropout_rate = 0.001,
                              hr = c(1, 0.7))
x <- gs_design_ahr(enroll_rate = enroll_rate, fail_rate = fail_rate,
                   alpha = 0.025, beta = 0.1, ratio = 1,
                   info_frac = c(0.4, 0.6, 0.8, 1), analysis_time = 30,
                   binding = FALSE,
                   upper = gs_spending_bound,
                   upar = list(sf = sfLDOF, total_spend = 0.025, param = NULL),
                   lower = gs_spending_bound,
                   lpar = list(sf = sfLDOF, total_spend = 0.1),
                   h1_spending = TRUE,
                   test_lower = TRUE,
                   info_scale = "h0_h1_info") |> to_integer()

# calculate conditional power
# case 1: currently at IA1, compute conditional power at IA2, IA3 and FA, with default theta = NULL
gs_cp(x = x, i = 1, zi = -gsDesign::hrn2z(hr = 0.8, n = 150+180, ratio = 1))

# case 2: currently at IA1, compute conditional power at IA2, IA3 and FA, with user-input theta
gs_cp(x = x, theta = c(0.15, 0.2, 0.25, 0.3), i = 1, zi = -gsDesign::hrn2z(hr = 0.8, n = 150+180, ratio = 1))

---

Simple conditional power computation with non-constant effect size

Description

Simple conditional power computation with non-constant effect size

Usage

gs_cp_simple(x = NULL, theta = NULL, i = 1, zi = NULL)

Arguments

x	An object of type gsDesign2.
theta	Optional numeric vector of natural parameter for treatment effects from analysis $i$ through final analysis $K$. If NULL, values are taken from x$analysis$theta.
i	Integer index for current analysis. Default is 1.
zi	Numeric scalar z-value observed at analysis $i$.

Details

Suppose there are $K$ analyses. Let $Z_i$ and $Z_j$ be the Z-statistics at a current analysis $i$ and a future analysis $j$, respectively. Let's denote the statistical information at the $i$-th analysis as $I_i$. We further assume $Z_i$ and $Z_j$ are bivariate normal under standard group sequential assumptions with independent increments, then

$E(Z_i) = \theta_i\sqrt{I_i}$

$Var(Z_i) = 1/I_i$

$Cov(Z_i, Z_j) = t \equiv I_i/I_j$

See https://merck.github.io/gsDesign2/articles/story-npe-background.html for assumption details. Returned value is

$P(Z_j > b_j \mid Z_i = z_i) = 1 - \Phi\left(\frac{b_j - \sqrt{t}z_i - \sqrt{I_j}(\theta_j - \theta_i\sqrt{t})}{\sqrt{1 - t}}\right)$

where $b_j$ is the efficacy bound at analysis $j$, $z_i$ is the observed Z-value at analysis $i$, and $\theta_i$ is the natural parameter for treatment effect at analysis $i$.

Value

A numeric vector with the conditional power $P(Z_j > b_j \mid Z_i = z_i)$ for $j = i+1, ..., K$.

Examples

library(gsDesign2)
library(gsDesign)
# Calculate conditional power with optional user-input theta (if NULL, will come from the input design)
alpha <- 0.025
beta <- 0.1
ratio <- 1
enroll_rate <- define_enroll_rate(
  duration = c(2, 2, 10),
  rate = (1:3) / 3)
fail_rate <- define_fail_rate(
  duration = Inf, fail_rate = log(2) / 9,
  hr = 0.6, dropout_rate = .0001)
analysis_time <- c(12, 24, 36)
ratio <- 1
upper <- gs_spending_bound
lower <- gs_b
upar <- list(sf = sfLDOF, total_spend = alpha)
lpar <- rep(-Inf, 3)
x <- gs_design_ahr(
  enroll_rate = enroll_rate, fail_rate = fail_rate,
  alpha = alpha, beta = beta, ratio = ratio,
  info_scale = "h0_h1_info",
  info_frac = NULL,
  analysis_time = c(12, 24, 36),
  upper = upper, upar = upar, test_upper = TRUE,
  lower = lower, lpar = lpar, test_lower = FALSE,
) |>
  to_integer()

# theta is NULL case
gs_cp_simple(x = x, theta = NULL, i = 1, zi = 1.5)

# User-input theta case
gs_cp_simple(x = x, theta = c(0.1, 0.2, 0.3), i = 1, zi = 1.5)

---

Create npsurvSS arm object

Description

Create npsurvSS arm object

Usage

gs_create_arm(enroll_rate, fail_rate, ratio, total_time = 1e+06)

Arguments

enroll_rate	Enrollment rates from define_enroll_rate().
fail_rate	Failure and dropout rates from define_fail_rate().
ratio	Experimental:Control randomization ratio.
total_time	Total analysis time.

Value

A list of the two arms.

Specification

The contents of this section are shown in PDF user manual only.

Examples

enroll_rate <- define_enroll_rate(
  duration = c(2, 2, 10),
  rate = c(3, 6, 9)
)

fail_rate <- define_fail_rate(
  duration = c(3, 100),
  fail_rate = log(2) / c(9, 18),
  hr = c(.9, .6),
  dropout_rate = .001
)

gs_create_arm(enroll_rate, fail_rate, ratio = 1)

---

Calculate sample size and bounds given targeted power and Type I error in group sequential design using average hazard ratio under non-proportional hazards

Description

Calculate sample size and bounds given targeted power and Type I error in group sequential design using average hazard ratio under non-proportional hazards

Usage

gs_design_ahr(
  enroll_rate = define_enroll_rate(duration = c(2, 2, 10), rate = c(3, 6, 9)),
  fail_rate = define_fail_rate(duration = c(3, 100), fail_rate = log(2)/c(9, 18), hr =
    c(0.9, 0.6), dropout_rate = 0.001),
  alpha = 0.025,
  beta = 0.1,
  info_frac = NULL,
  analysis_time = 36,
  ratio = 1,
  binding = FALSE,
  upper = gs_spending_bound,
  upar = list(sf = gsDesign::sfLDOF, total_spend = alpha),
  lower = gs_spending_bound,
  lpar = list(sf = gsDesign::sfLDOF, total_spend = beta),
  h1_spending = TRUE,
  test_upper = TRUE,
  test_lower = TRUE,
  info_scale = c("h0_h1_info", "h0_info", "h1_info"),
  r = 18,
  tol = 1e-06,
  interval = c(0.01, 1000)
)

Arguments

enroll_rate	An enroll_rate data frame with or without stratum created by define_enroll_rate().
fail_rate	A fail_rate data frame with or without stratum created by define_fail_rate().
alpha	One-sided Type I error.
beta	Type II error.
info_frac	Targeted information fraction for analyses. See details.
analysis_time	Targeted calendar timing of analyses. See details.
ratio	Experimental:Control randomization ratio.
binding	Indicator of whether futility bound is binding; default of FALSE is recommended.
upper	Function to compute upper bound. gs_spending_bound(): alpha-spending efficacy bounds. gs_b(): fixed efficacy bounds.
upar	Parameters passed to upper. If upper = gs_b, then upar is a numerical vector specifying the fixed efficacy bounds per analysis. If upper = gs_spending_bound, then upar is a list including sf for the spending function family. total_spend for total alpha spend. param for the parameter of the spending function. timing specifies spending time if different from information-based spending; see details.
lower	Function to compute lower bound, which can be set up similarly as upper. See this vignette.
lpar	Parameters passed to lower, which can be set up similarly as upar.
h1_spending	Indicator that lower bound to be set by spending under alternate hypothesis (input fail_rate) if spending is used for lower bound. If this is FALSE, then the lower bound spending is under the null hypothesis. This is for two-sided symmetric or asymmetric testing under the null hypothesis; See this vignette.
test_upper	Indicator of which analyses should include an upper (efficacy) bound; single value of TRUE (default) indicates all analyses; otherwise, a logical vector of the same length as info should indicate which analyses will have an efficacy bound.
test_lower	Indicator of which analyses should include a lower bound; single value of TRUE (default) indicates all analyses; single value of FALSE indicated no lower bound; otherwise, a logical vector of the same length as info should indicate which analyses will have a lower bound.
info_scale	Information scale for calculation. Options are: "h0_h1_info" (default): variance under both null and alternative hypotheses is used. "h0_info": variance under null hypothesis is used. This is often used for testing methods that use local alternatives, such as the Schoenfeld method. "h1_info": variance under alternative hypothesis is used.
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 parameter for boundary convergence (on Z-scale); normally not changed by the user.
interval	An interval presumed to include the times at which expected event count is equal to targeted event. Normally, this can be ignored by the user as it is set to c(.01, 1000).

Details

The parameters info_frac and analysis_time are used to determine the timing for interim and final analyses.

• If the interim analysis is determined by targeted information fraction and the study duration is known, then info_frac is a numerical vector where each element (greater than 0 and less than or equal to 1) represents the information fraction for each analysis. The analysis_time, which defaults to 36, indicates the time for the final analysis.

• If interim analyses are determined solely by the targeted calendar analysis timing from start of study, then analysis_time will be a vector specifying the time for each analysis.

• If both the targeted analysis time and the targeted information fraction are utilized for a given analysis, then timing will be the maximum of the two with both info_frac and analysis_time provided as vectors.

Value

A list with input parameters, enrollment rate, analysis, and bound.

• The ⁠$input⁠ is a list including alpha, beta, ratio, etc.

• The ⁠$enroll_rate⁠ is a table showing the enrollment for arriving the targeted power (1 - beta).

• The ⁠$fail_rate⁠ is a table showing the failure and dropout rates, which is the same as input.

• The ⁠$bound⁠ is a table summarizing the efficacy and futility bound per analysis.

• The analysis is a table summarizing the analysis time, sample size, events, average HR, treatment effect and statistical information per analysis.

Specification

The contents of this section are shown in PDF user manual only.

Examples

library(gsDesign)
library(gsDesign2)

# Example 1 ----
# call with defaults
gs_design_ahr()

# Example 2 ----
# Single analysis
gs_design_ahr(analysis_time = 40)

# Example 3 ----
# Multiple analysis_time
gs_design_ahr(analysis_time = c(12, 24, 36))

# Example 4 ----
# Specified information fraction

gs_design_ahr(info_frac = c(.25, .75, 1), analysis_time = 36)


# Example 5 ----
# multiple analysis times & info_frac
# driven by times
gs_design_ahr(info_frac = c(.25, .75, 1), analysis_time = c(12, 25, 36))
# driven by info_frac

gs_design_ahr(info_frac = c(1 / 3, .8, 1), analysis_time = c(12, 25, 36))


# Example 6 ----
# 2-sided symmetric design with O'Brien-Fleming spending

gs_design_ahr(
  analysis_time = c(12, 24, 36),
  binding = TRUE,
  upper = gs_spending_bound,
  upar = list(sf = gsDesign::sfLDOF, total_spend = 0.025, param = NULL, timing = NULL),
  lower = gs_spending_bound,
  lpar = list(sf = gsDesign::sfLDOF, total_spend = 0.025, param = NULL, timing = NULL),
  h1_spending = FALSE
)

# 2-sided asymmetric design with O'Brien-Fleming upper spending
# Pocock lower spending under H1 (NPH)

gs_design_ahr(
  analysis_time = c(12, 24, 36),
  binding = TRUE,
  upper = gs_spending_bound,
  upar = list(sf = gsDesign::sfLDOF, total_spend = 0.025, param = NULL, timing = NULL),
  lower = gs_spending_bound,
  lpar = list(sf = gsDesign::sfLDPocock, total_spend = 0.1, param = NULL, timing = NULL),
  h1_spending = TRUE
)


# Example 7 ----

gs_design_ahr(
  alpha = 0.0125,
  analysis_time = c(12, 24, 36),
  upper = gs_spending_bound,
  upar = list(sf = gsDesign::sfLDOF, total_spend = 0.0125, param = NULL, timing = NULL),
  lower = gs_b,
  lpar = rep(-Inf, 3)
)

gs_design_ahr(
  alpha = 0.0125,
  analysis_time = c(12, 24, 36),
  upper = gs_b,
  upar = gsDesign::gsDesign(
    k = 3, test.type = 1, n.I = c(.25, .75, 1),
    sfu = sfLDOF, sfupar = NULL, alpha = 0.0125
  )$upper$bound,
  lower = gs_b,
  lpar = rep(-Inf, 3)
)

---

Group sequential design using MaxCombo test under non-proportional hazards

Description

Group sequential design using MaxCombo test under non-proportional hazards

Usage

gs_design_combo(
  enroll_rate = define_enroll_rate(duration = 12, rate = 500/12),
  fail_rate = define_fail_rate(duration = c(4, 100), fail_rate = log(2)/15, hr = c(1,
    0.6), dropout_rate = 0.001),
  fh_test = rbind(data.frame(rho = 0, gamma = 0, tau = -1, test = 1, analysis = 1:3,
    analysis_time = c(12, 24, 36)), data.frame(rho = c(0, 0.5), gamma = 0.5, tau = -1,
    test = 2:3, analysis = 3, analysis_time = 36)),
  ratio = 1,
  alpha = 0.025,
  beta = 0.2,
  binding = FALSE,
  upper = gs_b,
  upar = c(3, 2, 1),
  lower = gs_b,
  lpar = c(-1, 0, 1),
  algorithm = mvtnorm::GenzBretz(maxpts = 1e+05, abseps = 1e-05),
  n_upper_bound = 1000,
  ...
)

Arguments

enroll_rate	An enroll_rate data frame with or without stratum created by define_enroll_rate().
fail_rate	A fail_rate data frame with or without stratum created by define_fail_rate().
fh_test	A data frame to summarize the test in each analysis. See examples for its data structure.
ratio	Experimental:Control randomization ratio.
alpha	One-sided Type I error.
beta	Type II error.
binding	Indicator of whether futility bound is binding; default of FALSE is recommended.
upper	Function to compute upper bound. gs_spending_bound(): alpha-spending efficacy bounds. gs_b(): fixed efficacy bounds.
upar	Parameters passed to upper. If upper = gs_b, then upar is a numerical vector specifying the fixed efficacy bounds per analysis. If upper = gs_spending_bound, then upar is a list including sf for the spending function family. total_spend for total alpha spend. param for the parameter of the spending function. timing specifies spending time if different from information-based spending; see details.
lower	Function to compute lower bound, which can be set up similarly as upper. See this vignette.
lpar	Parameters passed to lower, which can be set up similarly as upar.
algorithm	an object of class GenzBretz, Miwa or TVPACK specifying both the algorithm to be used as well as the associated hyper parameters.
n_upper_bound	A numeric value of upper limit of sample size.
...	Additional parameters passed to mvtnorm::pmvnorm.

Value

A list with input parameters, enrollment rate, analysis, and bound.

Examples

# The example is slow to run
library(mvtnorm)
library(gsDesign)

enroll_rate <- define_enroll_rate(
  duration = 12,
  rate = 500 / 12
)

fail_rate <- define_fail_rate(
  duration = c(4, 100),
  fail_rate = log(2) / 15, # median survival 15 month
  hr = c(1, .6),
  dropout_rate = 0.001
)

fh_test <- rbind(
  data.frame(
    rho = 0, gamma = 0, tau = -1,
    test = 1, analysis = 1:3, analysis_time = c(12, 24, 36)
  ),
  data.frame(
    rho = c(0, 0.5), gamma = 0.5, tau = -1,
    test = 2:3, analysis = 3, analysis_time = 36
  )
)

x <- gsSurv(
  k = 3,
  test.type = 4,
  alpha = 0.025,
  beta = 0.2,
  astar = 0,
  timing = 1,
  sfu = sfLDOF,
  sfupar = 0,
  sfl = sfLDOF,
  sflpar = 0,
  lambdaC = 0.1,
  hr = 0.6,
  hr0 = 1,
  eta = 0.01,
  gamma = 10,
  R = 12,
  S = NULL,
  T = 36,
  minfup = 24,
  ratio = 1
)

# Example 1 ----
# User-defined boundary

gs_design_combo(
  enroll_rate,
  fail_rate,
  fh_test,
  alpha = 0.025, beta = 0.2,
  ratio = 1,
  binding = FALSE,
  upar = x$upper$bound,
  lpar = x$lower$bound
)

# Example 2 ----

# Boundary derived by spending function
gs_design_combo(
  enroll_rate,
  fail_rate,
  fh_test,
  alpha = 0.025,
  beta = 0.2,
  ratio = 1,
  binding = FALSE,
  upper = gs_spending_combo,
  upar = list(sf = gsDesign::sfLDOF, total_spend = 0.025), # alpha spending
  lower = gs_spending_combo,
  lpar = list(sf = gsDesign::sfLDOF, total_spend = 0.2), # beta spending
)

---

Group sequential design computation with non-constant effect and information.

Description

The following two functions allow a non-constant treatment effect over time, but also can be applied for the usual homogeneous effect size designs. They require treatment effect and statistical information at each analysis as well as a method of deriving bounds, such as spending. Initial bound types supported are spending bounds and fixed bounds. These routines enables two things not available in the gsDesign package: 1) non-constant effect, 2) more flexibility in boundary selection.

gs_power_npe() derives group sequential bounds and boundary crossing probabilities for a design, given treatment effect and information at each analysis and the method of deriving bounds, such as spending.

gs_design_npe() derives group sequential design size, bounds and boundary crossing probabilities based on proportionate information and effect size at analyses, as well as the method of deriving bounds, such as spending.

The only differences in arguments between the two functions are the alpha and beta parameters used in the gs_design_npe().

Usage

gs_design_npe(
  theta = 0.1,
  theta0 = 0,
  theta1 = theta,
  info = 1,
  info0 = NULL,
  info1 = NULL,
  info_scale = c("h0_h1_info", "h0_info", "h1_info"),
  alpha = 0.025,
  beta = 0.1,
  upper = gs_b,
  upar = qnorm(0.975),
  lower = gs_b,
  lpar = -Inf,
  test_upper = TRUE,
  test_lower = TRUE,
  binding = FALSE,
  r = 18,
  tol = 1e-06
)

gs_power_npe(
  theta = 0.1,
  theta0 = 0,
  theta1 = theta,
  info = 1,
  info0 = NULL,
  info1 = NULL,
  info_scale = c("h0_h1_info", "h0_info", "h1_info"),
  upper = gs_b,
  upar = qnorm(0.975),
  lower = gs_b,
  lpar = -Inf,
  test_upper = TRUE,
  test_lower = TRUE,
  binding = FALSE,
  r = 18,
  tol = 1e-06
)

Arguments

theta	Natural parameter for group sequential design representing expected cumulative drift at all analyses; used for power calculation. It can be a scalar (constant treatment effect) or a vector (non-constant treatment effect). The user must provide a value for theta.
theta0	Natural parameter for null hypothesis. It can be a scalar (constant treatment effect) or a vector (non-constant treatment effect). The default is 0. If a value other than 0 is provided, it affects upper bound computation.
theta1	Natural parameter for alternate hypothesis, if needed for lower bound computation. It can be a scalar (constant treatment effect) or a vector (non-constant treatment effect). The default is the same as theta, which yields the usual beta-spending. If set to 0, spending is 2-sided under the null hypothesis.
info	Statistical information at all analyses for input theta. It is a vector of positive numbers in increasing order. The user must provide values corresponding to theta.
info0	Statistical information under null hypothesis. It is a vector of all positive numbers with increasing order. Default is set to be the same as info. If info0 is different than info, it impacts null hypothesis bound calculation.
info1	Statistical information under hypothesis used for futility bound calculation. It is a vector of all positive numbers with increasing order. Default is set to be the same as info. If info1 is different from info, it impacts futility bound calculation.
info_scale	Information scale for calculation. Options are: "h0_h1_info" (default): variance under both null and alternative hypotheses is used. "h0_info": variance under null hypothesis is used. This is often used for testing methods that use local alternatives, such as the Schoenfeld method. "h1_info": variance under alternative hypothesis is used.
alpha	One-sided Type I error.
beta	Type II error.
upper	Function to compute upper bound. gs_spending_bound(): alpha-spending efficacy bounds. gs_b(): fixed efficacy bounds.
upar	Parameters passed to upper. If upper = gs_b, then upar is a numerical vector specifying the fixed efficacy bounds per analysis. If upper = gs_spending_bound, then upar is a list including sf for the spending function family. total_spend for total alpha spend. param for the parameter of the spending function. timing specifies spending time if different from information-based spending; see details.
lower	Function to compute lower bound, which can be set up similarly as upper. See this vignette.
lpar	Parameters passed to lower, which can be set up similarly as upar.
test_upper	Indicator of which analyses should include an upper (efficacy) bound; single value of TRUE (default) indicates all analyses; otherwise, a logical vector of the same length as info should indicate which analyses will have an efficacy bound.
test_lower	Indicator of which analyses should include a lower bound; single value of TRUE (default) indicates all analyses; single value of FALSE indicated no lower bound; otherwise, a logical vector of the same length as info should indicate which analyses will have a lower bound.
binding	Indicator of whether futility bound is binding; default of FALSE is recommended.
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 parameter for boundary convergence (on Z-scale); normally not changed by the user.

Details

The bound specifications (upper, lower, upar, lpar) of gs_design_npe() will be used to ensure Type I error and other boundary properties are as specified. See the help file of gs_spending_bound() for details on spending function.

Value

A tibble with columns of

• analysis: analysis index.

• bound: either of value "upper" or "lower", indicating the upper and lower bound.

• z: the Z-score bounds.

• probability: cumulative probability of crossing the bound at or before the analysis.

• theta: same as the input.

• theta1: same as the input.

• info: statistical information at each analysis.

  • If it is returned by gs_power_npe, the info, info0, info1 are same as the input.

  • If it is returned by gs_design_npe, the info, info0, info1 are changed by a constant scale factor. factor to ensure the design has power 1 - beta.

• info0: statistical information under the null at each analysis.

• info1: statistical information under the alternative at each analysis.

• info_frac: information fraction at each analysis, i.e., info / max(info).

Specification

The contents of this section are shown in PDF user manual only.

The contents of this section are shown in PDF user manual only.

Author(s)

Keaven Anderson [email protected]

Examples

library(gsDesign)

# Example 1 ----
# gs_design_npe with single analysis
# Lachin book p 71 difference of proportions example
pc <- .28 # Control response rate
pe <- .40 # Experimental response rate
p0 <- (pc + pe) / 2 # Ave response rate under H0

# Information per increment of 1 in sample size
info0 <- 1 / (p0 * (1 - p0) * 4)
info <- 1 / (pc * (1 - pc) * 2 + pe * (1 - pe) * 2)

# Result should round up to next even number = 652
# Divide information needed under H1 by information per patient added
gs_design_npe(theta = pe - pc, info = info, info0 = info0)


# Example 2 ----
# gs_design_npe with with fixed bound
x <- gs_design_npe(
  alpha = 0.0125,
  theta = c(.1, .2, .3),
  info = (1:3) * 80,
  info0 = (1:3) * 80,
  upper = gs_b,
  upar = gsDesign::gsDesign(k = 3, sfu = gsDesign::sfLDOF, alpha = 0.0125)$upper$bound,
  lower = gs_b,
  lpar = c(-1, 0, 0)
)
x

# Same upper bound; this represents non-binding Type I error and will total 0.025
gs_power_npe(
  theta = rep(0, 3),
  info = (x |> dplyr::filter(bound == "upper"))$info,
  upper = gs_b,
  upar = (x |> dplyr::filter(bound == "upper"))$z,
  lower = gs_b,
  lpar = rep(-Inf, 3)
)

# Example 3 ----
# gs_design_npe with spending bound
# Design with futility only at analysis 1; efficacy only at analyses 2, 3
# Spending bound for efficacy; fixed bound for futility
# NOTE: test_upper and test_lower DO NOT WORK with gs_b; must explicitly make bounds infinite
# test_upper and test_lower DO WORK with gs_spending_bound
gs_design_npe(
  theta = c(.1, .2, .3),
  info = (1:3) * 40,
  info0 = (1:3) * 40,
  upper = gs_spending_bound,
  upar = list(sf = gsDesign::sfLDOF, total_spend = 0.025, param = NULL, timing = NULL),
  lower = gs_b,
  lpar = c(-1, -Inf, -Inf),
  test_upper = c(FALSE, TRUE, TRUE)
)

# one can try `info_scale = "h1_info"` or `info_scale = "h0_info"` here
gs_design_npe(
  theta = c(.1, .2, .3),
  info = (1:3) * 40,
  info0 = (1:3) * 30,
  info_scale = "h1_info",
  upper = gs_spending_bound,
  upar = list(sf = gsDesign::sfLDOF, total_spend = 0.025, param = NULL, timing = NULL),
  lower = gs_b,
  lpar = c(-1, -Inf, -Inf),
  test_upper = c(FALSE, TRUE, TRUE)
)

# Example 4 ----
# gs_design_npe with spending function bounds
# 2-sided asymmetric bounds
# Lower spending based on non-zero effect
gs_design_npe(
  theta = c(.1, .2, .3),
  info = (1:3) * 40,
  info0 = (1:3) * 30,
  upper = gs_spending_bound,
  upar = list(sf = gsDesign::sfLDOF, total_spend = 0.025, param = NULL, timing = NULL),
  lower = gs_spending_bound,
  lpar = list(sf = gsDesign::sfHSD, total_spend = 0.1, param = -1, timing = NULL)
)

# Example 5 ----
# gs_design_npe with two-sided symmetric spend, O'Brien-Fleming spending
# Typically, 2-sided bounds are binding
xx <- gs_design_npe(
  theta = c(.1, .2, .3),
  info = (1:3) * 40,
  binding = TRUE,
  upper = gs_spending_bound,
  upar = list(sf = gsDesign::sfLDOF, total_spend = 0.025, param = NULL, timing = NULL),
  lower = gs_spending_bound,
  lpar = list(sf = gsDesign::sfLDOF, total_spend = 0.025, param = NULL, timing = NULL)
)
xx

# Re-use these bounds under alternate hypothesis
# Always use binding = TRUE for power calculations
gs_power_npe(
  theta = c(.1, .2, .3),
  info = (1:3) * 40,
  binding = TRUE,
  upper = gs_b,
  lower = gs_b,
  upar = (xx |> dplyr::filter(bound == "upper"))$z,
  lpar = -(xx |> dplyr::filter(bound == "upper"))$z
)

# Example 6 ----
# Default of gs_power_npe (single analysis; Type I error controlled)
gs_power_npe(theta = 0) |> dplyr::filter(bound == "upper")

# Example 7 ----
# gs_power_npe with fixed bound
gs_power_npe(
  theta = c(.1, .2, .3),
  info = (1:3) * 40,
  upper = gs_b,
  upar = gsDesign::gsDesign(k = 3, sfu = gsDesign::sfLDOF)$upper$bound,
  lower = gs_b,
  lpar = c(-1, 0, 0)
)

# Same fixed efficacy bounds, no futility bound (i.e., non-binding bound), null hypothesis
gs_power_npe(
  theta = rep(0, 3),
  info = (1:3) * 40,
  upar = gsDesign::gsDesign(k = 3, sfu = gsDesign::sfLDOF)$upper$bound,
  lpar = rep(-Inf, 3)
) |>
  dplyr::filter(bound == "upper")

# Example 8 ----
# gs_power_npe with fixed bound testing futility only at analysis 1; efficacy only at analyses 2, 3
gs_power_npe(
  theta = c(.1, .2, .3),
  info = (1:3) * 40,
  upper = gs_b,
  upar = c(Inf, 3, 2),
  lower = gs_b,
  lpar = c(qnorm(.1), -Inf, -Inf)
)

# Example 9 ----
# gs_power_npe with spending function bounds
# Lower spending based on non-zero effect
gs_power_npe(
  theta = c(.1, .2, .3),
  info = (1:3) * 40,
  upper = gs_spending_bound,
  upar = list(sf = gsDesign::sfLDOF, total_spend = 0.025, param = NULL, timing = NULL),
  lower = gs_spending_bound,
  lpar = list(sf = gsDesign::sfHSD, total_spend = 0.1, param = -1, timing = NULL)
)

# Same bounds, but power under different theta
gs_power_npe(
  theta = c(.15, .25, .35),
  info = (1:3) * 40,
  upper = gs_spending_bound,
  upar = list(sf = gsDesign::sfLDOF, total_spend = 0.025, param = NULL, timing = NULL),
  lower = gs_spending_bound,
  lpar = list(sf = gsDesign::sfHSD, total_spend = 0.1, param = -1, timing = NULL)
)

# Example 10 ----
# gs_power_npe with two-sided symmetric spend, O'Brien-Fleming spending
# Typically, 2-sided bounds are binding
x <- gs_power_npe(
  theta = rep(0, 3),
  info = (1:3) * 40,
  binding = TRUE,
  upper = gs_spending_bound,
  upar = list(sf = gsDesign::sfLDOF, total_spend = 0.025, param = NULL, timing = NULL),
  lower = gs_spending_bound,
  lpar = list(sf = gsDesign::sfLDOF, total_spend = 0.025, param = NULL, timing = NULL)
)

# Re-use these bounds under alternate hypothesis
# Always use binding = TRUE for power calculations
gs_power_npe(
  theta = c(.1, .2, .3),
  info = (1:3) * 40,
  binding = TRUE,
  upar = (x |> dplyr::filter(bound == "upper"))$z,
  lpar = -(x |> dplyr::filter(bound == "upper"))$z
)

# Example 11 ----
# Different values of `r` and `tol` lead to different numerical accuracy
# Larger `r` and smaller `tol` give better accuracy, but leads to slow computation
n_analysis <- 5
gs_power_npe(
  theta = 0.1,
  info = 1:n_analysis,
  info0 = 1:n_analysis,
  info1 = NULL,
  info_scale = "h0_info",
  upper = gs_spending_bound,
  upar = list(sf = gsDesign::sfLDOF, total_spend = 0.025, param = NULL, timing = NULL),
  lower = gs_b,
  lpar = -rep(Inf, n_analysis),
  test_upper = TRUE,
  test_lower = FALSE,
  binding = FALSE,
  # Try different combinations of (r, tol) with
  # r in 6, 18, 24, 30, 35, 40, 50, 60, 70, 80, 90, 100
  # tol in 1e-6, 1e-12
  r = 6,
  tol = 1e-6
)

---