Skip to contents

gs_info_ahr: compute statistical information by the AHR method

Source: vignettes/usage_gs_info_ahr.Rmd
usage_gs_info_ahr.Rmd

Introduction of gs_info_ahr()

tEvents() calculate the analysis time (Time in its output), number of events (Events in its output), average hazard ratio (AHR in its outputs), effect size (theta in its output), statistical information (info and info0 in its output) using an average hazard ratio model.

The aforementioned calculation is based on piecewise model: + piecewise constant enrollment rates + piecewise exponential failure rates + piecewise censoring rates.

Use Cases

Example 1

In this example, we only input the target number of events by events = ..., and derive the time when these events will be arrived.

enrollRates <- tibble(Stratum = "All", duration = c(2, 2, 10), rate = c(3, 6, 9) * 5)
failRates <- tibble(Stratum = "All", duration = c(3, 100), failRate = log(2) / c(9, 18), hr = c(.9, .6), dropoutRate = rep(.001, 2))
ratio <- 1

gs_info_ahr(enrollRates = enrollRates, failRates = failRates,
            ratio = ratio, events = c(50, 80, 100))
## # A tibble: 3 × 7
##   Analysis  Time Events   AHR theta  info info0
##      <int> <dbl>  <dbl> <dbl> <dbl> <dbl> <dbl>
## 1        1  8.29   50.0 0.850 0.163  12.4  12.5
## 2        2 10.5    80.0 0.825 0.193  19.7  20.0
## 3        3 11.9   100.  0.812 0.208  24.6  25.0

Example 2

In this example, we only input the analysis time by analysisTimes = ..., and derive the number of events at these analysis time.

enrollRates <- tibble(Stratum = "All", duration = c(2, 2, 10), rate = c(3, 6, 9) * 5)
failRates <- tibble(Stratum = "All", duration = c(3, 100), failRate = log(2) / c(9, 18), hr = c(.9, .6), dropoutRate = rep(.001, 2))
ratio <- 1

gs_info_ahr(enrollRates = enrollRates, failRates = failRates,
            ratio = ratio, analysisTimes = c(10, 15, 20))
## # A tibble: 3 × 7
##   Analysis  Time Events   AHR theta  info info0
##      <int> <dbl>  <dbl> <dbl> <dbl> <dbl> <dbl>
## 1        1    10   72.4 0.831 0.186  17.9  18.1
## 2        2    15  151.  0.786 0.241  37.2  37.8
## 3        3    20  208.  0.738 0.304  51.0  52.1

Example 3

In this example, we both input analysisTimes = ... and events = .... In this case, one will see + the derived analysis time (Time column) \(\geq\) input analysisTimes + the derived number of event (Events column) \(\geq\) input events

enrollRates <- tibble(Stratum = "All", duration = c(2, 2, 10), rate = c(3, 6, 9) * 5)
failRates <- tibble(Stratum = "All", duration = c(3, 100), failRate = log(2) / c(9, 18), hr = c(.9, .6), dropoutRate = rep(.001, 2))
ratio <- 1

gs_info_ahr(enrollRates = enrollRates, failRates = failRates,
            ratio = ratio, analysisTimes = c(10, 15, 20), events = c(80,  # > events in example 2 
                                                                     140, # < > events in example 2 
                                                                     220  # > events in example 2 
                                                                     ))
## # A tibble: 3 × 7
##   Analysis  Time Events   AHR theta  info info0
##      <int> <dbl>  <dbl> <dbl> <dbl> <dbl> <dbl>
## 1        1  10.5   80.0 0.825 0.193  19.7  20.0
## 2        2  15    151.  0.786 0.241  37.2  37.8
## 3        3  21.2  220.  0.730 0.315  53.8  55.0

Inner Logic of gs_info_ahr()

To explain the inner logic of gs_info_ahr(), we discuss 3 scenario.

  1. only input analysisTimes
  2. only input events
  3. both input analysisTimes and events

Scenario 1: only input analysisTimes

If only analysisTimes = ... is input, essentially, gs_info_ahr() uses AHR() to calculate the number of events at these analysisTimes.

enrollRates <- tibble(Stratum = "All", duration = c(2, 2, 10), rate = c(3, 6, 9) * 5)
failRates <- tibble(Stratum = "All", duration = c(3, 100), failRate = log(2) / c(9, 18), hr = c(.9, .6), dropoutRate = rep(.001, 2))
ratio <- 1
analysisTimes <- c(10, 15, 20)

AHR(enrollRates = enrollRates, failRates = failRates, 
    ratio = ratio, totalDuration = analysisTimes) %>% 
  mutate(theta = -log(AHR), Analysis = 1 : length(analysisTimes)) %>% 
  select(Analysis, Time, Events, AHR, theta, info, info0) %>% 
  gt()
Analysis Time Events AHR theta info info0
1 10 72.37787 0.8305350 0.1856853 17.87995 18.09447
2 15 151.39207 0.7857415 0.2411275 37.20593 37.84802
3 20 208.36411 0.7377944 0.3040901 50.97575 52.09103

This is exactly the output from gs_info_ahr():

gs_info_ahr(enrollRates = enrollRates, failRates = failRates, 
            ratio = ratio, analysisTimes = analysisTimes) %>% gt()
Analysis Time Events AHR theta info info0
1 10 72.37787 0.8305350 0.1856853 17.87995 18.09447
2 15 151.39207 0.7857415 0.2411275 37.20593 37.84802
3 20 208.36411 0.7377944 0.3040901 50.97575 52.09103

Scenario 2: only input events

If only events = ... is input, essentially, gs_info_ahr() uses tEvents() to calculate the time when these events will be arrived.

enrollRates <- tibble(Stratum = "All", duration = c(2, 2, 10), rate = c(3, 6, 9) * 5)
failRates <- tibble(Stratum = "All", duration = c(3, 100), failRate = log(2) / c(9, 18), hr = c(.9, .6), dropoutRate = rep(.001, 2))
ratio <- 1
events <- c(70, 150, 200)

ans <- NULL
for(i in seq_along(events)){
  ans_new <- gsDesign2::tEvents(enrollRates = enrollRates, failRates = failRates, 
                                ratio = ratio, targetEvents = events[i])
  ans <- rbind(ans, ans_new)
}

ans %>% 
  mutate(theta = -log(AHR), Analysis = 1 : length(analysisTimes)) %>% 
  select(Analysis, Time, Events, AHR, theta, info, info0) %>% 
  gt()
Analysis Time Events AHR theta info info0
1 9.827998 70 0.8323845 0.1834608 17.29666 17.5
2 14.908141 150 0.7865729 0.2400699 36.86707 37.5
3 19.164367 200 0.7442008 0.2954443 48.94970 50.0

This is exactly the output from gs_info_ahr():

gs_info_ahr(enrollRates = enrollRates, failRates = failRates, 
            ratio = ratio, events = events) %>% gt()
Analysis Time Events AHR theta info info0
1 9.827998 70 0.8323845 0.1834608 17.29666 17.5
2 14.908141 150 0.7865729 0.2400699 36.86707 37.5
3 19.164367 200 0.7442008 0.2954443 48.94970 50.0

Scenario 3: both input analysisTimes and events

If both analysisTimes = ... and events = ... are input, gs_info_ahr() uses both AHR() and tEvents(). In this way, it is guaranteed that + the derived number of event (Events column) \(\geq\) input events + the derived analysis time (Time column) \(\geq\) input analysisTimes

enrollRates <- tibble(Stratum = "All", duration = c(2, 2, 10), rate = c(3, 6, 9) * 5)
failRates <- tibble(Stratum = "All", duration = c(3, 100), failRate = log(2) / c(9, 18), hr = c(.9, .6), dropoutRate = rep(.001, 2))
ratio <- 1
analysisTimes <- c(10, 15, 20)
events <- c(70, 150, 200)

ans <- NULL

# first, use `AHR()` to calculate the number of events at the input `analysisTimes`
ans <- AHR(enrollRates = enrollRates, failRates = failRates, 
           ratio = ratio, totalDuration = analysisTimes)

# second, compare if the events derived above meet the targeted number of events input in `events`
for(i in seq_along(events)){
  if (ans$Events[i] < events[i]){
    ans[i,] <- tEvents(enrollRates = enrollRates, failRates = failRates, 
                       ratio = ratio, targetEvents = events[i])
  }
}

ans %>% 
  mutate(theta = -log(AHR), Analysis = 1 : length(analysisTimes)) %>% 
  select(Analysis, Time, Events, AHR, theta, info, info0) %>% 
  gt()
Analysis Time Events AHR theta info info0
1 10 72.37787 0.8305350 0.1856853 17.87995 18.09447
2 15 151.39207 0.7857415 0.2411275 37.20593 37.84802
3 20 208.36411 0.7377944 0.3040901 50.97575 52.09103

This is exactly the output from gs_info_ahr():

gs_info_ahr(enrollRates = enrollRates, failRates = failRates, 
            ratio = ratio, events = events, analysisTimes = analysisTimes) %>% gt()
Analysis Time Events AHR theta info info0
1 10 72.37787 0.8305350 0.1856853 17.87995 18.09447
2 15 151.39207 0.7857415 0.2411275 37.20593 37.84802
3 20 208.36411 0.7377944 0.3040901 50.97575 52.09103