Allow event table as input of gs_update_ahr

[LittleBeannie]

When updating the boundaries, users may encounter the following scenarios:

• Scenario 1: Updating the design with a different alpha value: This scenario occurs during the design stage, where the design is prepared under an initial alpha (relatively smaller) and a full alpha (relatively larger). Since this happens at the design stage, no blinded data has been observed.

• Scenario 2: Updating the design at the time of analysis with blinded data observed: In this case, there are two approaches to consider:

[LittleBeannie]

For Scenario 2, there are two possible approaches:

• Approach 1: Input the blinded data (observed_data) into gs_update_ahr(). The function calculates the events for each piecewise interval. These events are then used to calculate the treatment effect (theta) and the statistical information under the alternative hypothesis (info0).
• Approach 2: Input the events for each piecewise interval (event_tbl) directly into gs_update_ahr().

To accommodate the above two approaches into gs_update_ahr(), there are two proposed interfaces of gs_update_ahr().

1. The gs_update_ahr() function accepts ONLY event_tbl as input. This event_tbl is calculated using a utility function called pw_event(), which summarizes the subject-level observed data, into summarized data.

# interface of gs_update_ahr
gs_update_ahr <- function (x,                          # original design
                           alpha,             # alpha if different from the original design
                           ustime, lstime,    # spending time if different from the original design
                           event_tbl) {...}

# use case
event_tbl <- observed_data |> pw_event(...)
gs_update_ahr(x = ..., alpha = ..., ustime = ..., lstime = ..., event_tbl = event_tbl)

2. The gs_update_ahr() function allows BOTHevent_tbl and observed_data as inputs:

# interface of gs_update_ahr
gs_update_ahr(x, # original design
             alpha,                # alpha if different from the original design
             ustime, lstime,       # new spending time if different from the original design
             observed_data,   
             event_tbl)

# use case 1: users can input event_tbl either manually or derive it using pw_event()
event_tbl <- observed_data |> pw_event(...)
gs_update_ahr(x = ..., ustime = ..., lstime = ..., event_tbl = event_tbl)

# use case 2: users can input observed_data, and the function will automatically convert this to event_tbl
gs_update_ahr(x = ..., ustime = ..., lstime = ..., observed_data = observed_data)

# use case 3: users can input both observed_data and event_tbl, and the function will cross-check for any mismatches between the two inputs.
gs_update_ahr(x = ..., ustime = ..., lstime = ..., observed_data = observed_data, event_tbl = event_tbl)

[LittleBeannie]

For Scenario 1: The desired output should resemble the attached screenshot, where columns for alpha values of 0.01, 0.0125, and 0.025 display the efficacy bounds corresponding to these different alpha levels. In contrast, there should be only one column for the futility bound, which represents the original alpha value.

What is the most effective way to design the gs_update_ahr function to accommodate a vector of alpha values? The guiding principle is to separate the calculation (in gs_update_ahr) from the formatting and presentation (in functions like summary and as_gt).

gs_update_ahr(x = ..., alpha = c(0.01, 0.0125, 0.025)) |> summary() |> as_gt()

Some references from gsDesign: