upndown (version 0.2.0)

bcdmat: 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)

Value

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

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.

Author

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

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:

• The k-in-a-row or fixed staircase design common in sensory studies: kmatMarg(), kmatFull() (Gezmu, 1996; Oron and Hoff, 2009; see Note). Design parameters are k, a natural number, and whether k negative responses are required for dose transition, or k positive responses. The former is for targets below the median and vice versa.

• The Durham-Flournoy Biased Coin Design: bcdmat(). This design can target any percentile via the target argument (Durham and Flournoy, 1994).

• The original "classical" median-targeting UDD: classicmat() (Dixon and Mood, 1948). This is simply a wrapper for bcdmat() with target set to 0.5.

• Cohort or group UDD: gudmat(), with three design parameters for the group size and the up/down rule thresholds (Gezmu and Flournoy, 2006).

References

• Dixon WJ, Mood AM. A method for obtaining and analyzing sensitivity data. J Am Stat Assoc. 1948;43:109-126.

• Durham SD, Flournoy N. Random walks for quantile estimation. In: Statistical Decision Theory and Related Topics V (West Lafayette, IN, 1992). Springer; 1994:467-476.

• Gezmu M. The Geometric Up-and-Down Design for Allocating Dosage Levels. PhD Thesis. American University; 1996.

• Gezmu M, Flournoy N. Group up-and-down designs for dose-finding. J Stat Plan Inference. 2006;136(6):1749-1764.

• Oron AP, Hoff PD. The k-in-a-row up-and-down design, revisited. Stat Med. 2009;28:1805-1820.

• Oron AP, Souter MJ, Flournoy N. Understanding Research Methods: Up-and-down Designs for Dose-finding. Anesthesiology 2022; 137:137–50.

See Also

• k2targ, ktargOptions to find the k-in-a-row target-response rate for specific k and vice versa.

• g2targ, , gtargOptions likewise for group up-and-down.

• pivec, currentvec, cumulvec, which provide probability vectors of dose-allocation distributions using Up-and-Down TPMs.

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:


# \donttest{
  round(kmatFull(exampleF, k = 6, lowTarget = FALSE), 2)
# }