[Gsdesign-commits] r326 - pkg/gsDesign/man

[noreply at r-forge.r-project.org]

Author: keaven
Date: 2011-12-23 00:16:12 +0100 (Fri, 23 Dec 2011)
New Revision: 326

Added:
   pkg/gsDesign/man/nNormal.Rd
   pkg/gsDesign/man/sfTruncated.Rd
Log:
Added documentation for nNormal, sfTruncated

Added: pkg/gsDesign/man/nNormal.Rd
===================================================================
--- pkg/gsDesign/man/nNormal.Rd	                        (rev 0)
+++ pkg/gsDesign/man/nNormal.Rd	2011-12-22 23:16:12 UTC (rev 326)
@@ -0,0 +1,50 @@
+\name{nNormal}
+\alias{nNormal}
+\title{Normal distribution sample size (2-sample)}
+\description{\code{nNormal()} computes a fixed design sample size for comparing 2 means where variance is known. T
+The function allows computation of sample size for a non-inferiority hypothesis.
+Note that you may wish to investigate other R packages such as the \code{pwr} package which uses the t-distr
+}
+\usage{
+nNormal(delta1=1,sigma=1.7,sigalt=NULL,alpha=.025,beta=.1,ratio=1, sided=1,
+n=NULL,delta0=0)
+}
+\arguments{
+\item{delta1}{difference between sample means under the alternate hypothesis.}
+\item{delta0}{difference between sample means under the null hypothesis; normally this will be left as the default of 0.}
+\item{ratio}{randomization ratio of experimental group compared to control.}
+\item{sided}{1 for 1-sided test (default), 2 for 2-sided test.}
+\item{sigma}{Standard deviation for the control arm.}
+\item{sigalt}{Standard deviation of experimental arm; this will be set to be the same as the control arm with the default of \code{NULL}.}
+\item{alpha}{type I error rate. Default is 0.025 since 1-sided testing is default.}
+\item{beta}{type II error rate. Default is 0.10 (90\% power). Not needed if \code{n} is provided.}
+\item{n}{Sample size; may be input to compute power rather than sample size. If \code{NULL} (default) then sample size is computed.}
+}
+\details{
+\code{nNormal()} computes sample size for comparing two normal means when the variance for observations in
+}
+\value{
+If \code{n} is \code{NULL} (default), total sample size (2 arms combined) is computed. Otherwise, power is c
+}
+\seealso{\link{gsDesign package overview}}
+\author{Keaven Anderson \email{keaven_anderson at merck.com}}
+\references{
+Lachin JM (1981),
+Introduction to sample size determination and power analysis for clinical trials. \emph{Controlled Clinical Trials} 2:93-113.
+
+Snedecor GW and Cochran WG (1989),
+Statistical Methods. 8th ed. Ames, IA:
+Iowa State University Press.
+}
+\examples{
+# EXAMPLES
+# equal variances
+nNormal(delta1=.5,sigma=1.1,alpha=.025,beta=.2)
+# unequal variances
+nNormal(delta1=.5,sigma=1.1,sigalt=2,alpha=.025,beta=.2)
+# unequal sample sizes
+nNormal(delta1=.5,sigma=1.1,alpha=.025,beta=.2, ratio=2)
+# non-inferiority assuming a better effect than null
+nNormal(delta1=.5,delta0=-.1,sigma=1.2)
+}
+\keyword{design}

Added: pkg/gsDesign/man/sfTruncated.Rd
===================================================================
--- pkg/gsDesign/man/sfTruncated.Rd	                        (rev 0)
+++ pkg/gsDesign/man/sfTruncated.Rd	2011-12-22 23:16:12 UTC (rev 326)
@@ -0,0 +1,76 @@
+\name{sfTruncated}
+\alias{sfTruncated}
+
+\title{4.7a: Truncated spending functions}
+\description{The function \code{sfTruncated()} applies any other spending function over a restricted range.
+This allows eliminating spending for early interim analyses when you desire not to stop for the bound being specified.
+The truncation can come late in the trial.
+if you desire to stop a trial any time after, say, 90 percent of information is available 
+and an analysis is performed.
+}
+
+\usage{
+sfTruncated(alpha, t, param)
+}
+\arguments{
+	\item{alpha}{Real value \eqn{> 0} and no more than 1. Normally, 
+\code{alpha=0.025} for one-sided Type I error specification
+	or \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 or information.}
+	\item{t}{A vector of points with increasing values from 0 to 1, inclusive. Values of the proportion of 
+	sample size or information for which the spending function will be computed.}
+	\item{param}{a list containing the elements sf (a spendfn object such as sfHSD), trange (the range over which the 
+        spending function increases from 0 to 1; 0 <= trange[1]<trange[2] <=1), 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).}
+}
+
+\value{An object of type \code{spendfn}. See \code{\link{Spending function overview}} for further details.}
+\details{
+\code{sfTruncated} compresses spending into a sub-range of [0,1].
+The parameter \code{param$trange} specifies the range over which spending is to occur.
+Within this range, spending is spent according to the spending function specified in
+\code{param$sf} along with the corresponding spending function parameter(s) in 
+\code{param$param}.
+See example using \code{sfLinear} that spends uniformly over specified range.
+}
+
+\seealso{\link{Spending function overview}, \code{\link{gsDesign}}, \link{gsDesign package overview}}
+\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.}
+
+\author{Keaven Anderson \email{keaven\_anderson at merck.}}
+\references{
+Jennison C and Turnbull BW (2000), \emph{Group Sequential Methods with Applications to Clinical Trials}.
+Boca Raton: Chapman and Hall.
+}
+
+\examples{
+
+# Eliminate spending forany interim at or before 20 percent of information.
+# Complete spending at first interim at or after 80 percent of information.
+s<-sfLinear(alpha=.05,t=(0:100)/100,param=c(.5,.5))
+plot((0:100)/100,s$spend,type="l",main="Accelerating spending with sfTruncated",
+xlab="Proportion of information",ylab="Spending")
+s<-sfTruncated(alpha=.05,t=(0:100)/100,param=list(sf=sfLinear,trange=c(.2,.8),param=c(.5,.5)))
+lines(col=2,(0:100)/100,s$spend)
+text("Accelerated (red) spending over interval (.2,.8)",x=.03,y=.045,pos=4)
+
+# now apply this in gsDesign
+# note how sfupar is set up to do as above
+
+# 1st version produces an error next to last interim must be before final spend
+# x<-gsDesign(k=5, sfu=sfTruncated, sfupar=list(sf=sfLinear, param=c(.5,.5), 
+# trange=c(.2,.8)))
+
+# now final spend occurs at > next to last interim
+x<-gsDesign(k=5, sfu=sfTruncated, sfupar=list(sf=sfLinear, param=c(.5,.5), trange=c(.2,.95)))
+x
+
+# The above means if final analysis is done a little early, all spending can occur
+# Suppose we skip 4th interim due to fast enrollment and set calendar date
+# based on estimated full information, but come up with only 97 pct of plan
+xA <- gsDesign(k=x$k-1,n.I=c(x$n.I[1:3],.97*x$n.I[5]),test.type=x$test.type, 
+               maxn.IPlan=x$n.I[x$k],sfu=sfTruncated,
+               sfupar=list(sf=sfLinear,  param=c(.5,.5), trange=c(.2,.95)))
+xA
+}
+\keyword{design}