[Gsdesign-commits] r377 - in pkg/gsDesign: . R man
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Thu Jul 30 02:53:34 CEST 2015
Author: keaven
Date: 2015-07-30 02:53:33 +0200 (Thu, 30 Jul 2015)
New Revision: 377
Added:
pkg/gsDesign/NEWS
pkg/gsDesign/R/nBinomial1Sample.r
Modified:
pkg/gsDesign/DESCRIPTION
pkg/gsDesign/NAMESPACE
pkg/gsDesign/R/gsBinomialExact.R
pkg/gsDesign/man/gsBinomialExact.Rd
Log:
Added nBinomial1Sample for exact binomial 1-sample power and sample size.
Modified: pkg/gsDesign/DESCRIPTION
===================================================================
--- pkg/gsDesign/DESCRIPTION 2014-11-10 00:07:50 UTC (rev 376)
+++ pkg/gsDesign/DESCRIPTION 2015-07-30 00:53:33 UTC (rev 377)
@@ -1,12 +1,12 @@
Package: gsDesign
-Version: 2.9-3
+Version: 2.9-4
Title: Group Sequential Design
Author: Keaven Anderson
Maintainer: Keaven Anderson <keaven_anderson at merck.com>
Depends: R (>= 3.0.0), ggplot2, xtable, stringr, RUnit, plyr
-Suggests: knitr
+Suggests: knitr, scales
VignetteBuilder: knitr
-Description: gsDesign is a package that derives group sequential designs and describes their properties.
+Description: Derives group sequential designs and describes their properties
License: GPL (>= 2)
Copyright: Copyright 2010, Merck Research Laboratories
Packaged: 2011-12-30 13:26:23 UTC; Anderkea
Modified: pkg/gsDesign/NAMESPACE
===================================================================
--- pkg/gsDesign/NAMESPACE 2014-11-10 00:07:50 UTC (rev 376)
+++ pkg/gsDesign/NAMESPACE 2015-07-30 00:53:33 UTC (rev 377)
@@ -1,10 +1,11 @@
useDynLib(gsDesign)
-import(RUnit,ggplot2,plyr,stringr,xtable)
+import(RUnit,ggplot2,plyr,stringr,xtable )
export(gsBoundCP, gsCP, gsPP, gsPI, gsPOS, gsCPOS, gsDensity, gsPosterior)
export(gsCPz, gsHR, gsDelta, gsBValue, gsRR, hrn2z, hrz2n, zn2hr)
export(gsBound, gsBound1, gsDesign, gsProbability)
export(ciBinomial, nBinomial, simBinomial, testBinomial, gsBinomialExact, varBinomial)
-export(binomialSPRT, plot.binomialSPRT, plot.gsBinomialExact, nSurvival, nEvents, nNormal)
+export(binomialSPRT,nBinomial1Sample,plot.binomialSPRT, plot.gsBinomialExact)
+export(nSurvival, nEvents, nNormal)
export(normalGrid,ssrCP,condPower,Power.ssrCP,z2Z,z2Fisher,z2NC,plot.ssrCP)
export(plot.gsDesign, plot.gsProbability, print.gsProbability, print.gsDesign)
export(print.nSurvival, gsBoundSummary, xtable.gsSurv)
Added: pkg/gsDesign/NEWS
===================================================================
--- pkg/gsDesign/NEWS (rev 0)
+++ pkg/gsDesign/NEWS 2015-07-30 00:53:33 UTC (rev 377)
@@ -0,0 +1,12 @@
+2.9-4
+- Minor edit to package description to comply with R standards
+
+2.9-3, November, 2014
+- Added sfTrimmed as likely preferred spending function approach to skipping early or all interim efficacy analyses; this also can adjust bound when final analysis is performed with less than maximum planned information. Updated help(sfTrimmed) to demonstrate these capabilities.
+- Added sfGapped, which is primarily intended to eliminate futility analyses later in a study; see help(sfGapped) for an example
+- Added summary.spendfn to provide textual summary of spending functions; this simplified the print function for gsDesign objects
+- Added sfStep which can be used to set an interim spend when the exact amount of information is unknown; an example of how this can be misused is provided in the help file.
+- Fixed rounding so that gsBoundSummary, xtable.gsSurv and summary.gsDesign are consistent for gsSurv objects
+
+2.9-4, July, 2015
+- Added initial version of nBinomial1Sample to compute sample size and power for 1-sample binomial testing.
Modified: pkg/gsDesign/R/gsBinomialExact.R
===================================================================
--- pkg/gsDesign/R/gsBinomialExact.R 2014-11-10 00:07:50 UTC (rev 376)
+++ pkg/gsDesign/R/gsBinomialExact.R 2015-07-30 00:53:33 UTC (rev 377)
@@ -144,3 +144,37 @@
return(p)
}
+# predictive probability bound
+binomialPP <- function(a=.2, b=.8, theta=c(.2,.4), p1=.4, PP=c(.025,.95), nIA){
+ # initiate bounds outside of range of possibility
+ upper <- nIA + 1
+ lower <- array(-1,length(nIA))
+ j <- 1
+ # set bounds for each analysis sample size specified
+ for(i in nIA){
+ q <- 0:i
+ # compute posterior probability for value > p1
+ # for each possible outcome at analysis i
+ post <- pbeta(p1, a + q, b + i - q, lower.tail=F)
+ # set upper bound where posterior probability is > PP[2]
+ # that response rate is > p1
+ upper[j] <- sum(post < PP[2])
+ # set lower bound were posterior probability is <= PP[1]
+ # that response rate is < p1
+ lower[j] <- sum(post <= PP[1])
+ j <- j+1
+ }
+ # compute boundary crossing probabilities under
+ # response rates input in theta
+ y <- gsBinomialExact(k=length(nIA),n.I=nIA,
+ theta=theta,a=lower,b=upper)
+ # add beta prior parameters to return value
+ y$abeta <- a
+ y$bbeta <- b
+ # add input predictive probability bounds to return value
+ y$PP <- PP
+ # define class for output
+ class(y) <- c("binomialPP","gsBinomialExact","gsProbability")
+ return(y)
+}
+
Added: pkg/gsDesign/R/nBinomial1Sample.r
===================================================================
--- pkg/gsDesign/R/nBinomial1Sample.r (rev 0)
+++ pkg/gsDesign/R/nBinomial1Sample.r 2015-07-30 00:53:33 UTC (rev 377)
@@ -0,0 +1,35 @@
+# based on code from Marc Schwartz marc_schwartz at me.com
+# The possible sample size vector n needs to be selected in such a fashion
+# that it covers the possible range of values that include the true
+# minima. My example here does with a finite range and makes the
+# plot easier to visualize.
+# NOTE: this is more conservative than using a 2-sided exact test in binom.test
+nBinomial1Sample <- function(p0 = 0.90, p1=0.95,
+ alpha = 0.025, beta=NULL,
+ n = 200:250, outtype=1, conservative=FALSE){
+ Pow = 1-beta
+ # Required number of events, given a vector of sample sizes (n)
+ # to be considered at the null proportion, for the given alpha
+ CritVal <- qbinom(p = 1 - alpha, size = n, prob = p0) + 1
+ Alpha <- pbinom(q = CritVal - 1, size=n, prob=p0, lower.tail=FALSE)
+ # Get the Power for each n at the alternate hypothesis
+ # proportion
+ Power <- pbinom(CritVal - 1, n, p1, lower.tail=FALSE)
+ bta <- 1 - Power
+ if (outtype==3 || is.null(beta)) return(data.frame(p0=p0, p1=p1,
+ alpha=Alpha, beta=bta,
+ Power=Power, n=n, b=CritVal))
+ if (max(Power)<Pow) return(NULL)
+ # Find the smallest sample size yielding at least the required power
+ if (!conservative){SampSize <- min(which(Power >= Pow))
+ }else if (min(Power >= Pow)==1){SampSize=1
+ }else SampSize <- max(which(Power < Pow)) + 1
+
+ if (outtype==2) return(data.frame(p0=p0, p1=p1, alpha=Alpha[SampSize],beta=beta,
+ n=SampSize,b=CritVal[SampSize],
+ alphaR=Alpha[SampSize], Power=Power[SampSize]))
+ return(n[SampSize])
+}
+
+
+
Modified: pkg/gsDesign/man/gsBinomialExact.Rd
===================================================================
--- pkg/gsDesign/man/gsBinomialExact.Rd 2014-11-10 00:07:50 UTC (rev 376)
+++ pkg/gsDesign/man/gsBinomialExact.Rd 2015-07-30 00:53:33 UTC (rev 377)
@@ -4,7 +4,9 @@
\alias{plot.gsBinomialExact}
\alias{binomialSPRT}
\alias{plot.binomialSPRT}
-\title{3.4: One-Sample Exact Binomial Boundary Crossing Probabilities}
+%\alias{gsBinomialPP}
+\alias{nBinomial1Sample}
+\title{3.4: One-Sample Binomial Routines}
\description{
\code{gsBinomialExact} computes power/Type I error and expected sample size for a group sequential design
@@ -14,14 +16,20 @@
Similarly, a plot function has been extended using \code{plot.gsBinomialExact} to plot \code{gsBinomialExact} objects; see examples.
\code{binomialSPRT} computes a truncated binomial sequential probability ratio test (SPRT) which is a specific instance of an exact binomial group sequential design for a single arm trial with a binary outcome. See, for example, \url{http://theriac.org/DeskReference/viewDocument.php?id=65&SectionsList=3}.
+
+%\code{gsBinomialPP} computes a truncated binomial (group) sequential design based on predictive probability.
+
+\code{nBinomial1Sample} uses exact binomial calculations to compute power and sample size for single arm binomial experiments.
}
\usage{
gsBinomialExact(k=2, theta=c(.1, .2), n.I=c(50, 100), a=c(3, 7), b=c(20,30))
binomialSPRT(p0,p1,alpha,beta,minn,maxn)
+nBinomial1Sample(p0 = 0.90, p1=0.95,
+ alpha = 0.025, beta=NULL,
+ n = 200:250, outtype=1, conservative=FALSE)
\method{plot}{gsBinomialExact}(x,plottype=1,\dots)
\method{plot}{binomialSPRT}(x,plottype=1,\dots)
-
}
\arguments{
\item{k}{Number of analyses planned, including interim and final.}
@@ -32,12 +40,15 @@
\item{p0}{Lower of the two response (event) rates hypothesized.}
\item{p1}{Higher of the two response (event) rates hypothesized.}
\item{alpha}{Nominal probability of rejecting response (event) rate \code{p0} when it is true (Type I error rate).}
- \item{beta}{Nominal probability of rejecting response (event) rate \code{p1} when it is trun (Type II error rate).}
+ \item{beta}{Nominal probability of rejecting response (event) rate \code{p1} when it is true (Type II error rate).}
\item{minn}{Minimum sample size at which sequential testing begins.}
\item{maxn}{Maximum sample size.}
\item{x}{Item of class \code{gsBinomialExact} or \code{binomialSPRT} for \code{print.gsBinomialExact}. Item of class \code{gsBinomialExact} for \code{plot.gsBinomialExact}. Item of class \code{binomialSPRT} for item of class \code{binomialSPRT}.}
\item{plottype}{1 produces a plot with counts of response at bounds (for \code{binomialSPRT}, also produces linear SPRT bounds); 2 produces a plot with power to reject null and alternate response rates as well as the probability of not crossing a bound by the maximum sample size; 3 produces a plot with the response rate at the boundary as a function of sample size when the boundary is crossed; 6 produces a plot of the expected sample size by the underlying event rate (this assumes there is no enrollment beyond the sample size where the boundary is crossed).}
-\item{\dots}{arguments passed through to \code{ggplot}}
+\item{n}{sample sizes to be considered for \code{nBinomial1Sample}. These should be ordered from smallest to largest and be > 0.}
+\item{outtype}{Operative when \code{beta != NULL}. \code{1} means routine will return a single integer sample size while for \code{output=2} or \code{3} a data frame is returned (see Value).}
+\item{conservative}{operative when \code{outtype=1} or \code{2} and \code{beta != NULL}. Default \code{FALSE} selects minimum sample size for which power is at least \code{1-beta}. When \code{conservative=TRUE}, the minimum sample sample size for which power is at least \code{1-beta} and there is no larger sample size in the input \code{n} where power is less than \code{1-beta}.}
+\item{\dots}{arguments passed through to \code{ggplot}.}
}
\details{
\code{gsBinomialExact} is based on the book "Group Sequential Methods with Applications to Clinical Trials,"
@@ -55,6 +66,9 @@
While the linear SPRT bounds are continuous, actual bounds are the integer number of response at or beyond each linear bound for each sample size where testing is performed. Because of the truncation and discretization of the bounds, power and Type I error achieve will be lower than the nominal levels specified by \code{alpha} and \code{beta} which can be altered to produce desired values that are achieved by the planned sample size. See also example that shows computation of Type I error when futility bound is considered non-binding.
Plots produced include boundary plots, expected sample size, response rate at the boundary and power.
+
+\code{gsBinomial1Sample} uses exact binomial computations based on the base R functions \code{qbinom()} and \code{pbinom()}. The tabular output may be convenient for plotting. Note that input variables are largely not checked, so the user is largely responsible for results; it is a good idea to do a run with \code{outtype=3} to check that you have done things appropriately.
+If \code{n} is not ordered (a bad idea) or not sequential (maybe OK), be aware of possible consequences.
}
\value{
@@ -76,6 +90,18 @@
\item{beta}{As input. Note that this will exceed the actual Type II error achieved by the design returned.}
\item{p0}{As input.}
\item{p1}{As input.}
+
+\code{nBinomial1Sample} produces an integer if the input \code{outtype=1} and a data frame with the following values otherwise:
+\item{p0}{input null hypothesis event (or response) rate.}
+\item{p1}{input alternative hypothesis (or response) rate; must be \code{> p0}.}
+\item{alpha}{Type I error achieved for each output value of \code{n}; less than or equal to the input value \code{alpha}.}
+\item{beta}{Type II error achieved for each output value of \code{n}.}
+\item{Power}{\code{1} minus the output \code{beta} value.}
+\item{n}{sample size.}
+\item{b}{cutoff given \code{n} to control Type I error; value is \code{NULL} if no such value exists.}
+
+Note that when the input \code{1 > beta > alpha > 0} from the input \code{n} for which the power is at least \code{1-beta} or \code{NULL} if no input sample size satisfies the desired.
+
}
\seealso{\code{\link{gsProbability}}}
\note{The manual is not linked to this help file, but is available in library/gsdesign/doc/gsDesignManual.pdf
@@ -84,6 +110,8 @@
\references{
Jennison C and Turnbull BW (2000), \emph{Group Sequential Methods with Applications to Clinical Trials}.
Boca Raton: Chapman and Hall.
+
+Code for nBinomial1Sample was based on code developed by marc_schwartz at me.com.
}
\examples{
@@ -111,5 +139,28 @@
plot(x,plottype=3)
# Expect sample size at boundary crossing or end of trial
plot(x,plottype=6)
+
+# sample size for single arm exact binomial
+
+# plot of table of power by sample size
+nb1 <- nBinomial1Sample(p0 = 0.05, p1=0.2,alpha = 0.025, beta=.2, n = 25:40, outtype=3)
+nb1
+library(scales)
+ggplot(nb1,aes(x=n,y=Power))+geom_line()+geom_point()+scale_y_continuous(labels=percent)
+
+# simple call with same parameters to get minimum sample size yielding desired power
+nBinomial1Sample(p0 = 0.05, p1=0.2,alpha = 0.025, beta=.2, n = 25:40)
+
+# change to 'conservative' if you want all larger sample
+# sizes to also provide adequate power
+nBinomial1Sample(p0 = 0.05, p1=0.2,alpha = 0.025, beta=.2, n = 25:40, conservative=TRUE)
+
+# print out more information for the selected derived sample size
+nBinomial1Sample(p0 = 0.05, p1=0.2,alpha = 0.025, beta=.2, n = 25:40, conservative=TRUE,outtype=2)
+
+# what happens if input sample sizes not sufficient?
+nBinomial1Sample(p0 = 0.05, p1=0.2,alpha = 0.025, beta=.2, n = 25:30)
+
+
}
\keyword{design}
More information about the Gsdesign-commits
mailing list