[Gsdesign-commits] r324 - in pkg/gsDesign: . R man
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Sun Dec 4 15:24:58 CET 2011
Author: keaven
Date: 2011-12-04 15:24:57 +0100 (Sun, 04 Dec 2011)
New Revision: 324
Modified:
pkg/gsDesign/DESCRIPTION
pkg/gsDesign/NAMESPACE
pkg/gsDesign/R/gsMethods.R
pkg/gsDesign/R/gsqplot.R
pkg/gsDesign/R/nEvents.R
pkg/gsDesign/man/gsBoundSummary.Rd
pkg/gsDesign/man/gsDesign.Rd
pkg/gsDesign/man/gsProbability.Rd
pkg/gsDesign/man/nSurvival.Rd
pkg/gsDesign/man/plot.gsDesign.Rd
Log:
Mainly updates for correct R 2.14 build
Modified: pkg/gsDesign/DESCRIPTION
===================================================================
--- pkg/gsDesign/DESCRIPTION 2011-09-22 17:47:22 UTC (rev 323)
+++ pkg/gsDesign/DESCRIPTION 2011-12-04 14:24:57 UTC (rev 324)
@@ -1,5 +1,5 @@
Package: gsDesign
-Version: 2.5-03
+Version: 2.6
Title: Group Sequential Design
Author: Keaven Anderson
Maintainer: Keaven Anderson <keaven_anderson at merck.com>
Modified: pkg/gsDesign/NAMESPACE
===================================================================
--- pkg/gsDesign/NAMESPACE 2011-09-22 17:47:22 UTC (rev 323)
+++ pkg/gsDesign/NAMESPACE 2011-12-04 14:24:57 UTC (rev 324)
@@ -1,6 +1,6 @@
useDynLib(gsDesign)
export(gsBoundCP, gsCP, gsPP, gsPI, gsPOS, gsCPOS, gsDensity, gsPosterior)
-export(gsCPz, gsHR, gsDelta, gsBValue, gsRR)
+export(gsCPz, gsHR, gsDelta, gsBValue, gsRR, hrn2z, hrz2n, zn2hr)
export(gsBound, gsBound1, gsDesign, gsProbability)
export(ciBinomial, nBinomial, simBinomial, testBinomial, gsBinomialExact)
export(nSurvival, nEvents)
Modified: pkg/gsDesign/R/gsMethods.R
===================================================================
--- pkg/gsDesign/R/gsMethods.R 2011-09-22 17:47:22 UTC (rev 323)
+++ pkg/gsDesign/R/gsMethods.R 2011-12-04 14:24:57 UTC (rev 324)
@@ -34,7 +34,7 @@
# Exported Functions
###
-"print.gsProbability" <- function(x, ...)
+"print.gsProbability" <- function(x,...)
{
ntxt <- "N "
nval <- ceiling(x$n.I)
@@ -90,6 +90,7 @@
cat("\nLower boundary (futility or Type II Error)\n")
cat(" Analysis\n")
print(y)
+ invisible(x)
}
"print.gsDesign" <- function(x, ...)
@@ -243,6 +244,7 @@
cat(" Analysis\n")
print(y)
}
+ invisible(x)
}
print.nSurvival <- function(x,...){
if (class(x) != "nSurvival") stop("print.nSurvival: primary argument must have class nSurvival")
Modified: pkg/gsDesign/R/gsqplot.R
===================================================================
--- pkg/gsDesign/R/gsqplot.R 2011-09-22 17:47:22 UTC (rev 323)
+++ pkg/gsDesign/R/gsqplot.R 2011-12-04 14:24:57 UTC (rev 324)
@@ -129,7 +129,7 @@
}
# qplots for z-values and transforms of z-values
"qplotit" <- function(x, xlim=NULL, ylim=NULL, main=NULL, geom=c("line", "text"),
- dgt=c(2.2), lty=c(2,1), col=c(1,1),
+ dgt=c(2,2), lty=c(2,1), col=c(1,1),
lwd=c(1,1), nlabel="TRUE", xlab=NULL, ylab=NULL, fn=function(z,i,x,...){z},
ratio=1, delta0=0, delta=1, cex=1, base=FALSE,...)
{ if (length(lty)==1) lty <- array(lty, 2)
@@ -167,7 +167,7 @@
}else{
z <- fn(z=x$upper$bound, i=1:x$k, x=x,
ratio=ratio, delta0=delta0, delta=delta)
- Ztxt <- as.character(round(z),dgt[1])
+ Ztxt <- as.character(round(z,dgt[1]))
y <- data.frame(
N=as.numeric(x$n.I),
Z=as.numeric(z),
Modified: pkg/gsDesign/R/nEvents.R
===================================================================
--- pkg/gsDesign/R/nEvents.R 2011-09-22 17:47:22 UTC (rev 323)
+++ pkg/gsDesign/R/nEvents.R 2011-12-04 14:24:57 UTC (rev 324)
@@ -16,3 +16,18 @@
return(pwr)
}
}
+"zn2hr" <- function (z, n , ratio = 1)
+{ c <- 1/(1 + ratio)
+ psi <- c * (1 - c)
+ exp(-z/sqrt(n * psi))
+}
+"hrn2z" <- function(hr, n, ratio=1)
+{ c <- 1/(1 + ratio)
+ psi <- c * (1 - c)
+ log(hr) * sqrt(n * psi)
+}
+"hrz2n" <- function(hr, z, ratio=1)
+{ c <- 1 / (1 + ratio)
+ psi <- c * (1 - c)
+ (z / log(hr))^2 / psi
+}
Modified: pkg/gsDesign/man/gsBoundSummary.Rd
===================================================================
--- pkg/gsDesign/man/gsBoundSummary.Rd 2011-09-22 17:47:22 UTC (rev 323)
+++ pkg/gsDesign/man/gsBoundSummary.Rd 2011-12-04 14:24:57 UTC (rev 324)
@@ -17,13 +17,13 @@
}
\usage{
- gsBValue <- function(z, i, x, ylab="B-value", ...)
+ gsBValue(z, i, x, ylab="B-value", ...)
gsDelta(z, i, x, ylab=NULL, ...)
gsHR(z, i, x, ratio=1, ylab="Estimated hazard ratio", ...)
gsRR(z, i, x, ratio=1, ylab="Estimated risk ratio",...)
gsCPz(z, i, x, theta=NULL, ylab=NULL, ...)
gsBoundSummary(x, upper=TRUE, ratio=1)
- xtable.gsDesign(x, caption=NULL, label=NULL, align=NULL, digits=c(0,0,3,4,4,4,3,3,3,3),
+ \method{xtable}{gsDesign}(x, caption=NULL, label=NULL, align=NULL, digits=c(0,0,3,4,4,4,3,3,3,3),
display=NULL, upper=TRUE, rnames=NULL, cnames=NULL, ratio=1,
sanitize.text.function=function(x){x},
sanitize.rownames.function=function(x){x},...)
Modified: pkg/gsDesign/man/gsDesign.Rd
===================================================================
--- pkg/gsDesign/man/gsDesign.Rd 2011-09-22 17:47:22 UTC (rev 323)
+++ pkg/gsDesign/man/gsDesign.Rd 2011-12-04 14:24:57 UTC (rev 324)
@@ -9,7 +9,7 @@
sfl=sfHSD, sflpar=-2, tol=0.000001, r=18, n.I = 0,
maxn.IPlan = 0, nFixSurv=0, endpoint=NULL, delta1=1, delta0=0)
-print.gsDesign(x,...)}
+\method{print}{gsDesign}(x,...)}
\arguments{
\item{k}{Number of analyses planned, including interim and final.}
@@ -97,6 +97,7 @@
\item{endpoint}{As input.}
\item{delta1}{As input.}
\item{delta0}{As input.}
+Note: \code{print.gsProbability()} returns the input \code{x}.
}
\details{
Many parameters normally take on default values and thus do not require explicit specification.
Modified: pkg/gsDesign/man/gsProbability.Rd
===================================================================
--- pkg/gsDesign/man/gsProbability.Rd 2011-09-22 17:47:22 UTC (rev 323)
+++ pkg/gsDesign/man/gsProbability.Rd 2011-12-04 14:24:57 UTC (rev 324)
@@ -9,6 +9,7 @@
\usage{
gsProbability(k=0, theta, n.I, a, b, r=18, d=NULL)
+\method{print}{gsProbability}(x,\dots)
}
\details{Depending on the calling sequence, an object of class \code{gsProbability} or class \code{gsDesign} is returned.
If it is of class \code{gsDesign} then the members of the object will be the same as described in \code{\link{gsDesign}}.
@@ -32,6 +33,8 @@
\item{d}{If not \code{NULL}, this should be an object of type \code{gsDesign} returned by a call to \code{gsDesign()}.
When this is specified, the values of \code{k}, \code{n.I}, \code{a}, \code{b}, and \code{r} will be obtained from \code{d} and
only \code{theta} needs to be specified by the user.}
+ \item{x}{An item of class \code{gsProbability}.}
+ \item{\dots}{Not implemented (here for compatibility with generic print input).}
}
\value{
\item{k}{As input.}
@@ -45,6 +48,7 @@
\item{en}{A vector of the same length as \code{theta} containing expected sample sizes for the trial design
corresponding to each value in the vector \code{theta}.}
\item{r}{As input.}
+Note: \code{print.gsProbability()} returns the input \code{x}.
}
\seealso{\link{Plots for group sequential designs}, \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
Modified: pkg/gsDesign/man/nSurvival.Rd
===================================================================
--- pkg/gsDesign/man/nSurvival.Rd 2011-09-22 17:47:22 UTC (rev 323)
+++ pkg/gsDesign/man/nSurvival.Rd 2011-12-04 14:24:57 UTC (rev 324)
@@ -1,18 +1,26 @@
\name{nSurvival}
\alias{nSurvival}
\alias{nEvents}
+\alias{zn2hr}
+\alias{hrn2z}
+\alias{hrz2n}
\alias{print.nSurvival}
\alias{Survival sample size}
\title{3.4: Time-to-event sample size calculation (Lachin-Foulkes)}
\description{\code{nSurvival()} is used to calculate the sample size for a clinical trial with a time-to-event endpoint. The Lachin and Foulkes (1986) method is used.
+\code{nEvents} uses the Schoenfeld (1981) approximation to provide sample size and power in terms of the underlying hazard ratio and the number of events observed in a survival analysis.
+The functions \code{hrz2n()}, \code{hrn2z()} and \code{zn2hr()} also use the Schoenfeld approximation to provide simple translations between hazard ratios, z-values and the number of events in an analysis; input variables can be given as vectors.
}
\usage{
nSurvival(lambda1=1/12, lambda2=1/24, Ts=24, Tr=12, eta = 0, ratio = 1,
alpha = 0.025, beta = 0.10, sided = 1, approx = FALSE,
type = c("rr", "rd"), entry = c("unif", "expo"), gamma = NA)
-print.nSurvival(x,...)
+\method{print}{nSurvival}(x,...)
nEvents(hr = .6, alpha = .025, beta = .1, ratio = 1, sided = 1, hr0 = 1, n = 0, tbl = FALSE)
+hrn2z(hr, n, ratio=1)
+hrz2n(hr, z, ratio=1)
+zn2hr(z, n, ratio=1)
}
\arguments{
\item{lambda1, lambda2}{event hazard rate for placebo and treatment
@@ -22,9 +30,9 @@
group. Default is balanced design, i.e., randomization ratio is 1.}
\item{Ts}{maximum study duration.}
\item{Tr}{accrual (recruitment) duration.}
- \item{alpha}{type I error rate. Default is 0.05 since 2-sided testing is default.}
+ \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 for \code{nEvents()} if n is provided.}
- \item{sided}{one or two-sided test? Default is two-sided test.}
+ \item{sided}{one or two-sided test? Default is one-sided test.}
\item{approx}{logical. If \code{TRUE}, the approximation sample size
formula for risk difference is used.}
\item{type}{type of sample size calculation: risk ratio (\dQuote{rr}) or risk
@@ -36,10 +44,11 @@
\code{"expo"} (exponential).}
\item{x}{An object of class "nSurvival" returned by \code{nSurvival()}
(optional: used for output; "months" or "years" would be the 'usual' choices).}
- \item{hr}{Hazard ratio under the alternative hypothesis (>0).}
+ \item{hr}{Hazard ratio. For \code{nEvents}, this is the hazard ratio under the alternative hypothesis (>0).}
\item{hr0}{Hazard ratio under the null hypothesis (>0, != \code{hr}).}
- \item{n}{Number of events may be input to compute power rather than sample size.}
+ \item{n}{Number of events. For \code{nEvents} may be input to compute power rather than sample size.}
\item{tbl}{Indicator of whether or not scalar (vector) or tabular output is desired for \code{nEvents()}.}
+ \item{z}{A z-statistic.}
\item{...}{Allows additional arguments for \code{print.nSurvival()}.}
}
@@ -51,13 +60,24 @@
be used for risk ratio or risk difference. The function also consider
non-uniform (exponential) entry as well as uniform entry.
- If the logical approx is \code{TRUE}, the variance under alternative
+ If the logical \code{approx} is \code{TRUE}, the variance under alternative
hypothesis is used to replace the variance under null hypothesis.
- For non-uniform entry, a non-zero value of gamma for exponential entry
- must be supplied. For positive gamma, the entry distribution is
- convex, whereas for negative gamma, the entry distribution is concave.
+ For non-uniform entry, a non-zero value of \code{gamma} for exponential entry
+ must be supplied. For positive \code{gamma}, the entry distribution is
+ convex, whereas for negative \code{gamma}, the entry distribution is concave.
- \code{nEvents()} uses the Schoenfeld (1981) method to approximate the number of events \code{n} (given \code{beta}) or the power (given \code{n}). Arguments may be vectors or scalars, but any vectors must have the same length.
+\code{nEvents()} uses the Schoenfeld (1981) method to approximate the number of events \code{n} (given \code{beta}) or the power (given \code{n}). Arguments may be vectors or scalars, but any vectors must have the same length.
+
+The functions \code{hrz2n}, \code{hrn2z} and \code{zn2hr} also all apply the Schoenfeld approximation for proportional hazards modelling.
+This approximation is based on the asymptotic normal distribtuion of the logrank statistic as well as related statistics are asymptotically normal.
+Let \eqn{\lambda} denote the underlying hazard ratio (\code{lambda1/lambda2} in terms of the arguments to \code{nSurvival}). Further, let \eqn{n} denote the number of events observed when computing the statistic of interest and \eqn{r} the ratio of the sample size in an experimental group relative to a control. The estimated natural logarithm of the hazard ratio from a proportional hazards ratio is approximately normal with a mean of \eqn{log{\lambda}} and variance \eqn{(1+r)^2/nr}.
+Let \eqn{z} denote a logrank statistic (or a Wald statistic or score statistic from a proportional hazards regression model).
+The same asymptotic theory implies \eqn{z} is asymptotically equivalent to a normalized estimate of the hazard ratio \eqn{\lambda} and thus \eqn{z} is asymptotically normal with variance 1 and mean \deqn{\frac{log{\lambda}r}{(1+r)^2}.}
+Plugging the estimated hazard ratio into the above equation allows approximating any one of the following based on the other two: the estimate hazard ratio, the number of events and the z-statistic.
+That is,
+\deqn{\hat{\lambda}= \exp(z(1+r)/\sqrt{rn})}
+\deqn{z=log(\hat{\lambda})\sqrt{nr}/(1+r)}
+\deqn{n= (z(1+r)/log(\hat{\lambda}))^2/r.}
}
\value{
@@ -86,9 +106,14 @@
\item{delta}{Standardized effect size represented by input difference between null and alternative hypothesis hazard ratios.}
\item{ratio}{Ratio of experimental to control sample size where 'experimental' is the same as the group with hazard represented in the numerator of the hazard ratio.}
\item{se}{Estimated standard error for the observed log(hazard ratio) with the given sample size.}
+
+\code{hrz2n} outputs a number of events required to approximately have the input hazard ratio, z-statistic and sample size correspond.
+\code{hrn2z} outputs an approximate z-statistic corresponding to an input hazard ratio and number of events.
+\code{zn2hr} outputs an approximate hazard ratio corresponding to an input z-statistic and number of events.
+
}
-\seealso{\link{gsDesign package overview}, \link{Plots for group sequential designs}, \link{gsDesign}}
-\author{Shanhong Guan \email{shanhong\_guan at merck.com}}
+\seealso{\link{gsDesign package overview}, \link{Plots for group sequential designs}, \link{gsDesign}, \link{gsHR}}
+\author{Shanhong Guan \email{shanhong.guan at gmail.com}, Keaven Anderson \email{keaven_anderson at merck.com}}
\references{
Lachin JM and Foulkes MA (1986),
Evaluation of Sample Size and Power for Analyses of Survival
@@ -139,6 +164,19 @@
nEvents(hr=.6, n=c(50, 100), tbl=TRUE)
# vector output
nEvents(hr=.6, n=c(50, 100))
+
+# approximate hazard ratio corresponding to 100 events and z-statistic of 2
+zn2hr(n=100,z=2)
+
+# approximate number of events corresponding to z-statistic of 2 and
+# estimated hazard ratio of .5 (or 2)
+hrz2n(hr=.5,z=2)
+hrz2n(hr=2,z=2)
+
+# approximate z statistic corresponding to 75 events
+# and estimated hazard ratio of .6 (or 1/.6)
+# assuming 2-to-1 randomization of experimental to control
+hrn2z(hr=.6,n=75,ratio=2)
+hrn2z(hr=1/.6,n=75,ratio=2)
}
-
\keyword{design}
Modified: pkg/gsDesign/man/plot.gsDesign.Rd
===================================================================
--- pkg/gsDesign/man/plot.gsDesign.Rd 2011-09-22 17:47:22 UTC (rev 323)
+++ pkg/gsDesign/man/plot.gsDesign.Rd 2011-12-04 14:24:57 UTC (rev 324)
@@ -11,8 +11,8 @@
}
\usage{
-plot.gsProbability(x, plottype=2, base=FALSE, ...)
-plot.gsDesign(x, plottype=1, base=FALSE, ...)
+\method{plot}{gsProbability}(x, plottype=2, base=FALSE, ...)
+\method{plot}{gsDesign}(x, plottype=1, base=FALSE, ...)
}
\arguments{
More information about the Gsdesign-commits
mailing list