Fix roxygen2 issues for gsSurvCalendar()

keaven · Oct 2, 2023 · 4434e24 · 4434e24
1 parent c0f4663
commit 4434e24
Show file tree

Hide file tree

Showing 2 changed files with 292 additions and 114 deletions.
diff --git a/R/gsSurvCalendar.R b/R/gsSurvCalendar.R
@@ -1,131 +1,136 @@
 #' Time-to-event endpoint design with calendar timing of analyses
-#' 
-#' @param test.type 
-#' @param alpha Type I error rate. Default is 0.025 since 1-sided 
-#' testing is default.
-#' @param sided 1 for 1-sided testing, 2 for 2-sided testing.
-#' @param beta Type II error rate. Default is 0.10 
-#' (90% power); NULL if power is to be computed based on 
-#' other input values.
-#' @param astar Normally not specified. If \code{test.type=5} 
-#' or \code{6}, \code{astar} specifies the total probability 
-#' of crossing a lower bound at all analyses combined. This 
-#' will be changed to \code{1−alpha} when default value of 
-#' \code{0} is used. Since this is the expected usage, 
-#' normally \code{astar} is not specified by the user.
-#' @param sfu A spending function or a character string 
-#' indicating a boundary type (that is, “WT” for 
-#' Wang-Tsiatis bounds, “OF” for O'Brien-Fleming bounds and 
-#' “Pocock” for Pocock bounds). For one-sided and symmetric 
-#' two-sided testing is used to completely specify spending 
-#' (\code{test.type=1, 2}), \code{sfu}. The default value is 
-#' \code{sfHSD} which is a Hwang-Shih-DeCani spending function. 
-#' @param sfupar Real value, default is −4 which is an 
-#' O'Brien-Fleming-like conservative bound when used with the 
-#' default Hwang-Shih-DeCani spending function. This is a 
-#' real-vector for many spending functions. The parameter 
-#' sfupar specifies any parameters needed for the spending 
-#' function specified by sfu; this will be ignored for 
-#' spending functions (\code{sfLDOF}, \code{sfLDPocock}) 
-#' or bound types (\code{“OF”, “Pocock”}) 
-#' that do not require parameters.
-#' @param sfl Specifies the spending function for lower 
-#' boundary crossing probabilities when asymmetric, 
-#' two-sided testing is performed 
-#' (\code{test.type = 3, 4, 5, or 6}). Unlike the upper bound,
-#'  only spending functions are used to specify the lower bound.
-#'   The default value is \code{sfHSD} which is a 
-#'   Hwang-Shih-DeCani spending function. The parameter 
-#'   \code{sfl} is ignored for one-sided testing 
-#'   (\code{test.type=1}) or symmetric 2-sided testing 
-#'   (\code{test.type=2}). 
-#' @param sflpar Real value, default is −2, which, with the 
-#' default Hwang-Shih-DeCani spending function, specifies a 
-#' less conservative spending rate than the default for the 
-#' upper bound.
-#' @param calendarTime Vector of increasing positive numbers 
-#' with calendar times of analyses. Time 0 is start of 
-#' randomization.
-#' @param spending Select between calendar-based spending and 
-#' information-based spending.
-#' @param lambdaC scalar, vector or matrix of event hazard 
-#' rates for the control group; rows represent time periods while 
-#' columns represent strata; a vector implies a single stratum.
-#' @param hr hazard ratio (experimental/control) under the 
-#' alternate hypothesis (scalar).
-#' @param hr0 hazard ratio (experimental/control) under the null
-#'  hypothesis (scalar).
-#' @param eta scalar, vector or matrix of dropout hazard rates 
-#' for the control group; rows represent time periods while 
-#' columns represent strata; if entered as a scalar, rate is 
-#' constant across strata and time periods; if entered as a 
-#' vector, rates are constant across strata.
-#' @param etaE matrix dropout hazard rates for the experimental 
-#' group specified in like form as \code{eta}; if \code{NULL}, 
-#' this is set equal to \code{eta}.
-#' @param gamma a scalar, vector or matrix of rates of entry by 
-#' time period (rows) and strata (columns); if entered as a 
-#' scalar, rate is constant across strata and time periods; 
-#' if entered as a vector, rates are constant across strata.
-#' @param R a scalar or vector of durations of time periods for 
-#' recruitment rates specified in rows of gamma. Length is the 
-#' same as number of rows in gamma. Note that when variable 
-#' enrollment duration is specified (input T=NULL), the final 
-#' enrollment period is extended as long as needed.
-#' @param S a scalar or vector of durations of piecewise constant 
-#' event rates specified in rows of lambda, eta and etaE; this is 
-#' NULL if there is a single event rate per stratum (exponential 
-#' failure) or length of the number of rows in lambda minus 1, 
-#' otherwise.
-#' @param minfup A non-negative scalar less than the maximum value 
-#' in \code{calendarTime}. Enrollment will be cut off at the 
-#' difference between the maximum value in \code{calendarTime} 
-#' and \code{minfup}.
-#' @param ratio randomization ratio of experimental treatment 
-#' divided by control; normally a scalar, but may be a vector with
-#' length equal to number of strata.
-#' @param 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.
+#'
+#' @param test.type Test type. See \code{\link{gsSurv}}.
+#' @param alpha Type I error rate. Default is 0.025 since 1-sided
+#'   testing is default.
+#' @param sided \code{1} for 1-sided testing, \code{2} for 2-sided testing.
+#' @param beta Type II error rate. Default is 0.10
+#'   (90\% power); \code{NULL} if power is to be computed based on
+#'   other input values.
+#' @param astar Normally not specified. If \code{test.type = 5}
+#'   or \code{6}, \code{astar} specifies the total probability
+#'   of crossing a lower bound at all analyses combined. This
+#'   will be changed to \code{1 - alpha} when default value of
+#'   \code{0} is used. Since this is the expected usage,
+#'   normally \code{astar} is not specified by the user.
+#' @param sfu A spending function or a character string
+#'   indicating a boundary type (that is, \code{"WT"} for
+#'   Wang-Tsiatis bounds, \code{"OF"} for O'Brien-Fleming bounds and
+#'   \code{"Pocock"} for Pocock bounds). For one-sided and symmetric
+#'   two-sided testing is used to completely specify spending
+#'   (\code{test.type = 1}, \code{2}), \code{sfu}. The default value is
+#'   \code{sfHSD} which is a Hwang-Shih-DeCani spending function.
+#' @param sfupar Real value, default is \code{-4} which is an
+#'   O'Brien-Fleming-like conservative bound when used with the
+#'   default Hwang-Shih-DeCani spending function. This is a
+#'   real-vector for many spending functions. The parameter
+#'   \code{sfupar} specifies any parameters needed for the spending
+#'   function specified by \code{sfu}; this will be ignored for
+#'   spending functions (\code{sfLDOF}, \code{sfLDPocock})
+#'   or bound types (\code{"OF"}, \code{"Pocock"})
+#'   that do not require parameters.
+#' @param sfl Specifies the spending function for lower
+#'   boundary crossing probabilities when asymmetric,
+#'   two-sided testing is performed
+#'   (\code{test.type = 3}, \code{4}, \code{5}, or \code{6}).
+#'   Unlike the upper bound,
+#'   only spending functions are used to specify the lower bound.
+#'   The default value is \code{sfHSD} which is a
+#'   Hwang-Shih-DeCani spending function. The parameter
+#'   \code{sfl} is ignored for one-sided testing
+#'   (\code{test.type = 1}) or symmetric 2-sided testing
+#'   (\code{test.type = 2}).
+#' @param sflpar Real value, default is \code{-2}, which, with the
+#'   default Hwang-Shih-DeCani spending function, specifies a
+#'   less conservative spending rate than the default for the
+#'   upper bound.
+#' @param calendarTime Vector of increasing positive numbers
+#'   with calendar times of analyses. Time 0 is start of
+#'   randomization.
+#' @param spending Select between calendar-based spending and
+#'   information-based spending.
+#' @param lambdaC Scalar, vector or matrix of event hazard
+#'   rates for the control group; rows represent time periods while
+#'   columns represent strata; a vector implies a single stratum.
+#' @param hr Hazard ratio (experimental/control) under the
+#'   alternate hypothesis (scalar).
+#' @param hr0 Hazard ratio (experimental/control) under the null
+#'   hypothesis (scalar).
+#' @param eta Scalar, vector or matrix of dropout hazard rates
+#'   for the control group; rows represent time periods while
+#'   columns represent strata; if entered as a scalar, rate is
+#'   constant across strata and time periods; if entered as a
+#'   vector, rates are constant across strata.
+#' @param etaE Matrix dropout hazard rates for the experimental
+#'   group specified in like form as \code{eta}; if \code{NULL},
+#'   this is set equal to \code{eta}.
+#' @param gamma A scalar, vector or matrix of rates of entry by
+#'   time period (rows) and strata (columns); if entered as a
+#'   scalar, rate is constant across strata and time periods;
+#'   if entered as a vector, rates are constant across strata.
+#' @param R A scalar or vector of durations of time periods for
+#'   recruitment rates specified in rows of \code{gamma}. Length is the
+#'   same as number of rows in \code{gamma}. Note that when variable
+#'   enrollment duration is specified (input \code{T = NULL}), the final
+#'   enrollment period is extended as long as needed.
+#' @param S A scalar or vector of durations of piecewise constant
+#'   event rates specified in rows of \code{lambda}, \code{eta} and \code{etaE};
+#'   this is \code{NULL} if there is a single event rate per stratum
+#'   (exponential failure) or length of the number of rows in \code{lambda}
+#'   minus 1, otherwise.
+#' @param minfup A non-negative scalar less than the maximum value
+#'   in \code{calendarTime}. Enrollment will be cut off at the
+#'   difference between the maximum value in \code{calendarTime}
+#'   and \code{minfup}.
+#' @param ratio Randomization ratio of experimental treatment
+#'   divided by control; normally a scalar, but may be a vector with
+#'   length equal to number of strata.
+#' @param 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 \code{r} will not be changed by
+#'   the user.
+#' @param tol Tolerance for error passed to the \code{\link{gsDesign}} function.
+#'
+#' @export
+#'
+#' @rdname gsSurvCalendar
 #'
 #' @examples
 #' # First example: while timing is calendar-based, spending is event-based
 #' x <- gsSurvCalendar() %>% toInteger()
+#' gsBoundSummary(x)
+#' 
 #' # Second example: both timing and spending are calendar-based
 #' # This results in less spending at interims and leaves more for final analysis
-#' gsBoundSummary(x)
 #' y <- gsSurvCalendar(spending = "calendar") %>% toInteger()
 #' gsBoundSummary(y)
+#'
 #' # Note that calendar timing for spending relates to planned timing for y
 #' # rather than timing in y after toInteger() conversion
-#' y$usTime # Values plugged into spending function for calendar time
-#' y$T / max(y$T) # Actual calendar fraction from design after toInteger() conversion
-#' 
-#' @export
-#' @rdname gsSurvCalendar
+#'
+#' # Values plugged into spending function for calendar time
+#' y$usTime
+#' # Actual calendar fraction from design after toInteger() conversion
+#' y$T / max(y$T)
 gsSurvCalendar <- function(
-    test.type = 4, alpha = 0.025, sided = 1, beta = 0.1, astar = 0, 
+    test.type = 4, alpha = 0.025, sided = 1, beta = 0.1, astar = 0,
     sfu = gsDesign::sfHSD, sfupar = -4,
     sfl = gsDesign::sfHSD, sflpar = -2,
-    calendarTime=c(12, 24, 36),
+    calendarTime = c(12, 24, 36),
     spending = c("information", "calendar"),
     lambdaC = log(2) / 6, hr = .6, hr0 = 1, eta = 0, etaE = NULL,
     gamma = 1, R = 12, S = NULL, minfup = 18, ratio = 1,
-    r = 18, tol = 1e-06
-)
-{
+    r = 18, tol = 1e-06) {
   x <- nSurv(
     lambdaC = lambdaC, hr = hr, hr0 = hr0, eta = eta, etaE = etaE,
-    gamma = gamma, R = R, S = S, T = max(calendarTime), 
+    gamma = gamma, R = R, S = S, T = max(calendarTime),
     minfup = minfup, ratio = ratio,
     alpha = alpha, beta = beta, sided = sided
   )
-  
-  # Get interim expected event counts and sample size based on 
+
+  # Get interim expected event counts and sample size based on
   # input gamma, eta, lambdaC, R, S, minfup
-
   eDC <- NULL
   eDE <- NULL
   eNC <- NULL
@@ -142,16 +147,21 @@ gsSurvCalendar <- function(
   timing <- rowSums(eDC) + rowSums(eDE)
   timing <- timing / max(timing)
   # if calendar spending, set usTime, lsTime
-  if(spending[1] == "calendar"){lsTime <- calendarTime / max(calendarTime)
-  }else{lsTime <- NULL}
+  if (spending[1] == "calendar") {
+    lsTime <- calendarTime / max(calendarTime)
+  } else {
+    lsTime <- NULL
+  }
   usTime <- lsTime
-  
+
   # Now inflate events to get targeted power
-  y <- gsDesign::gsDesign(k = k, test.type = test.type, alpha = alpha / sided,
-                          beta = beta, astar = astar, n.fix = x$d, timing = timing,
-                          sfu = sfu, sfupar = sfupar, sfl = sfl, sflpar = sflpar, tol = tol,
-                          delta1 = log(hr), delta0 = log(hr0),
-                          usTime = usTime, lsTime = lsTime)
+  y <- gsDesign::gsDesign(
+    k = k, test.type = test.type, alpha = alpha / sided,
+    beta = beta, astar = astar, n.fix = x$d, timing = timing,
+    sfu = sfu, sfupar = sfupar, sfl = sfl, sflpar = sflpar, tol = tol,
+    delta1 = log(hr), delta0 = log(hr0),
+    usTime = usTime, lsTime = lsTime
+  )
   y$hr <- hr
   y$hr0 <- hr0
   y$R <- x$R
@@ -172,7 +182,7 @@ gsSurvCalendar <- function(
   y$tol <- tol
   y$T <- calendarTime
   class(y) <- c("gsSurv", "gsDesign")
-  
+
   nameR <- nameperiod(cumsum(y$R))
   stratnames <- paste("Stratum", 1:ncol(y$lambdaC))
   if (is.null(y$S)) {