glrSearch: This function searches through a space of design boundaries...

In sglr: Sequential Generalized Likelihood Ratio Decision Boundaries Proposed by Shih, Lai, Heyse and Chen (2010, <doi:10.1002/Sim.4036>)

This function searches through a space of design boundaries (scalar values a and b) to find values that achieve close to specified type I and type II errors for the sequential generalized likelihood ratio test of p0 versus p1 (specified respectively as vector of length 2) in pre-licensure vaccine trials

Description

The search through the space of b_1 (corresponds to b_1 in paper) and b_0 (corresponds to b_0 in paper) is greedy initially. Then refinements to the boundary are made by adjusting the boundaries by the step-size. It is entirely possible that the step-size is so small that a maximum number of iterations can be reached. Depending on how close p_0 and p_1 are the memory usage can grow significantly. The process is computationally intensive being dominated by a recursion deep in the search.

Usage

glrSearch(p, alpha, beta, stepSize = 0.5, tol = 1e-7,
          startB1 = log(1/beta), startB0 = log(1/alpha),
          maxIter = 25, gridIt = FALSE, nGrid = 5, verbose = FALSE)

Arguments

p	The vector of p_0 and p_1, with p_0 < p_1
alpha	A value for type I error α between 0 and 1 typically 0.05 which is the default value
beta	A value for type II error (β) between 0 and 1 typically below .2, default 0.10
stepSize	A value to use for moving the boundaries during the search, 0.5 default seems to work.
tol	A value that is used for deciding when to terminate the search. A euclidean metric is used. Default 1e-7.
startB1	A starting value for the futility boundary, default is log of reciprocal type I error
startB0	A starting value for the rejection boundary, default is log of reciprocal type II error
maxIter	A maximum number of iterations to be used for the search. This allows for a bailout if the step size is too small.
gridIt	A logical value indicating if a grid of values should be evaluated once the boundaries are bracketed in the search.
nGrid	The number of grid points to use, default 5
verbose	A logical flag indicating if you want verbose output during search. Useful for situations where the code gets confused.

Details

One should not use this code without a basic understanding of the Shih, Lai, Heyse and Chen paper cited below, particularly the section on the pre-licensure vaccine trials.

As the search can be computationally intensive, the program needs to use some variables internally by reference, particularly large tables that stay constant.

In our experiments, starting off with the default step size has usually worked, but in other cases the step size and the maximum number of iterations may need to be adjusted.

Value

b1	The explored values of the futility boundary b_1 (corresponds to the boundary b_1 in the appendix of reference)
b0	The explored values of the rejection boundary b_0 (corresponds to the boundary b_0 in the appendix of reference)
estimate	The estimated α and β values corresponding to the explored boundaries (a 2-column matrix); first column is α, second is β
glrTables	The constant values of the log likelihoods under p_0, p_1 and the estimate probability of terminating at that step. The first two, are, in turn, lists of length n where n is the maximum number of adverse events that might be needed for the test. The last element is a matrix of 2 columns, specifying the probability of terminating at each value of n
alphaTable	a matrix (nGrid x nGrid) of α values corresponding to the combinations of boundaries b and a (which are the row and column names of the matrix). This is computed only if gridIt=TRUE
betaTable	a matrix (nGrid x nGrid) of β values corresponding to the combinations of boundaries b and a (which are the row and column names of the matrix). This is computed only if gridIt=TRUE
b1Vals	the vector of b_1 (or equivalently b_1) values used in the grid, computed only if gridIt=TRUE
b0Vals	the vector of b_0 (or equivalently b_0) values used in the grid, computed only if gridIt=TRUE
iterations	The number of iterations actually used

Author(s)

Balasubramanian Narasimhan

References

“Sequential Generalized Likelihood Ratio Tests for Vaccine Safety Evaluation” doi: 10.1002/sim.4036.

Examples

library(sglr)
result <- glrSearch(p=c(.5, .75), alpha=0.05, beta=0.10)

result <- glrSearch(p=c(.5, .75), alpha=0.05, beta=0.10, verbose=TRUE)

result <- glrSearch(p=c(.5, .75), alpha=0.05, beta=0.10, gridIt=TRUE)
print(result$alphaTable)
print(result$betaTable)

## takes a while
result <- glrSearch(p=c(.5, 2/3), alpha=0.05, beta=0.10)
print(names(result))

##result <- glrSearch(p=c(.5, 2/3), alpha=0.05, beta=0.10, gridIt=TRUE)
##print(result$alphaTable)
##print(result$betaTable)

sglr documentation built on April 19, 2022, 5:06 p.m.