updated repeated_p and sequential_p

Author: xidongdxi

NAMESPACE

@@ -55,5 +55,6 @@ export(spending_hsd)
 export(spending_linear)
 export(spending_of)
 export(spending_pocock)
+export(spending_with_time)
 export(three_doses_two_primary_two_secondary)
 export(two_doses_two_primary_two_secondary)

R/print.gsd_graph_report.R

@@ -208,6 +208,21 @@ print.gsd_graph_report <- function(x, ..., precision = 6, indent = 2) {
     }
   }
 
+  # Repeated and sequential p-values (verbose) --------------------------------
+  if (!is.null(x$boundary_table)) {
+    section_break("Repeated p-values ($outputs$repeated_p)")
+    rep_p_display <- x$outputs$repeated_p
+    rep_p_display[] <- format(rep_p_display, digits = precision)
+    print(as.data.frame(rep_p_display))
+
+    cat("\n")
+    section_break("Sequential p-values ($outputs$sequential_p)")
+    seq_p_display <- x$outputs$sequential_p
+    seq_p_display[] <- format(seq_p_display, digits = precision)
+    print(as.data.frame(seq_p_display))
+    cat("\n")
+  }
+
   # Boundary table (verbose) ---------------------------------------------------
   if (!is.null(x$boundary_table)) {
     section_break("Boundary table ($boundary_table)")

R/spending_functions.R

@@ -141,3 +141,78 @@ spending_linear <- function(alpha, info_frac) {
   )
   alpha * info_frac
 }
+
+
+#' Create a spending function with a custom spending time
+#'
+#' @description
+#' Wraps an existing spending function to use a fixed **spending time** instead
+#' of the information fractions passed to it at runtime. This separates the
+#' alpha allocation schedule (determined by spending time) from the correlation
+#' structure (determined by information fractions in
+#' [graph_test_shortcut_gsd()]).
+#'
+#' This is useful in two common scenarios:
+#' * **Subgroup analyses**: all-subjects hypotheses use all-subjects event
+#'   counts for the correlation structure but subgroup event counts for
+#'   spending (see the spending time section of
+#'   `vignette("group-sequential-testing")`).
+#' * **Monitoring with changed final information**: when the actual total
+#'   information at the final analysis differs from the planned total, the
+#'   planned information fractions are used as spending time to preserve
+#'   boundaries at earlier analyses, while the actual information fractions
+#'   are used for the correlation structure (see the monitoring section of
+#'   `vignette("group-sequential-testing")`).
+#'
+#' @param spending_fn A spending function to wrap. Must accept two arguments:
+#'   `alpha` (significance level) and `info_frac` (information fraction), and
+#'   return the cumulative alpha spent.
+#' @param spending_time A numeric vector of spending time values. These replace
+#'   the `info_frac` argument when the wrapped function is called. The vector
+#'   is truncated to match the length of `info_frac` at runtime, which handles
+#'   interim analyses where fewer analyses have been conducted.
+#'
+#' @return A function with the same signature as `spending_fn` —
+#'   `function(alpha, info_frac)` — that internally uses `spending_time`
+#'   instead of `info_frac` for alpha allocation.
+#'
+#' @seealso [spending_of()], [spending_pocock()], [spending_hsd()],
+#'   [spending_linear()] for built-in spending functions,
+#'   [graph_test_shortcut_gsd()] for the graphical procedure with group
+#'   sequential designs.
+#'
+#' @export
+#'
+#' @examples
+#' # Subgroup spending time: use subgroup event fractions for spending
+#' # while info_frac uses all-subjects event fractions for correlation
+#' spending_h2 <- spending_with_time(
+#'   spending_of,
+#'   spending_time = c(185 / 295, 245 / 295, 1)
+#' )
+#'
+#' # The wrapped function has the standard (alpha, info_frac) signature
+#' # but ignores info_frac and uses spending_time internally
+#' spending_h2(0.01, c(0.5, 0.8, 1))
+#'
+#' # Monitoring: use planned info fractions for spending
+#' # when actual final information differs from planned
+#' spending_monitor <- spending_with_time(
+#'   spending_of,
+#'   spending_time = c(0.627, 0.831, 1)  # planned
+#' )
+#' # Call with actual info fractions (for correlation structure)
+#' spending_monitor(0.01, c(0.597, 0.790, 1))  # actual
+spending_with_time <- function(spending_fn, spending_time) {
+  stopifnot(
+    "spending_fn must be a function" = is.function(spending_fn),
+    "spending_time must be a numeric vector" = is.numeric(spending_time),
+    "spending_time must be in [0, 1]" =
+      all(spending_time >= 0 & spending_time <= 1)
+  )
+
+  function(alpha, info_frac) {
+    st <- spending_time[seq_along(info_frac)]
+    spending_fn(alpha, st)
+  }
+}

_pkgdown.yml

@@ -45,6 +45,7 @@ reference:
   - repeated_p
   - sequential_p
   - spending_of
+  - spending_with_time
   - gs_boundaries
   - gs_corr
 - title: Power simulation

man/spending_with_time.Rd

@@ -805,21 +805,8 @@ subgroup is a subset of the all-subjects population, and the subgroup events
 may better reflect the information available for the treatment effect
 comparison.
 
-We define a helper function that creates a spending function with a custom
-spending time:
-
-```{r spending-time-helper}
-# Factory function: create a spending function that uses spending_time
-# instead of info_frac for alpha allocation
-make_spending_with_time <- function(base_spending_fn, spending_time) {
-  function(alpha, info_frac) {
-    # Use spending_time for alpha allocation, ignoring info_frac
-    # Truncate to match length (handles interim stops)
-    st <- spending_time[seq_along(info_frac)]
-    base_spending_fn(alpha, st)
-  }
-}
-```
+The `spending_with_time()` function creates a spending function that uses
+a fixed spending time instead of the information fractions passed at runtime:
 
 For the oncology trial, $H_2$ (OS, all subjects) uses all-subjects OS events
 (`r paste(c(529, 700, 800), collapse = ", ")`) for the correlation structure
@@ -828,13 +815,13 @@ For the oncology trial, $H_2$ (OS, all subjects) uses all-subjects OS events
 
 ```{r spending-time-setup}
 # Spending time = subgroup event fractions (same as H1_OS_S)
-spending_h2 <- make_spending_with_time(
+spending_h2 <- spending_with_time(
   spending_of,
   spending_time = c(185 / 295, 245 / 295, 1)
 )
 
 # Similarly, H4 (PFS, all subjects) uses subgroup PFS event fractions
-spending_h4 <- make_spending_with_time(
+spending_h4 <- spending_with_time(
   spending_of,
   spending_time = c(265 / 310, 1)
 )
@@ -892,6 +879,134 @@ any function with the signature `function(alpha, info_frac)`, users can
 encode arbitrary spending behaviors — including spending time separation —
 without requiring changes to the `graph_test_shortcut_gsd()` interface.
 
+### Monitoring: Adjusting for Changed Final Information
+
+In practice, the total information (e.g., total number of events) at the
+final analysis may differ from what was planned at the design stage. When
+this happens, the information fractions at earlier analyses change
+retroactively — not because the data changed, but because the denominator
+(planned total) is now different. This creates a challenge: the boundaries
+at earlier analyses were already computed using the **planned** information
+fractions, but the correlation structure at the current analysis should
+reflect the **actual** information fractions.
+
+The spending time approach handles this naturally:
+
+- **Spending time**: use the planned information fractions to preserve the
+  boundaries at analyses 1 and 2 (which have already been applied).
+- **Information fraction** (`info_frac`): use the actual information fractions
+  for the correlation structure, since this reflects the true joint
+  distribution of the test statistics.
+
+Consider the OS subgroup hypothesis ($H_1$) in the oncology trial. The
+trial was designed with a planned maximum of 295 OS events in the subgroup,
+giving planned information fractions of
+(`r paste(round(c(185, 245, 295) / 295, 3), collapse = ", ")`).
+Suppose that by the time of the final analysis, 310 events have been
+observed instead of 295. The actual information fractions are now
+(`r paste(round(c(185, 245, 310) / 310, 3), collapse = ", ")`):
+
+```{r monitoring-setup}
+# Planned info fractions (used for boundaries at analyses 1 and 2)
+planned_if_h1 <- c(185 / 295, 245 / 295, 1)
+
+# Actual info fractions (more events than planned at final analysis)
+actual_if_h1 <- c(185 / 310, 245 / 310, 1)
+
+cat("Planned:", round(planned_if_h1, 4), "\n")
+cat("Actual: ", round(actual_if_h1, 4), "\n")
+```
+
+We create a spending function that uses the planned information fractions
+for alpha allocation, while the procedure uses the actual information
+fractions for the correlation structure:
+
+```{r monitoring-spending}
+# Spending function using planned info fractions
+spending_h1_monitor <- spending_with_time(
+  spending_of,
+  spending_time = planned_if_h1
+)
+```
+
+To illustrate, we compare the boundaries computed under three scenarios:
+
+1. **Planned**: both spending and correlation use planned info fractions
+   (the original design).
+2. **Naive update**: both spending and correlation use actual info fractions
+   (ignores that analyses 1 and 2 used planned boundaries).
+3. **Correct monitoring**: spending uses planned info fractions, correlation
+   uses actual info fractions.
+
+```{r monitoring-comparison}
+alpha_h1 <- 0.01  # H1's allocated alpha
+
+# Scenario 1: Planned (original design)
+bounds_planned <- gs_boundaries(alpha_h1, planned_if_h1, spending_of)
+
+# Scenario 2: Naive update (both use actual)
+bounds_naive <- gs_boundaries(alpha_h1, actual_if_h1, spending_of)
+
+# Scenario 3: Correct monitoring (spending=planned, correlation=actual)
+bounds_monitor <- gs_boundaries(alpha_h1, actual_if_h1, spending_h1_monitor)
+
+monitor_table <- data.frame(
+  Analysis = 1:3,
+  Planned.IF = round(planned_if_h1, 4),
+  Actual.IF = round(actual_if_h1, 4),
+  Boundary.Planned = bounds_planned$bounds_nominal,
+  Boundary.Naive = bounds_naive$bounds_nominal,
+  Boundary.Monitor = bounds_monitor$bounds_nominal
+)
+knitr::kable(monitor_table, digits = 6,
+             caption = paste("Boundaries under three scenarios",
+                             "(H1 with alpha = 0.01)"))
+```
+
+The key observations:
+
+- **Analyses 1 and 2**: the monitoring boundaries differ from the planned
+  boundaries because the correlation structure has changed (the actual
+  info fractions are smaller). However, the spending at these analyses is
+  preserved — the same cumulative alpha is allocated.
+- **Analysis 3**: the monitoring boundary reflects both the preserved
+  spending schedule and the updated correlation structure.
+- **Naive update**: changes the spending at all analyses, which is
+  inconsistent with the boundaries already applied at analyses 1 and 2.
+
+This approach extends naturally to the full graphical procedure. For
+monitoring at analysis 3, use the actual information fractions in
+`info_frac` and per-hypothesis spending functions with planned information
+fractions:
+
+```{r monitoring-full}
+# Actual info fractions for all hypotheses
+# (only OS hypotheses affected; PFS and ORR are complete)
+actual_if_onc <- info_frac_onc
+actual_if_onc["H1_OS_S", ] <- c(185 / 310, 245 / 310, 1)
+actual_if_onc["H2_OS_A", ] <- c(529 / 830, 700 / 830, 1)
+
+# Spending functions using planned info fractions for OS hypotheses
+spending_fn_monitor <- list(
+  spending_with_time(spending_of, info_frac_onc["H1_OS_S", ]),
+  spending_with_time(spending_of, info_frac_onc["H2_OS_A", ]),
+  spending_of,   # H3: PFS complete, no change
+  spending_of,   # H4: PFS complete, no change
+  spending_of,   # H5: ORR complete
+  spending_of    # H6: ORR complete
+)
+
+result_monitor <- graph_test_shortcut_gsd(
+  graph = g_onc,
+  p = p_onc,
+  alpha = alpha_onc,
+  info_frac = actual_if_onc,
+  spending_fn = spending_fn_monitor,
+  look_back = TRUE
+)
+print(result_monitor)
+```
+
 ## Additional Examples
 
 ### Different Spending Functions per Hypothesis