[Gsdesign-commits] r279 - in pkg/gsDesign: . R man tex/Sections
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Tue Jul 19 15:06:45 CEST 2011
Author: keaven
Date: 2011-07-19 15:06:45 +0200 (Tue, 19 Jul 2011)
New Revision: 279
Modified:
pkg/gsDesign/DESCRIPTION
pkg/gsDesign/NAMESPACE
pkg/gsDesign/R/gsCP.R
pkg/gsDesign/R/gsDesign.R
pkg/gsDesign/R/gsNormalGrid.R
pkg/gsDesign/man/gsCP.Rd
pkg/gsDesign/tex/Sections/DefaultDesign.tex
Log:
2.5 updates focus on prediction intervals, predictive power
Modified: pkg/gsDesign/DESCRIPTION
===================================================================
--- pkg/gsDesign/DESCRIPTION 2011-07-19 12:59:35 UTC (rev 278)
+++ pkg/gsDesign/DESCRIPTION 2011-07-19 13:06:45 UTC (rev 279)
@@ -1,10 +1,11 @@
Package: gsDesign
-Version: 2.4-01
+Version: 2.5-02
Title: Group Sequential Design
Author: Keaven Anderson
Maintainer: Keaven Anderson <keaven_anderson at merck.com>
Depends: ggplot2, xtable
-Description: gsDesign is a package that derives group sequential designs and describes their properties.
+Description: gsDesign is a package that derives group sequential designs and describes their properties. 2.5 additions focus on predictive power update and
+prediction intervals.
License: GPL (>= 2)
Copyright: Copyright 2010, Merck Research Laboratories
Packaged: Thu Aug 6 17:28:16 2009; anderkea
Modified: pkg/gsDesign/NAMESPACE
===================================================================
--- pkg/gsDesign/NAMESPACE 2011-07-19 12:59:35 UTC (rev 278)
+++ pkg/gsDesign/NAMESPACE 2011-07-19 13:06:45 UTC (rev 279)
@@ -1,5 +1,5 @@
useDynLib(gsDesign)
-export(gsBoundCP, gsCP, gsPP, gsPOS, gsCPOS, gsDensity)
+export(gsBoundCP, gsCP, gsPP, gsPI, gsPOS, gsCPOS, gsDensity, gsPosterior)
export(gsCPz, gsHR, gsDelta, gsBValue, gsRR)
export(gsBound, gsBound1, gsDesign, gsProbability)
export(ciBinomial, nBinomial, simBinomial, testBinomial, gsBinomialExact)
Modified: pkg/gsDesign/R/gsCP.R
===================================================================
--- pkg/gsDesign/R/gsCP.R 2011-07-19 12:59:35 UTC (rev 278)
+++ pkg/gsDesign/R/gsCP.R 2011-07-19 13:06:45 UTC (rev 279)
@@ -4,8 +4,10 @@
# Exported Functions:
#
# gsCP
+# gsBoundCP
# gsPP
-# gsBoundCP
+# gsPosterior
+# gsPI
#
# Hidden Functions:
#
@@ -17,6 +19,7 @@
#
# R Version: 2.7.2
#
+# Updated: added gsPosterior, 8May2011, K. Anderson
##################################################################################
###
@@ -73,26 +76,50 @@
gsPP <- function(x, i=1, zi=0, theta=c(0,3), wgts=c(.5,.5), r=18, total=TRUE)
{ if (!(is(x, "gsProbability") || is(x, "gsDesign")))
- {
- stop("gsPP must be called with class of x either gsProbability or gsDesign")
+ { stop("gsPP: class(x) must be gsProbability or gsDesign")
}
test.type <- ifelse(is(x, "gsProbability"), 3, x$test.type)
checkScalar(i, "integer", c(1, x$k-1))
- checkScalar(zi, "numeric", c(ifelse(test.type==1, -20, x$lower$bound[i]), x$upper$bound[i]), c(TRUE,TRUE))
- checkVector(wgts, "numeric", c(-Inf, Inf), c(FALSE, FALSE))
+ checkScalar(zi, "numeric", c(-Inf,Inf), c(FALSE, FALSE))
+ checkVector(wgts, "numeric", c(0, Inf), c(TRUE, FALSE))
checkVector(theta, "numeric", c(-Inf,Inf), c(FALSE, FALSE))
checkLengths(theta, wgts)
checkScalar(r, "integer", c(1, 80))
-
cp <- gsCP(x = x, i = i, theta = theta, zi = zi, r = r)
- gsDen <- gsDensity(x, theta=theta, i=i, zi=zi, r=r)
- pp <- cp$upper$prob %*% t(gsDen$density * wgts) / sum(gsDen$density * wgts)
+ gsDen <- dnorm(zi, mean=sqrt(x$n.I[i])*theta) * wgts
+ pp <- cp$upper$prob %*% gsDen / sum(gsDen)
if (total) return(sum(pp))
else return(pp)
}
+gsPI<-function(x, i=1, zi=0, j=2, level=.95, theta=c(0,3), wgts=c(.5,.5)){
+ if (!(is(x, "gsProbability") || is(x, "gsDesign")))
+ { stop("gsPI: class(x) must be gsProbability or gsDesign")
+ }
+ checkScalar(i, "integer", c(1, x$k-1))
+ checkScalar(j, "integer", c(i+1, x$k))
+ checkScalar(zi, "numeric", c(-Inf,Inf), c(FALSE,FALSE))
+ checkVector(wgts, "numeric", c(0, Inf), c(TRUE, FALSE))
+ checkVector(theta, "numeric", c(-Inf,Inf), c(FALSE, FALSE))
+ checkLengths(theta, wgts)
+ post <- dnorm(zi,mean=sqrt(x$n.I[i])*theta) * wgts
+ post <- post/sum(post)
+ lower <- uniroot(f=postfn, interval=c(-20,20), PP=1-(1-level)/2,
+ d=x, i=i, zi=zi, j=j, theta=theta, wgts=post)$root
+ if (level==0) return(lower)
+ upper <- uniroot(f=postfn, interval=c(-20,20), PP=(1-level)/2,
+ d=x, i=i, zi=zi, j=j, theta=theta, wgts=post)$root
+ c(lower,upper)
+}
+
"gsBoundCP" <- function(x, theta="thetahat", r=18)
-{
+{ if (!(is(x, "gsProbability") || is(x, "gsDesign")))
+ { stop("gsPI: class(x) must be gsProbability or gsDesign")
+ }
+ checkScalar(r, "integer", c(1, 70))
+ if (!is.character(theta))
+ checkVector(theta, "numeric", c(-Inf,Inf), c(FALSE, FALSE))
+
len <- x$k-1
test.type <- ifelse(is(x, "gsProbability"), 3, x$test.type)
@@ -122,7 +149,58 @@
if (test.type > 1) cbind(CPlo, CPhi) else CPhi
}
+gsPosterior <- function(x=gsDesign(), i=1, zi=NULL, prior=normalGrid(),
+ r=18)
+{ if (is.null(prior$gridwgts)) prior$gridwgts <- array(1,length(prior$z))
+ checkLengths(prior$z, prior$density, prior$gridwgts)
+ checkVector(prior$gridwgts, "numeric", c(0, Inf), c(TRUE, FALSE))
+ checkVector(prior$density, "numeric", c(0, Inf), c(TRUE, FALSE))
+ checkVector(prior$z, "numeric", c(-Inf,Inf), c(FALSE, FALSE))
+ cl <- class(x)
+ if (cl != "gsDesign" && cl != "gsProbability")
+ stop("gsPosterior: x must have class gsDesign or gsProbability")
+ test.type <- ifelse(is(x, "gsProbability"), 3, x$test.type)
+ checkScalar(i, "integer", c(1, x$k-1))
+ if (is.null(zi)) zi <- c(x$lower$bound[i],x$upper$bound[i])
+ else checkVector(zi, "numeric", c(-Inf,Inf), c(FALSE,FALSE))
+ if (length(zi) > 2) stop("gsPosterior: length of zi must be 1 or 2")
+ if (length(zi) > 1)
+ { if (zi[2] <= zi[1])
+ stop("gsPosterior: when length of zi is 2, must have zi[2] > zi[1]")
+ xa <- x
+ if (zi[1] != x$lower$bound[i] || zi[2] != x$upper$bound[i])
+ { xa$lower$bound[i] <- zi[1]
+ xa$upper$bound[i] <- zi[2]
+ }
+ xa <- gsProbability(d=xa, theta=prior$z, r=r)
+ prob <- xa$lower$prob + xa$upper$prob
+ for (j in 1:ncol(prob)) prob[,j] <- 1 - cumsum(prob[,j])
+ marg <- sum(prob[i,] * prior$gridwgts * prior$density)
+ posterior <- prob[i,] * prior$density
+ }
+ else
+ { y <- gsZ(x, theta=prior$z, i=i, zi=zi)
+ marg <- sum(as.vector(y$density) * prior$gridwgts * prior$density)
+ posterior <- as.vector(y$density) * prior$density
+ }
+ posterior <- posterior / marg
+ return(list(z=prior$z, density=posterior,
+ gridwgts=prior$gridwgts, wgts=prior$gridwgts*posterior))
+}
###
# Hidden Functions
###
+gsZ <- function(x, theta, i, zi){
+ mu <- sqrt(x$n.I[i]) * theta
+ xx <- matrix(0,nrow=length(zi),ncol=length(theta))
+ for (j in 1:length(theta)) xx[,j] <- dnorm(zi - mu[j])
+ list(zi=zi, theta=theta, density=xx)
+}
+postfn <- function(x, PP, d, i, zi, j, theta, wgts)
+{ newmean <- (d$timing[j]-d$timing[i]) * theta * sqrt(d$n.I[d$k])
+ newsd <- sqrt(d$timing[j]-d$timing[i])
+ pprob <- pnorm(x*sqrt(d$timing[j])-zi*sqrt(d$timing[i]), mean=newmean,
+ sd=newsd, lower.tail=FALSE)
+ sum(pprob * wgts) - PP
+}
Modified: pkg/gsDesign/R/gsDesign.R
===================================================================
--- pkg/gsDesign/R/gsDesign.R 2011-07-19 12:59:35 UTC (rev 278)
+++ pkg/gsDesign/R/gsDesign.R 2011-07-19 13:06:45 UTC (rev 279)
@@ -297,20 +297,7 @@
list(zi=zi, theta=theta, density=matrix(xx[[1]], nrow=length(zi), ncol=length(theta)))
}
-#"gsPosterior" <- function(x, theta=NULL, wgts=NULL, i=1, zi=0, r=18)
-#{ if (class(x) != "gsDesign" && class(x) != "gsProbability")
-# stop("x must have class gsDesign or gsProbability.")
-# checkVector(theta, "numeric")
-# checkVector(wgts, "numeric")
-# checkLengths(
-# checkScalar(i, "integer", c(0,x$k), c(FALSE, TRUE))
-# checkVector(zi, "numeric")
-# checkScalar(r, "integer", c(1, 80))
-
-#}
-
-
###
# Hidden Functions
###
Modified: pkg/gsDesign/R/gsNormalGrid.R
===================================================================
--- pkg/gsDesign/R/gsNormalGrid.R 2011-07-19 12:59:35 UTC (rev 278)
+++ pkg/gsDesign/R/gsNormalGrid.R 2011-07-19 13:06:45 UTC (rev 279)
@@ -57,3 +57,35 @@
d <- dnorm(z, mean=mu, sd=sigma)
list(z=z, density=d, gridwgts=w, wgts=d*w)
}
+
+invCDF <- function(q, x, discrete=FALSE, upper=FALSE)
+{ checkLengths(x$z, x$density, x$gridwgts, x$wgts)
+ len <- length(x$z)
+ checkVector(x$z[2:len]-x$z[1:(len-1)],"numeric",c(0,Inf), c(TRUE, FALSE))
+ checkVector(x$density,"numeric",c(0,Inf),c(FALSE,FALSE))
+ checkVector(x$gridwgts,"numeric",c(0,Inf),c(FALSE,FALSE))
+ checkVector(x$wgts, "numeric", c(0,1), c(FALSE, TRUE))
+ if (!upper) CDF <- cumsum(x$wgts)
+ else CDF <- cumsum(x$wgts[len:1])
+ if (CDF[len] > 1.0000001 || CDF[len]<.9999999)
+ stop("Input distribution did not integrate to 1")
+ if (q <= 0 || q > 1) stop("q outside of range (0,1]")
+ CDFq <- CDF[CDF <= q]
+ i <- length(CDFq)
+ if (i==0)
+ { if (!upper) return(x$z[1])
+ return(x$z[len])
+ }
+ if (discrete && !upper) return(x$z[i])
+ if (discrete) return(x$z[len-i])
+ if (abs(q - CDF[i])<tol)
+ { if (!upper) return(x$z[i])
+ return(x$z[len-i])
+ }
+ # if not discrete and inverse is between grid points in x$z,
+ # use trapezoidal rule to approximate inverse
+ F1 <- CDF[i]; F2 <- CDF[i+1]
+ if (!upper){ z1 <- x$z[i]; z2 <- x$z[i+1]}
+ else { z1 <- x$z[len-i]; z2 <- x$z[len+1-i]}
+ return((q-F1)/(F2-F1)*(z2-z1)+z1)
+}
Modified: pkg/gsDesign/man/gsCP.Rd
===================================================================
--- pkg/gsDesign/man/gsCP.Rd 2011-07-19 12:59:35 UTC (rev 278)
+++ pkg/gsDesign/man/gsCP.Rd 2011-07-19 13:06:45 UTC (rev 279)
@@ -1,12 +1,16 @@
\name{gsCP}
\alias{gsCP}
\alias{gsPP}
+\alias{gsPI}
\alias{gsPOS}
\alias{gsCPOS}
+\alias{gsPosterior}
\title{2.4: Conditional and Predictive Power, Overall and Conditional Probability of Success}
\description{
\code{gsCP()} computes conditional boundary crossing probabilities at future planned analyses for a given group sequential design assuming an interim z-statistic at a specified interim analysis.
\code{gsPP()} averages conditional power across a posterior distribution to compute predictive power.
+\code{gsPI()} computes Bayesian prediction intervals for future analyses corresponding to results produced by \code{gsPP()}.
+\code{gsPosterior()} computes the posterior density for the group sequential design parameter of interest given a prior density and an interim outcome that is exact or in an interval.
\code{gsPOS()} computes the probability of success for a trial using a prior distribution to average power over a set of \code{theta} values of interest.
\code{gsCPOS()} assumes no boundary has been crossed before and including an interim analysis of interest, and computes the probability of success based on this event.
Note that \code{gsCP()} and \code{gsPP()} take only the interim test statistic into account in computing conditional probabilities, while \code{gsCPOS()} conditions on not crossing any bound through a specified interim analysis.
@@ -15,21 +19,27 @@
\usage{
gsCP(x, theta=NULL, i=1, zi=0, r=18)
gsPP(x, i=1, zi=0, theta=c(0,3), wgts=c(.5,.5), r=18, total=TRUE)
+gsPI(x, i=1, zi=0, j=2, level=.95, theta=c(0,3), wgts=c(.5,.5))
+gsPosterior(x=gsDesign(), i=1, zi=NULL, prior=normalGrid(), r=18)
gsPOS(x, theta, wgts)
gsCPOS(i, x, theta, wgts)
}
\arguments{
\item{x}{An object of type \code{gsDesign} or \code{gsProbability}}
- \item{theta}{a vector with \eqn{\theta}{theta} value(s) at which conditional power is to be computed; for \code{gsCP()} if \code{NULL}, an estimated value of \eqn{\theta}{theta} based on the interim test statistic (\code{zi/sqrt(x$n.I[i])}) as well as at \code{x$theta} is computed.}
+ \item{theta}{a vector with \eqn{\theta}{theta} value(s) at which conditional power is to be computed; for \code{gsCP()} if \code{NULL}, an estimated value of \eqn{\theta}{theta} based on the interim test statistic (\code{zi/sqrt(x$n.I[i])}) as well as at \code{x$theta} is computed.
+For \code{gsPosterior}, this may be a scalar or an interval; for \code{gsPP} and \code{gsCP}, this must be a scalar.}
\item{wgts}{Weights to be used with grid points in \code{theta}. Length can be one if weights are equal, otherwise should be the same length as \code{theta}. Values should be positive, but do not need to sum to 1.}
\item{i}{analysis at which interim z-value is given; must be from 1 to \code{x$k-1}}
+ \item{prior}{provides a prior distribution in the form produced by \code{\link{normalGrid}}}
\item{zi}{interim z-value at analysis i (scalar)}
+ \item{j}{specific analysis for which prediction is being made; must be \code{>i} and no more than \code{x$k}}
\item{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.}
- \item{total}{Needs documentation.}
-}
+ \item{total}{The default of \code{total=TRUE} produces the combined probability for all planned analyses after the interim analysis specified in \code{i}. Otherwise, information on each analysis is provided separately.}
+ \item{level}{The level to be used for Bayes credible intervals (which approach confidence intervals for vague priors). The default \code{level=.95} corresponds to a 95\% credible interval. \code{level=0} provides a point estimate rather than an interval.
+}}
\value{
\code{gsCP()} returns an object of the class \code{gsProbability}.
Based on the input design and the interim test statistic, the output gsDesign object has bounds for test statistics computed based on solely on observations after interim \code{i}.
@@ -38,17 +48,33 @@
\code{gsPP()} if total==TRUE, returns a real value indicating the predictive power of the trial conditional on the interim test statistic \code{zi} at analysis \code{i}; otherwise returns vector with predictive power for each future planned analysis.
+\code{gsPI()} returns an interval (or point estimate if \code{level=0}) indicating 100\code{level}\% credible interval for the z-statistic at analysis \code{j} conditional on the z-statistic at analysis \code{i<j}.
+The interval does not consider intervending interim analyses.
+The probability estimate is based on the predictive distribution used for \code{gsPP()} and requires a prior distribution for the group sequential parameter \code{theta} specified in \code{theta} and \code{wgts}.
+
+\code{gsPosterior()} returns a posterior distribution containing the the vector \code{z} input in \code{prior$z}, the posterior density in \code{density}, grid weights for integrating the posterior density as input in \code{prior$gridwgts} or defaulted to a vector of ones, and the product of the output values in \code{density} and \code{gridwgts} in \code{wgts}.
+
\code{gsPOS()} returns a real value indicating the probability of a positive study weighted by the prior distribution input for \code{theta}.
-\code{gsCPOS()} returns a real value indicating the probability of a positive study weighted by the posterior distribution derived from the interim test statistic and the prior distribution input for \code{theta} conditional on an interim test statistic .
+\code{gsCPOS()} returns a real value indicating the probability of a positive study weighted by the posterior distribution derived from the interim test statistic and the prior distribution input for \code{theta} conditional on an interim test statistic.
}
\details{
See Conditional power section of manual for further clarification. See also Muller and Schaffer (2001) for background theory.
+
+For \code{gsPP()}, \code{gsPI()}, \code{gsPOS()} and \code{gsCPOS()}, the prior distribution for the standardized parameter \code{theta} () for a group sequential design specified through a gsDesign object is specified through the arguments \code{theta} and \code{wgts}. This can be a discrete or a continuous probability density function. For a discrete function, generally all weights would be 1. For a continuous density, the \code{wgts} would contain integration grid weights, such as those provided by \link{normalGrid}.
+
+For \code{gsPosterior}, a prior distribution in \code{prior} must be composed of the vectors \code{z} \code{density}.
+The vector \code{z} contains points where the prior is evaluated and \code{density} the corresponding density or, for a discrete distribution, the probabilities of each point in \code{z}.
+Densities may be supplied as from \code{normalGrid()} where grid weights for numerical integration are supplied in \code{gridwgts}.
+If \code{gridwgts} are not supplied, they are defaulted to 1 (equal weighting).
+To ensure a proper prior distribution, you must have \code{sum(gridwgts * density)} equal to 1; this is NOT checked, however.
}
\note{The manual is not linked to this help file, but is available in library/gsdesign/doc/gsDesignManual.pdf in the directory where R is installed.}
+\seealso{\code{\link{normalGrid}}, \code{\link{gsDesign}}, \code{\link{gsProbability}}, \code{\link{gsBoundCP}}}
+
\author{Keaven Anderson \email{keaven\_anderson at merck.}}
\references{
Jennison C and Turnbull BW (2000), \emph{Group Sequential Methods with Applications to Clinical Trials}.
@@ -123,7 +149,20 @@
pnorm(((b - x$upper$bound[2]) * (1 + t * sigma2) +
(1 - t) * (mu0 + b * sigma2)) /
sqrt((1 - t) * (1 + sigma2) * (1 + t * sigma2)))
+
+# plot prior then posterior distribution for unblinded analysis with i=1, zi=1
+xp <- gsPosterior(x=x,i=1,zi=1,prior=prior)
+plot(x=xp$z, y=xp$density, type="l", col=2, xlab=expression(theta), ylab="Density")
+points(x=x$z, y=x$density, col=1)
+
+# add posterior plot assuming only knowlede that interim bound has
+# not been crossed at interim 1
+xpb <- gsPosterior(x=x,i=1,zi=1,prior=prior)
+lines(x=xpb$z,y=xpb$density,col=4)
+
+# prediction interval based in interim 1 results
+# start with point estimate, followed by 90% prediction interval
+gsPI(x=x, i=1, zi=z1, j=2, theta=prior$z, wgts=prior$wgts, level=0)
+gsPI(x=x, i=1, zi=z1, j=2, theta=prior$z, wgts=prior$wgts, level=.9)
}
-
-\seealso{\code{\link{gsDesign}}, \code{\link{gsProbability}}, \code{\link{gsBoundCP}}}
\keyword{design}
Modified: pkg/gsDesign/tex/Sections/DefaultDesign.tex
===================================================================
--- pkg/gsDesign/tex/Sections/DefaultDesign.tex 2011-07-19 12:59:35 UTC (rev 278)
+++ pkg/gsDesign/tex/Sections/DefaultDesign.tex 2011-07-19 13:06:45 UTC (rev 279)
@@ -1,51 +1,62 @@
\section{Applying the default group sequential design\label{sec:default}}
\subsection{Default parameters}
-We are now prepared to demonstrate derivation of group sequential designs using default parameters with the \code{gsDesign()} function.
+We are now prepared to demonstrate derivation of group sequential designs using default parameters with the \texttt{gsDesign()} function.
Along with this, we discuss the \texttt{gsDesign} class returned by \texttt{gsDesign()} and its associated standard print and plot functions.
We then apply this default group sequential design to each of our motivational examples.
-The main parameters in \code{gsDesign()} will be explained in more detail in sections \ref{sec:gsDesign} through \ref{sec:spendfn}.
+The main parameters in \texttt{gsDesign()} will be explained in more detail in sections \ref{sec:gsDesign} through \ref{sec:spendfn}.
The main parameter defaults that you need to know about are as follows:
\begin{enumerate}
-\item Overall Type I error $\alpha = 0.025$ (one-sided)
+\item Overall Type I error ($\alpha$, one-sided): \texttt{alpha = 0.025}
-\item Overall Type II error $\beta = 0.1$ (Power = $90\%$)
+\item Overall Type II error ($\beta=1-\hbox{power}$): \texttt{beta = 0.1}
-\item Two interim analyses equally spaced at 1/3 and 2/3 of the way through the trial plus the final analysis (\texttt{k=3})
+\item Two interim analyses equally spaced at 1/3 and 2/3 of the way through the trial plus the final analysis: \texttt{k=3}
+\item {test.type=4}, which specifies all of the following:
+\begin{itemize}
\item Asymmetric boundaries, which means we may stop the trial for futility or
-superiority at an interim analysis.
-
+superiority at an interim analysis
\item $\beta$-spending is used to set the lower stopping
boundary. This means that the spending function controls the incremental
amount of Type II error at each analysis, $\beta_i(\delta)$, $i=1,2,\ldots,K$.
-
\item Non-binding lower bound. Lower bounds are sometimes considered as
guidelines, which may be ignored during the course of the trial.
Since Type I error is inflated if this is the case, regulators often demand that the lower bounds be ignored when computing Type I error.
That is, Type I error is computed using $\alpha^+(\theta)$ from (\ref{alphai+(theta)}) and (\ref{alpha+(theta)}) rather than $\alpha(\theta)$ from (\ref{alphai(theta)}) and (\ref{alpha(theta)}).
+\end{itemize}
-\item A Hwang-Shih-DeCani spending functions with $\gamma = -4$ for the upper
-bound and $\gamma = -2$ for the lower bound. This provides a conservative,
-O'Brien-Fleming-like superiority bound and a less conservative lower bound.
-Spending functions will be discussed in detail in \ref{sec:spendfn}.
+\item Hwang-Shih-DeCani spending functions for the upper bound (\texttt{sfu=sfHSD}) with $\gamma$-paramater \texttt{sfupar = -4} and lower bound (\texttt{sfl=sfHSD}) with $\gamma$-parameter \texttt{sflpar=-2}.
+This provides a conservative, O'Brien-Fleming-like superiority bound and a less conservative lower bound.
+Spending functions will be discussed in detail in Section \ref{sec:spendfn}.
+\item The following parameters are related to numerical accuracy and will not be discussed further here as they generally would not be changed by the user: \texttt{tol=0.000001}, \texttt{r=18}. Further information is in the help file.
+\item The input variable \texttt{endpoint} (default is NULL) at present impacts default options for plots approximating the treatment effect at a boundary. If \texttt{endpoint="binomial"} then the y-axis will change to a default label $\hat{p}_C-\hat{p}_E$; see also the \texttt{delta0} and \texttt{delta1} arguments below.
+Another option is to set \texttt{endpoint="survival"} which will cause the treatment effect plot to be on a hazard ratio scale.
+\item \texttt{delta1} (default 1) indicates the alternative hypothesis value on a scale of interest to you that is a linear transformation of the scale used for \texttt{theta}. This is used to scale the treatment effect plot.
+\item \texttt{delta0} is also a value on a linearly transformed scale from \texttt{theta} used to scale a plot of treatment effect. Generally, this will be 0, but may be changed if you are testing for noninferiority.
+\item \texttt{nFixSurv} (defaul of 0) is used to indicate the sample size for a fixed design for a survival trial. In this case \texttt{n.fix} would indicate the number of endpoints for this trial to be powered as specified. By providing \texttt{nFixSurv}, printed output from a \texttt{gsDesign} object will include the total sample size as well as the number of events at interim and final analysis.
+\item The following parameters are used to reset bounds when timing of analyses are changed from the original design and will be discussed in \ref{sec:reset}:
+\begin{itemize}
+\item \texttt{maxn.IPlan = 0}, if resetting timing of analyses, this contains the statistical information/sample size/number of events at the originally planned final analysis.
+\item \texttt{n.I = 0}, if \texttt{maxn.IPlan > 0} this is a vector of length \texttt{k} containing actual statistical information/sample size/number of events at each analysis.
+\end{itemize}
\end{enumerate}
\subsection{Sample size ratio for a group sequential design compared to a fixed
design.\label{sec:ssratio}}
-In section \ref{sec:testing} and its subsections we gave distributional assumptions, defined testing procedures and denoted probabilities for boundary crossing.
-Consider a trial with a fixed design (no interim analyses) with power 100(1--$\beta$) and level $\alpha$ (1-sided). Denote the sample size as $N_{fix}$ and statistical information for this design as $I_{fix}$.
+In Section \ref{sec:testing} and its subsections we gave distributional assumptions, defined testing procedures and denoted probabilities for boundary crossing.
+Consider a trial with a fixed design (no interim analyses) with power 100(1--$\beta$) and level $\alpha$ (1-sided). Denote the sample size as $N_{fix}$ and statistical information for this design as $\mathcal{I}_{fix}$.
For a group sequential design as noted above, we denote the information ratio (inflation factor) comparing the information planned for the final analysis of a group sequential design compared to a fixed design as
\begin{equation}
-r=I_{k}/I_{fix}=n_{k}/N_{fix}.\label{ssratio}%
+r=\mathcal{I}_{k}/\mathcal{I}_{fix}=n_{k}/N_{fix}.\label{ssratio}%
\end{equation}
This ratio is independent of the $\theta$-value $\delta$ for which the trial
is powered as long as the information (sample size) available at each analysis
-increases proportionately with $I_{fix}$ and the boundaries for the group
+increases proportionately with $\mathcal{I}_{fix}$ and the boundaries for the group
sequential design remain unchanged; see, for example, Jennison and Turnbull \cite{JTBook}.
-Because of this, the default for \texttt{gsDesign()} is to print the sample size ratios $r_i=I_i/I_k$, $i=1,2,\ldots,k$ rather than an actual sample size at each interim analysis.
+Because of this, the default for \texttt{gsDesign()} is to print the sample size ratios $r_i=\mathcal{I}_i/\mathcal{I}_k$, $i=1,2,\ldots,k$ rather than an actual sample size at each interim analysis.
This is implemented through by the default value of 1 for the input parameter \texttt{n.fix}.
We demonstrate in the following subsections how to set \texttt{n.fix} to apply to our motivating examples.
@@ -63,15 +74,16 @@
been run, both of these numbers would assume the trial
stops if the lower bound stopped and thus would both be $0.025$.
-\bigskip
-
-\begin{verbatim}
+\begin{Schunk}
+\begin{Sinput}
> x <- gsDesign()
> x
-Asymmetric two-sided group sequential design with 90 % power and 2.5
-Type I Error.
-Upper bound spending computations assume trial continues if lower bound is
-crossed.
+\end{Sinput}
+\begin{Soutput}
+Asymmetric two-sided group sequential design with
+90 % power and 2.5 % Type I Error.
+Upper bound spending computations assume
+trial continues if lower bound is crossed.
Sample
Size ----Lower bounds---- ----Upper bounds-----
@@ -80,13 +92,14 @@
2 0.713 0.94 0.8267 0.0289 2.55 0.0054 0.0049
3 1.070 2.00 0.9772 0.0563 2.00 0.0228 0.0188
Total 0.1000 0.0250
-+ lower bound beta spending (under H1): Hwang-Shih-DeCani spending function
- with gamma = -2
-++ alpha spending: Hwang-Shih-DeCani spending function with gamma = -4
-* Sample size ratio compared to fixed non-group sequential design
++ lower bound beta spending (under H1):
+ Hwang-Shih-DeCani spending function with gamma = -2
+++ alpha spending:
+ Hwang-Shih-DeCani spending function with gamma = -4
+* Sample size ratio compared to fixed design with no interim
-Boundary crossing probabilities and expected sample size assuming any cross
-stops the trial
+Boundary crossing probabilities and expected sample size
+assume any cross stops the trial
Upper boundary (power or Type I Error)
Analysis
@@ -99,18 +112,13 @@
Theta 1 2 3 Total
0.0000 0.4057 0.4290 0.1420 0.9767
3.2415 0.0148 0.0289 0.0563 0.1000
-
+\end{Soutput}
+\begin{Sinput}
> plot(x)
-\end{verbatim}
-\begin{figure}
-\begin{center}
-\includegraphics[width=.6\textwidth]{figs/boundplot.pdf}
-\end{center}
-\caption{Default plot for gsDesign object}
-\end{figure}%
+\end{Sinput}
+\end{Schunk}
+\includegraphics{defaultdesign-pldef}
-\bigskip
-
Above we have seen standard output for \texttt{gsDesign()}.
To access individual items of information about what is returned from the above, use \texttt{summary(x)} to list the elements of \texttt{x}.
Type \texttt{help(gsDesign)} to get full documentation of the class \texttt{gsDesign} returned by the \texttt{gsDesign()} function.
@@ -127,42 +135,65 @@
\subsection{Applying the default design to the CAPTURE example}
The sample size ratios from (\ref{ssratio}) can be obtained as follows:
-\begin{verbatim}
+
+\begin{Schunk}
+\begin{Sinput}
> x <- gsDesign()
> x$n.I
-[1] 0.3566277 0.7132554 1.0698832
-\end{verbatim}
+\end{Sinput}
+\begin{Soutput}
+[1] 0.3566277 0.7132555 1.0698832
+\end{Soutput}
+\end{Schunk}
+
These will be applied to each of our examples.
Recall from the CAPTURE trial that we had a binomial outcome and wished to detect a reduction in the primary endpoint from a 15\% event rate in the control group to a 10\% rate in the experimental group.
While we consider 80\% power elsewhere, we stick with the default of 90\% here.
A group sequential design with 90\% power and 2.5\% Type I error has the same bounds as shown previously. The sample size at each analysis is obtained as follows (continuing the code just above):
-\begin{verbatim}
-> n.I <- nBinomial(p1 = .15, p2 = .1)
+
+\begin{Schunk}
+\begin{Sinput}
+> n.I <- nBinomial(p1 = 0.15, p2 = 0.1)
> n.I
-1834.641
+\end{Sinput}
+\begin{Soutput}
+[1] 1834.641
+\end{Soutput}
+\begin{Sinput}
> n.I * x$n.I
-[1] 654.2839 1308.5679 1962.8518
-\end{verbatim}
+\end{Sinput}
+\begin{Soutput}
+[1] 654.284 1308.568 1962.852
+\end{Soutput}
+\end{Schunk}
+
Rounding up to an even number in each case, we see from the above that a while a fixed design requires 1836 patients, employing the default group sequential design inflates the sample size requirement to 1964.
Interim analyses would be peformed after approximately 654 and 1308 patients.
The group sequential design can be derived directly by replacing the input parameter \texttt{n.fix} with the sample size from a fixed design trial as follows:
-\begin{verbatim}
-> n.I <- nBinomial(p1 = .15, p2 = .1)
+\begin{Schunk}
+\begin{Sinput}
+> n.I <- nBinomial(p1 = 0.15, p2 = 0.1)
> x <- gsDesign(n.fix = n.I)
> x$n.I
+\end{Sinput}
+\begin{Soutput}
[1] 654.2839 1308.5678 1962.8518
-\end{verbatim}
+\end{Soutput}
+\end{Schunk}
Printing this design now replaces the sample size ratio with the actual sample sizes at each analysis. The only other difference from the design above in Section \ref{sec:default} is the second value of \texttt{theta} below.
-\begin{verbatim}
+\begin{Schunk}
+\begin{Sinput}
> x
-Asymmetric two-sided group sequential design with 90 % power and
-2.5 % Type I Error.
-Upper bound spending computations assume trial continues if lower
-bound is crossed.
+\end{Sinput}
+\begin{Soutput}
+Asymmetric two-sided group sequential design with
+90 % power and 2.5 % Type I Error.
+Upper bound spending computations assume
+trial continues if lower bound is crossed.
----Lower bounds---- ----Upper bounds-----
Analysis N Z Nominal p Spend+ Z Nominal p Spend++
@@ -170,12 +201,13 @@
2 1309 0.94 0.8267 0.0289 2.55 0.0054 0.0049
3 1963 2.00 0.9772 0.0563 2.00 0.0228 0.0188
Total 0.1000 0.0250
-+ lower bound beta spending (under H1): Hwang-Shih-DeCani spending
-function with gamma = -2
-++ alpha spending: Hwang-Shih-DeCani spending function with gamma = -4
++ lower bound beta spending (under H1):
+ Hwang-Shih-DeCani spending function with gamma = -2
+++ alpha spending:
+ Hwang-Shih-DeCani spending function with gamma = -4
-Boundary crossing probabilities and expected sample size assuming
-any cross stops the trial
+Boundary crossing probabilities and expected sample size
+assume any cross stops the trial
Upper boundary (power or Type I Error)
Analysis
@@ -188,47 +220,108 @@
Theta 1 2 3 Total
0.0000 0.4057 0.4290 0.1420 0.9767
0.0757 0.0148 0.0289 0.0563 0.1000
-\end{verbatim}
+\end{Soutput}
+\end{Schunk}
-\bigskip
-
\subsection{Applying the default design to the noninferiority example}
The fixed noninferiority design for a binomial comparison is the same as above, only changing the \texttt{nBinomial()} call to
-\bigskip
-\begin{verbatim}
-> n.fix <- nBinomial(p1=.677, p2=.677, delta0=.07)
+
+\begin{Schunk}
+\begin{Sinput}
+> n.fix <- nBinomial(p1 = 0.677, p2 = 0.677, delta0 = 0.07)
> ceiling(gsDesign(n.fix = n.fix)$n.I)
+\end{Sinput}
+\begin{Soutput}
[1] 668 1336 2004
->\end{verbatim}
-\bigskip
+\end{Soutput}
+\end{Schunk}
+
Testing at each analysis can be peformed using the Miettinen and Nurminen \cite{MandN} method.
-Simulation to verify the normal approximation is adequate for comparing binomial event rates can be performed using the functions \code{simBinomial} and \code{testBinomial}.
[TRUNCATED]
To get the complete diff run:
svnlook diff /svnroot/gsdesign -r 279
More information about the Gsdesign-commits
mailing list