Boundary derivation - low level — gsBound • gsDesign

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).

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

Usage

gsBound(I, trueneg, falsepos, tol = 1e-06, r = 18, printerr = 0)

gsBound1(theta, I, a, probhi, tol = 1e-06, r = 18, printerr = 0)

Arguments

I: Vector containing statistical information planned at each analysis.
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.
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.
theta: Scalar containing mean (drift) per unit of statistical information.
a: Vector containing lower bound that is fixed for use in gsBound1.
probhi: Vector of desired probabilities for crossing upper bound assuming mean of theta.

Value

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.

Note

The gsDesign technical manual is available at https://keaven.github.io/gsd-tech-manual/.

References

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

Author

Keaven Anderson keaven_anderson@merck.com

Examples


# 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 = rep(.02, 3),
  falsepos = rep(.01, 3)
)
x
#> $k
#> [1] 3
#> 
#> $theta
#> [1] 0
#> 
#> $I
#> [1] 0.3333333 0.6666667 1.0000000
#> 
#> $a
#> [1] -2.053749 -1.914183 -1.789206
#> 
#> $b
#> [1] 2.326348 2.219299 2.120127
#> 
#> $rates
#> $rates$falsepos
#> [1] 0.01 0.01 0.01
#> 
#> $rates$trueneg
#> [1] 0.02 0.02 0.02
#> 
#> 
#> $tol
#> [1] 1e-06
#> 
#> $r
#> [1] 18
#> 
#> $error
#> [1] 0
#> 

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

# 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 = rep(.05, 3)
)
y$b
#> [1]  0.3746830 -0.3594403 -0.9470061

#  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)
#>                Lower bounds   Upper bounds
#>   Analysis N    Z   Nominal p  Z   Nominal p
#>          1  1 -0.37    0.3539 3.09    0.0010
#>          2  1  0.36    0.6404 2.34    0.0095
#>          3  1  0.95    0.8282 2.04    0.0207
#> 
#> Boundary crossing probabilities and expected sample size assume
#> any cross stops the trial
#> 
#> Upper boundary
#>           Analysis
#>   Theta      1      2      3  Total E{N}
#>     0.0 0.0010 0.0090 0.0146 0.0246  0.7
#>     2.2 0.0344 0.2601 0.2783 0.5728  0.8
#> 
#> Lower boundary
#>           Analysis
#>   Theta      1      2     3  Total
#>     0.0 0.3539 0.3153 0.184 0.8532
#>     2.2 0.0500 0.0500 0.050 0.1500

Boundary derivation - low level