gsbound: 2.7: Boundary derivation - low level
In gsDesign: Group Sequential Design

Description Usage Arguments Details Value Note Author(s) References See Also Examples

gsBound() and gsBound1() are lower-level functions used to find boundaries for a group sequential design. They are not recommended (especially gsBound1()) for casual users. These functions do not adjust sample size as gsDesign() does to ensure appropriate power for a design.

gsBound() computes upper and lower bounds given boundary crossing probabilities assuming a mean of 0, the usual null hypothesis. gsBound1() computes the upper bound given a lower boundary, upper boundary crossing probabilities and an arbitrary mean (theta).

1 2	gsBound(I, trueneg, falsepos, tol=0.000001, r=18) gsBound1(theta, I, a, probhi, tol=0.000001, r=18, printerr=0)

Note that all vector arguments should have the same length which will be denoted here as k.

`theta`	Scalar containing mean (drift) per unit of statistical information.
`I`	Vector containing statistical information planned at each analysis.
`a`	Vector containing lower bound that is fixed for use in `gsBound1`.
`trueneg`	Vector of desired probabilities for crossing upper bound assuming mean of 0.
`falsepos`	Vector of desired probabilities for crossing lower bound assuming mean of 0.
`probhi`	Vector of desired probabilities for crossing upper bound assuming mean of theta.
`tol`	Tolerance for error (scalar; default is 0.000001). Normally this will not be changed by the user. This does not translate directly to number of digits of accuracy, so use extra decimal places.
`r`	Single 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 `r` will not be changed by the user.
`printerr`	If this scalar argument set to 1, this will print messages from underlying C program. Mainly intended to notify user when an output solution does not match input specifications. This is not intended to stop execution as this often occurs when deriving a design in `gsDesign` that uses beta-spending.

The function gsBound1() requires special attention to detail and knowledge of behavior when a design corresponding to the input parameters does not exist.

Both routines return a list. Common items returned by the two routines are:

`k`	The length of vectors input; a scalar.
`theta`	As input in `gsBound1()`; 0 for `gsBound()`.
`I`	As input.
`a`	For `gsbound1`, this is as input. For `gsbound` this is the derived lower boundary required to yield the input boundary crossing probabilities under the null hypothesis.
`b`	The derived upper boundary required to yield the input boundary crossing probabilities under the null hypothesis.
`tol`	As input.
`r`	As input.
`error`	Error code. 0 if no error; greater than 0 otherwise.

gsBound() also returns the following items:

`rates`	a list containing two items:
`falsepos`	vector of upper boundary crossing probabilities as input.
`trueneg`	vector of lower boundary crossing probabilities as input.

gsBound1() also returns the following items:

`problo`	vector of lower boundary crossing probabilities; computed using input lower bound and derived upper bound.
`probhi`	vector of upper boundary crossing probabilities as input.

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.

Keaven Anderson keaven\_anderson@merck.

Jennison C and Turnbull BW (2000), Group Sequential Methods with Applications to Clinical Trials. Boca Raton: Chapman and Hall.

gsDesign package overview, gsDesign, gsProbability

# set boundaries so that probability is .01 of first crossing
# each upper boundary and .02 of crossing each lower boundary
# under the null hypothesis
x <- gsBound(I=c(1, 2, 3)/3, trueneg=array(.02, 3),
             falsepos=array(.01, 3))
x

#  use gsBound1 to set up boundary for a 1-sided test
x <- gsBound1(theta= 0, I=c(1, 2, 3) / 3, a=array(-20, 3),
              probhi=c(.001, .009, .015))
x$b

# check boundary crossing probabilities with gsProbability 
y <- gsProbability(k=3, theta=0, n.I=x$I, a=x$a, b=x$b)$upper$prob

#  Note that gsBound1 only computes upper bound 
#  To get a lower bound under a parameter value theta:
#      use minus the upper bound as a lower bound
#      replace theta with -theta
#      set probhi as desired lower boundary crossing probabilities 
#  Here we let set lower boundary crossing at 0.05 at each analysis
#  assuming theta=2.2 
y <- gsBound1(theta=-2.2, I=c(1, 2, 3)/3, a= -x$b, 
              probhi=array(.05, 3))
y$b

#  Now use gsProbability to look at design
#  Note that lower boundary crossing probabilities are as
#  specified for theta=2.2, but for theta=0 the upper boundary
#  crossing probabilities are smaller than originally specified
#  above after first interim analysis
gsProbability(k=length(x$b), theta=c(0, 2.2), n.I=x$I, b=x$b, a= -y$b)