bcdmat {upndown}R Documentation

Transition Probability Matrices for Up-and-Down Designs

Description

Transition Probability Matrices for Common Up-and-Down Designs

Usage

bcdmat(cdf, target)

classicmat(cdf)

kmatMarg(cdf, k, lowTarget)

kmatFull(cdf, k, lowTarget, fluffup = FALSE)

gudmat(cdf, cohort, lower, upper)

Arguments

cdf

monotone increasing vector with positive-response probabilities. The number of dose levels M is deduced from vector's length.

target

the design's target response rate (bcdmat() only).

k

the number of consecutive identical responses required for dose transitions (k-in-a-row functions only).

lowTarget

logical k-in-a-row functions only: is the design targeting below-median percentiles, with k repeated negative responses needed to level up and only one to level down - or vice versa? Default FALSE. See "Details" for more information.

fluffup

logical (kmatFull only): in the full k-in-a-row internal-state representation, should we "fluff" the matrix up so that it has Mk rows and columns (TRUE, default), or exclude k-1 "phantom" states near one of the boundaries?

cohort, lower, upper

gudmat only: the cohort (group) size, how many positive responses are allowed for a move upward, and how many are required for a move downward, respectively. For example ⁠cohort=3, lower=0, upper=2⁠ evaluates groups of 3 observations at a time, moves up if none are positive, down if >=2 are positive, and repeats the same dose with 1 positive.

Details

Up-and-Down designs (UDDs) generate random walk behavior, whose theoretical properties can be summarized via a transition probability matrix (TPM). Given the number of doses M, and the value of the cdf F at each dose (i.e., the positive-response probabilities), the specific UDD rules uniquely determine the TPM.

The utilities described here calculate the TPMs of the most common and simplest UDDs:

Value

An M\times M transition probability matrix, except for kmatFull() with k>1 which returns a larger square matrix.

Note

As Gezmu (1996) discovered and Oron and Hoff (2009) further extended, k-in-a-row UDDs with k>1 generate a random walk with internal states. Their full TPM is therefore larger than M\times M. However, in terms of random-walk behavior, most salient properties are better represented via an M\times M matrix analogous to those of the other designs, with transition probabilities marginalized over internal states using their asymptotic frequencies. This matrix is provided by kmatMarg(), while kmatFull() returns the full matrix including internal states.

Also, in kmatFull() there are two matrix-size options. Near one of the boundaries (upper boundary with lowTarget = TRUE, and vice versa), the most extreme k internal states are practically indistinguishable, so in some sense only one of them really exists. Using the fluffup argument, users can choose between having a more aesthetically symmetric (but a bit misleading) full Mk\times Mk matrix, or reducing it to its effectivelly true size by removing k-1 rows and columns.

Author(s)

Assaf P. Oron <assaf.oron.at.gmail.com>

References

See Also

Examples

#  Let's use an 8-dose design, and  a somewhat asymmetric CDF

exampleF = pweibull(1:8, shape = 2, scale = 4)
# You can plot if you want: plot(exampleF)

# Here's how the transition matrix looks for the median-finding classic up-and-down

round(classicmat(exampleF), 2)
# Note how the only nonzero diagonals are at the opposite corners. That's how 
#   odd-n and even-n distributions communicate (see examples for vector functions).
# Also note how "up" probabilities (the 1st upper off-diagnoal) are decreasing, 
#   while "down" probabilities (1st lower off-diagonal) are increasing, and 
#   start exceeding "up" moves at row 4.

# Now, let's use the same F to target the 90th percentile, which is often
#    the goal of anesthesiology dose-finding studies.
#    We use the biased-coin design (BCD) presented by Durham and Flournoy (1994):

round(bcdmat(exampleF, target = 0.9), 2)

# Note that now there's plenty of probability mass on the diagonal (i.e., repeating same dose).

# Another option, actually with somewhat better operational characteristics, 
#   is "k-in-a-row". Let's see what k to use:

ktargOptions(.9, tolerance = 0.05)

# Even though nominally k=7's target is closest to 0.9, it's generally preferable
#    to choose a somewhat smaller k. So let's go with k=6.
# We must also specify whether this is a low (<0.5) or high target.

round(kmatMarg(exampleF, k = 6, lowTarget = FALSE), 2)

# Compare and contrast with the BCD matrix above! At what dose do the "up" and "down"
#   probabilities flip? 

# Lastly, if you want to see a 43 x 43 matrix - the full state matrix for k-in-a-row, 
#      run the following line:



  round(kmatFull(exampleF, k = 6, lowTarget = FALSE), 2)





[Package upndown version 0.1.0 Index]