Standardize documentation in package.R

R/gsDesign-package.R

@@ -0,0 +1,4 @@
+#' @keywords internal
+#' @aliases gsDesign-package
+"_PACKAGE"
+NULL

R/gsDesign.R

@@ -61,7 +61,7 @@
 #' @note The gsDesign technical manual is available at
 #'   \url{https://keaven.github.io/gsd-tech-manual/}.
 #' @author Keaven Anderson \email{keaven_anderson@@merck.com}
-#' @seealso \link{gsDesign package overview}, \code{\link{gsDesign}},
+#' @seealso \code{vignette("gsDesignPackageOverview")}, \code{\link{gsDesign}},
 #' \code{\link{gsProbability}}
 #' @references Jennison C and Turnbull BW (2000), \emph{Group Sequential
 #' Methods with Applications to Clinical Trials}. Boca Raton: Chapman and Hall.
@@ -281,7 +281,7 @@ gsBound1 <- function(theta, I, a, probhi, tol = 0.000001, r = 18, printerr = 0)
 #' 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.  See details,
-#' \link{Spending_Function_Overview}, manual and examples.
+#' \code{vignette("SpendingFunctionOverview")}, manual and examples.
 #' @param sfupar Real value, default is \eqn{-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
@@ -366,13 +366,13 @@ gsBound1 <- function(theta, I, a, probhi, tol = 0.000001, r = 18, printerr = 0)
 #' \item{endpoint}{As input.} \item{delta1}{As input.} \item{delta0}{As input.}
 #' \item{overrun}{As input.} \item{usTime}{As input.} \item{lsTime}{As input.} \item{upper}{Upper bound spending function,
 #' boundary and boundary crossing probabilities under the NULL and alternate
-#' hypotheses. See \link{Spending_Function_Overview} and manual for further
+#' hypotheses. See \code{vignette("SpendingFunctionOverview")} and manual for further
 #' details.} \item{lower}{Lower bound spending function, boundary and boundary
 #' crossing probabilities at each analysis. Lower spending is under alternative
 #' hypothesis (beta spending) for \code{test.type=3} or \code{4}.  For
 #' \code{test.type=2}, \code{5} or \code{6}, lower spending is under the null
 #' hypothesis. For \code{test.type=1}, output value is \code{NULL}. See
-#' \link{Spending_Function_Overview} and manual.} \item{theta}{Standarized
+#' \code{vignette("SpendingFunctionOverview")} and manual.} \item{theta}{Standarized
 #' effect size under null (0) and alternate hypothesis. If \code{delta} is
 #' input, \code{theta[1]=delta}. If \code{n.fix} is input, \code{theta[1]} is
 #' computed using a standard sample size formula (pseudocode):
@@ -426,9 +426,9 @@ gsBound1 <- function(theta, I, a, probhi, tol = 0.000001, r = 18, printerr = 0)
 #' @note The gsDesign technical manual is available at
 #'   \url{https://keaven.github.io/gsd-tech-manual/}.
 #' @author Keaven Anderson \email{keaven_anderson@@merck.com}
-#' @seealso \link{gsDesign package overview}, \link{gsBoundSummary}, 
+#' @seealso \code{vignette("gsDesignPackageOverview")}, \link{gsBoundSummary},
 #' \link{plot.gsDesign},
-#' \code{\link{gsProbability}}, \link{Spending_Function_Overview},
+#' \code{\link{gsProbability}}, \code{vignette("SpendingFunctionOverview")},
 #' @references Jennison C and Turnbull BW (2000), \emph{Group Sequential
 #' Methods with Applications to Clinical Trials}. Boca Raton: Chapman and Hall.
 #' Lan KK, DeMets DL (1989). Group sequential procedures: calendar versus information 
@@ -639,7 +639,7 @@ gsDesign <- function(k = 3, test.type = 4, alpha = 0.025, beta = 0.1, astar = 0,
 #'   \url{https://keaven.github.io/gsd-tech-manual/}.
 #' @author Keaven Anderson \email{keaven_anderson@@merck.com}
 #' @seealso \link{plot.gsDesign}, \code{\link{gsDesign}},
-#' \link{gsDesign package overview}
+#' \code{vignette("gsDesignPackageOverview")}
 #' @references Jennison C and Turnbull BW (2000), \emph{Group Sequential
 #' Methods with Applications to Clinical Trials}. Boca Raton: Chapman and Hall.
 #' @keywords design

R/gsMethods.R

@@ -777,6 +777,7 @@ sfprint <- function(x) {
 
 # summary.spendfn roxy [sinew] ----
 #' @export
+#' @rdname spendingFunction
 #' @aliases summary.spendfn
 # summary.spendfn function [sinew] ----
 summary.spendfn <- function(object, ...) {

R/gsSpending.R

@@ -55,7 +55,7 @@
 #' parameterization, all four values must be between 0 and 1 and \code{t1 <
 #' t2}, \code{u1 < u2}.
 #' @return An object of type \code{spendfn}. 
-#' See \code{\link{Spending_Function_Overview}} for further details.
+#' See \code{vignette("SpendingFunctionOverview")} for further details.
 #' @examples
 #' library(ggplot2)
 #' # design a 4-analysis trial using a Kim-DeMets spending function
@@ -265,8 +265,8 @@ sfLogistic <- function(alpha, t, param) {
 #'   to closely approximate an O'Brien-Fleming design. An example is given below.
 #'   The manual is available at <https://keaven.github.io/gsd-tech-manual/>.
 #' @author Keaven Anderson \email{keaven_anderson@@merck.com}
-#' @seealso \link{Spending_Function_Overview}, \code{\link{gsDesign}},
-#' \link{gsDesign package overview}
+#' @seealso \code{vignette("SpendingFunctionOverview")}, \code{\link{gsDesign}},
+#' \code{vignette("gsDesignPackageOverview")}
 #' @references Anderson KM and Clark JB (2009), Fitting spending functions.
 #' \emph{Statistics in Medicine}; 29:321-327.
 #'
@@ -532,7 +532,7 @@ sfExtremeValue2 <- function(alpha, t, param) {
 #' function will be computed.
 #' @param param A single real value specifying the gamma parameter for which
 #' Hwang-Shih-DeCani spending is to be computed; allowable range is [-40, 40]
-#' @return An object of type \code{spendfn}. See \link{Spending_Function_Overview} for further details.
+#' @return An object of type \code{spendfn}. See \code{vignette("SpendingFunctionOverview")} for further details.
 #' @examples
 #' library(ggplot2)
 #' # design a 4-analysis trial using a Hwang-Shih-DeCani spending function
@@ -567,8 +567,8 @@ sfExtremeValue2 <- function(alpha, t, param) {
 #' @note The gsDesign technical manual is available at
 #'   \url{https://keaven.github.io/gsd-tech-manual/}.
 #' @author Keaven Anderson \email{keaven_anderson@@merck.com}
-#' @seealso \link{Spending_Function_Overview}, \code{\link{gsDesign}},
-#' \link{gsDesign package overview}
+#' @seealso \code{vignette("SpendingFunctionOverview")}, \code{\link{gsDesign}},
+#' \code{vignette("gsDesignPackageOverview")}
 #' @references Jennison C and Turnbull BW (2000), \emph{Group Sequential
 #' Methods with Applications to Clinical Trials}. Boca Raton: Chapman and Hall.
 #' @keywords design
@@ -683,8 +683,8 @@ sfHSD <- function(alpha, t, param) {
 #' @note The gsDesign technical manual is available at
 #'   \url{https://keaven.github.io/gsd-tech-manual/}.
 #' @author Keaven Anderson \email{keaven_anderson@@merck.com}
-#' @seealso \link{Spending_Function_Overview}, \code{\link{gsDesign}},
-#' \link{gsDesign package overview}
+#' @seealso \code{vignette("SpendingFunctionOverview")}, \code{\link{gsDesign}},
+#' \code{vignette("gsDesignPackageOverview")}
 #' @references Jennison C and Turnbull BW (2000), \emph{Group Sequential
 #' Methods with Applications to Clinical Trials}. Boca Raton: Chapman and Hall.
 #'
@@ -848,7 +848,7 @@ sfNormal <- function(alpha, t, param) {
 #' (\code{param[m]}) will be the final analysis, using any remaining error that
 #' was not previously spent.
 #'
-#' See \code{\link{Spending_Function_Overview}} for further details.
+#' See \code{vignette("SpendingFunctionOverview")} for further details.
 #' @examples
 #' library(ggplot2)
 #' # set up alpha spending and beta spending to be piecewise linear
@@ -919,8 +919,8 @@ sfNormal <- function(alpha, t, param) {
 #' @note The gsDesign technical manual is available at
 #'   \url{https://keaven.github.io/gsd-tech-manual/}.
 #' @author Keaven Anderson \email{keaven_anderson@@merck.com}
-#' @seealso \link{Spending_Function_Overview}, \code{\link{gsDesign}},
-#' \link{gsDesign package overview}
+#' @seealso \code{vignette("SpendingFunctionOverview")}, \code{\link{gsDesign}},
+#' \code{vignette("gsDesignPackageOverview")}
 #' @references Jennison C and Turnbull BW (2000), \emph{Group Sequential
 #' Methods with Applications to Clinical Trials}. Boca Raton: Chapman and Hall.
 #' @keywords design
@@ -1039,7 +1039,7 @@ sfStep <- function(alpha, t, param) {
 #' just the points they wish to specify. If using \code{sfPoints()} in a
 #' design, it is recommended to specify how to interpolate between the
 #' specified points (e.g,, linear interpolation); also consider fitting smooth
-#' spending functions; see \link{Spending_Function_Overview}.
+#' spending functions; see \code{vignette("SpendingFunctionOverview")}.
 #'
 #'
 #' @param alpha Real value \eqn{> 0} and no more than 1. Normally,
@@ -1101,8 +1101,8 @@ sfStep <- function(alpha, t, param) {
 #' @note The gsDesign technical manual is available at
 #'   \url{https://keaven.github.io/gsd-tech-manual/}.
 #' @author Keaven Anderson \email{keaven_anderson@@merck.com}
-#' @seealso \link{Spending_Function_Overview}, \code{\link{gsDesign}},
-#' \link{gsDesign package overview}, \link{sfLogistic}
+#' @seealso \code{vignette("SpendingFunctionOverview")}, \code{\link{gsDesign}},
+#' \code{vignette("gsDesignPackageOverview")}, \link{sfLogistic}
 #' @references Jennison C and Turnbull BW (2000), \emph{Group Sequential
 #' Methods with Applications to Clinical Trials}. Boca Raton: Chapman and Hall.
 #' @keywords design
@@ -1180,7 +1180,7 @@ sfPoints <- function(alpha, t, param) {
 #' @param param A single, positive value specifying the \eqn{\rho}{rho}
 #' parameter for which Kim-DeMets spending is to be computed; allowable range
 #' is (0,50]
-#' @return An object of type \code{spendfn}. See \link{Spending_Function_Overview} for further details.
+#' @return An object of type \code{spendfn}. See \code{vignette("SpendingFunctionOverview")} for further details.
 #' @examples
 #' library(ggplot2)
 #' # design a 4-analysis trial using a Kim-DeMets spending function
@@ -1218,8 +1218,8 @@ sfPoints <- function(alpha, t, param) {
 #' @note The gsDesign technical manual is available at
 #'   \url{https://keaven.github.io/gsd-tech-manual/}.
 #' @author Keaven Anderson \email{keaven_anderson@@merck.com}
-#' @seealso \link{Spending_Function_Overview}, \code{\link{gsDesign}},
-#' \link{gsDesign package overview}
+#' @seealso \code{vignette("SpendingFunctionOverview")}, \code{\link{gsDesign}},
+#' \code{vignette("gsDesignPackageOverview")}
 #' @references Jennison C and Turnbull BW (2000), \emph{Group Sequential
 #' Methods with Applications to Clinical Trials}. Boca Raton: Chapman and Hall.
 #' @keywords design
@@ -1338,8 +1338,8 @@ sfPower <- function(alpha, t, param) {
 #' @note The gsDesign technical manual is available at
 #'   \url{https://keaven.github.io/gsd-tech-manual/}.
 #' @author Keaven Anderson \email{keaven_anderson@@merck.com}
-#' @seealso \link{Spending_Function_Overview}, \code{\link{gsDesign}},
-#' \link{gsDesign package overview}
+#' @seealso \code{vignette("SpendingFunctionOverview")}, \code{\link{gsDesign}},
+#' \code{vignette("gsDesignPackageOverview")}
 #' @references Jennison C and Turnbull BW (2000), \emph{Group Sequential
 #' Methods with Applications to Clinical Trials}. Boca Raton: Chapman and Hall.
 #' @keywords design
@@ -1475,7 +1475,7 @@ sfTDist <- function(alpha, t, param) {
 #' to 1; 0 <= trange[1]<trange[2] <=1; for sfGapped, trange[1] must be > 0),
 #' and param (null for a spending function with no parameters or a scalar or
 #' vector of parameters needed to fully specify the spending function in sf).
-#' @return An object of type \code{spendfn}. See \code{\link{Spending_Function_Overview}} 
+#' @return An object of type \code{spendfn}. See \code{vignette("SpendingFunctionOverview")}
 #' for further details.
 #' @examples
 #' 
@@ -1553,8 +1553,8 @@ sfTDist <- function(alpha, t, param) {
 #' @note The gsDesign technical manual is available at
 #'   \url{https://keaven.github.io/gsd-tech-manual/}.
 #' @author Keaven Anderson \email{keaven_anderson@@merck.com}
-#' @seealso \link{Spending_Function_Overview}, \code{\link{gsDesign}},
-#' \link{gsDesign package overview}
+#' @seealso \code{vignette("SpendingFunctionOverview")}, \code{\link{gsDesign}},
+#' \code{vignette("gsDesignPackageOverview")}
 #' @references Jennison C and Turnbull BW (2000), \emph{Group Sequential
 #' Methods with Applications to Clinical Trials}. Boca Raton: Chapman and Hall.
 #' @keywords design
@@ -1673,8 +1673,127 @@ sfGapped <- function(alpha, t, param) {
 }
 
 # spendingFunction roxy [sinew] ----
+#' @title Spending Function
+#'
+#' @param alpha Real value \eqn{> 0} and no more than 1. Defaults in calls to
+#'   \code{gsDesign()} are \code{alpha=0.025} for one-sided Type I error
+#'   specification and \code{alpha=0.1} for Type II error specification.
+#'   However, this could be set to 1 if, for descriptive purposes, you wish to
+#'   see the proportion of spending as a function of the proportion of sample
+#'   size/information.
+#' @param t A vector of points with increasing values from 0 to 1, inclusive.
+#'   Values of the proportion of sample size/information for which the spending
+#'   function will be computed.
+#' @param param A single real value or a vector of real values specifying the
+#'   spending function parameter(s); this must be appropriately matched to the
+#'   spending function specified.
+#' @param object A spendfn object to be summarized.
+#' @param ... Not currently used.
+#'
+#' @return
+#' \code{spendingFunction} and spending functions in general produce an
+#' object of type \code{spendfn}.
+#' \item{name}{A character string with the name of the spending function.}
+#' \item{param}{any parameters used for the spending function.}
+#' \item{parname}{a character string or strings with the name(s) of
+#' the parameter(s) in \code{param}.}
+#' \item{sf}{the spending function specified.}
+#' \item{spend}{a vector of cumulative spending values corresponding to
+#' the input values in \code{t}.}
+#' \item{bound}{this is null when returned from the spending function,
+#' but is set in \code{gsDesign()} if the spending function is called
+#' from there.  Contains z-values for bounds of a design.}
+#' \item{prob}{this is null when returned from the spending function,
+#' but is set in \code{gsDesign()} if the spending function is called
+#' from there.  Contains probabilities of boundary crossing at \code{i}-th
+#' analysis for \code{j}-th theta value input to \code{gsDesign()} in
+#' \code{prob[i,j]}.}
+#'
 #' @export
-#' @aliases spendingFunction
+#'
+#' @rdname spendingFunction
+#'
+#' @note The gsDesign technical manual is available at
+#'   \url{https://keaven.github.io/gsd-tech-manual/}.
+#'
+#' @author Keaven Anderson \email{keaven_anderson@@merck.com}
+#'
+#' @seealso \code{\link{gsDesign}}, \code{\link{sfHSD}}, \code{\link{sfPower}},
+#' \code{\link{sfLogistic}}, \code{\link{sfExponential}},
+#' \code{\link{sfTruncated}}, \code{vignette("gsDesignPackageOverview")}
+#'
+#' @references Jennison C and Turnbull BW (2000), \emph{Group Sequential
+#' Methods with Applications to Clinical Trials}. Boca Raton: Chapman and Hall.
+#'
+#' @keywords design
+#'
+#' @examples
+#' # Example 1: simple example showing what most users need to know
+#'
+#' # Design a 4-analysis trial using a Hwang-Shih-DeCani spending function
+#' # for both lower and upper bounds
+#' x <- gsDesign(k = 4, sfu = sfHSD, sfupar = -2, sfl = sfHSD, sflpar = 1)
+#'
+#' # Print the design
+#' x
+#' # Summarize the spending functions
+#' summary(x$upper)
+#' summary(x$lower)
+#'
+#' # Plot the alpha- and beta-spending functions
+#' plot(x, plottype = 5)
+#'
+#' # What happens to summary if we used a boundary function design
+#' x <- gsDesign(test.type = 2, sfu = "OF")
+#' y <- gsDesign(test.type = 1, sfu = "WT", sfupar = .25)
+#' summary(x$upper)
+#' summary(y$upper)
+#'
+#' # Example 2: advanced example: writing a new spending function
+#' # Most users may ignore this!
+#'
+#' # Implementation of 2-parameter version of
+#' # beta distribution spending function
+#' # assumes t and alpha are appropriately specified (does not check!)
+#' sfbdist <- function(alpha, t, param) {
+#'   # Check inputs
+#'   checkVector(param, "numeric", c(0, Inf), c(FALSE, TRUE))
+#'   if (length(param) != 2) {
+#'     stop(
+#'       "b-dist example spending function parameter must be of length 2"
+#'     )
+#'   }
+#'
+#'   # Set spending using cumulative beta distribution and return
+#'   x <- list(
+#'     name = "B-dist example", param = param, parname = c("a", "b"),
+#'     sf = sfbdist, spend = alpha *
+#'       pbeta(t, param[1], param[2]), bound = NULL, prob = NULL
+#'   )
+#'
+#'   class(x) <- "spendfn"
+#'
+#'   x
+#' }
+#'
+#' # Now try it out!
+#' # Plot some example beta (lower bound) spending functions using
+#' # the beta distribution spending function
+#' t <- 0:100 / 100
+#' plot(
+#'   t, sfbdist(1, t, c(2, 1))$spend,
+#'   type = "l",
+#'   xlab = "Proportion of information",
+#'   ylab = "Cumulative proportion of total spending",
+#'   main = "Beta distribution Spending Function Example"
+#' )
+#' lines(t, sfbdist(1, t, c(6, 4))$spend, lty = 2)
+#' lines(t, sfbdist(1, t, c(.5, .5))$spend, lty = 3)
+#' lines(t, sfbdist(1, t, c(.6, 2))$spend, lty = 4)
+#' legend(
+#'   x = c(.65, 1), y = 1 * c(0, .25), lty = 1:4,
+#'   legend = c("a=2, b=1", "a=6, b=4", "a=0.5, b=0.5", "a=0.6, b=2")
+#' )
 # spendingFunction function [sinew] ----
 spendingFunction <- function(alpha, t, param) {
   checkScalar(alpha, "numeric", c(0, Inf), c(FALSE, FALSE))

R/gsSurv.R

@@ -156,7 +156,7 @@ eEvents1 <- function(lambda = 1, eta = 0, gamma = 1, R = 1, S = NULL,
 #'
 #' @aliases print.eEvents
 #' @author Keaven Anderson \email{keaven_anderson@@merck.com}
-#' @seealso \link{gsDesign package overview}, \link{plot.gsDesign},
+#' @seealso \code{vignette("gsDesignPackageOverview")}, \link{plot.gsDesign},
 #' \code{\link{gsDesign}}, \code{\link{gsHR}},
 #' \code{\link{nSurvival}}
 #' @references Lachin JM and Foulkes MA (1986), Evaluation of Sample Size and
@@ -840,7 +840,7 @@ KT <- function(alpha = .025, sided = 1, beta = .1,
 #' 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.  See details,
-#' \link{Spending_Function_Overview}, manual and examples.
+#' \code{vignette("SpendingFunctionOverview")}, manual and examples.
 #' @param sfupar Real value, default is \eqn{-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
@@ -962,7 +962,7 @@ KT <- function(alpha = .025, sided = 1, beta = .1,
 #' \code{tEventsIA()} returns the same structure as \code{nEventsIA(..., simple=TRUE)} when
 #' @author Keaven Anderson \email{keaven_anderson@@merck.com}
 #' @seealso \code{\link{gsBoundSummary}}, \code{\link{xprint}},
-#' \link{gsDesign package overview}, \link{plot.gsDesign},
+#' \code{vignette("gsDesignPackageOverview")}, \link{plot.gsDesign},
 #' \code{\link{gsDesign}}, \code{\link{gsHR}}, \code{\link{nSurvival}}
 #' @references Kim KM and Tsiatis AA (1990), Study duration for clinical trials
 #' with survival response and early stopping rule. \emph{Biometrics}, 46, 81-92

R/gsSurvival.R

@@ -198,7 +198,7 @@
 #' hrn2z(hr = 1 / .6, n = 75, ratio = 2)
 #' @author Shanhong Guan \email{shanhong.guan@@gmail.com}, Keaven Anderson
 #' \email{keaven_anderson@@merck.com}
-#' @seealso \link{gsDesign package overview}, \link{plot.gsDesign}, 
+#' @seealso \code{vignette("gsDesignPackageOverview")}, \link{plot.gsDesign},
 #' \link{gsDesign}, \link{gsHR}
 #' @references Lachin JM and Foulkes MA (1986), Evaluation of Sample Size and
 #' Power for Analyses of Survival with Allowance for Nonuniform Patient Entry,

R/gsWTPT.R

@@ -35,7 +35,7 @@
 # @note The gsDesign technical manual is available at
 #   \url{https://keaven.github.io/gsd-tech-manual/}.
 # @author Keaven Anderson \email{keaven_anderson@@merck.com}
-# @seealso \code{\link{Spending_Function_Overview}, \link{gsDesign}},
+# @seealso \code{vignette("SpendingFunctionOverview")}, \code{\link{gsDesign}},
 # \code{\link{gsProbability}}
 # @references Jennison C and Turnbull BW (2000), \emph{Group Sequential
 # Methods with Applications to Clinical Trials}. Boca Raton: Chapman and Hall.