R: Boundary derivation - low level

gsBound {gsDesign} | R Documentation

## Boundary derivation - low level

### Description

`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 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(s)

Keaven Anderson keaven\_anderson@merck.

### References

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

### See Also

gsDesign package overview, `gsDesign`, `gsProbability`

### 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

    #  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

    # 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

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

[Package gsDesign version 3.2.0 Index]