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), or exclude k-1 "phantom" states near the less-likely-to-be-visited boundary (FALSE, default)?

cohort

gudmat only: the cohort (group) size

lower, upper

(gudmat only) 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; see Note below for details on the latter.

Note

As Gezmu (1996) discovered and Oron and Hoff (2009) further extended, k-in-a-row UDDs with k>1 generate what can be described as a random walk **with ⁠k' internal states**. Their full TPM is therefore larger than \eqn{M\times M.} However, in terms of random-walk behavior, most salient properties are better represented via an \eqn{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. Another perspective on this intriguing design, viewing it as generaating a semi-Markov process, with equivalent results (Sada Allo et al., in review).

In kmatFull(), there are two matrix-size options. At one of the boundary dose-levels (upper boundary with lowTarget = TRUE, and vice versa), the k internal states are practically indistinguishable, so arguably only one of them exists. Hence, the most compact TPM representation, and the function default, is \left[(M-1)k + 1\right]\times \left[(M-1)k + 1\right]. Using fluffup = TRUE, users can choose a more aesthetically symmetric (but a bit misleading) full Mk\times Mk matrix.

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.3.0 Index]