pivec {upndown}

Key Probability Vectors of Up-and-Down Designs

Description

Dose-allocation probability vectors that quantify the instantaneous, cumulative, and asymptotic behavior of Up-and-Down designs.

Usage

pivec(cdf, matfun, ...)

currentvec(cdf, matfun, n, startdose = NULL, ...)

cumulvec(
  cdf,
  matfun,
  n,
  startdose = NULL,
  proportions = TRUE,
  exclude = 0,
  ...
)

Arguments

cdf

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

matfun

The function to calculate the TPM. Depends on the specific design; see bcdmat. For all functions except classicmat, user must provide auxiliary parameters via ....

...

Arguments passed on to the design's matrix-calculating function.

n

For ⁠currentvec, cumulvec⁠, at what step (= after how many observations) in the experiment would you like the vector calculated?

startdose

For ⁠currentvec, cumulvec⁠, where does the experiment start? To be given as a dose-level index between 1 and M. If left as NULL (default), function will assume the equivalent of "fair die roll" among all doses. User can also specify your own M-length probability vector.

proportions

Logical (cumulvec only) Would you like the results returned as proportions (= a probability vector; TRUE, default), or as cumulative allocation counts?

exclude

Integer (cumulvec only) Should the cumulative distribution exclude a certain number of initial observations? Default 0.

Details

Up-and-Down designs (UDDs) generate random walk behavior, which concentrates doses around the target quantile. Asymptotically, dose allocations follow a stationary distribution \boldsymbol{\pi} which can be calculated given the number of doses M, and the value of the cdf F at each dose (i.e., the positive-response probabilities), and the specific UDD rules. No matter the starting dose, the allocation distribution converges to \boldsymbol{\pi} at a geometric rate (Diaconis and Stroock, 1991).

Three functions are offered:

• pivec() returns \boldsymbol{\pi}.

• currentvec() returns the current (instantaneous) allocation distribution at step n, using the formula from Diaconis and Stroock (1991).

• cumulvec() returns the cumulative allocations, i.e., the expected proportions (or counts) of allocations during the experiment after n observations. This function is perhaps of greatest practical use.

All functions first calculate the transition probability matrix (TPM), by calling one of the functions described under bcdmat. See that help page for more details.

Value

A vector of allocation frequencies/probabilities for the doses, summing up to 1. Exception: cumulvec(propotions = FALSE) returns a vector of expected allocation counts, summing up to n - exclude.

Note

When using the k-in-a-row design, set matfun = kmatMarg, not kmatFull.

Author(s)

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

References

• Diaconis P, Stroock D. Geometric Bounds for Eigenvalues of Markov Chains. Ann. Appl. Probab. 1991;1(1):36-61.

• Hughes BD. Random Walks and Random Environments, Vol. 1. Oxford University Press, 1995.

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

See Also

• bcdmat for the functions calculating transition probability matrices for various up-and-down designs.

• k2targ for target-finding design aids.

Examples

#----- Classical UD Example -----#

# An example used in Oron et al. 2022, Fig. 2.
# It is presented here via the original motivating story:
# "Ketofol"  is a commonly-used anesthesia-inducing mix known to combine its 2 components' 
# beneficial properties, while each component mitigates the other's harmful side-effects. 
# In particular:
#     Propofol reduces blood pressure while ketamine raises it.
# What is *not* known at present, is which mix proportions produce 
# 0 "delta-BP" on average among the population. 

# The classical UD design below administers the mix 0-100% ketamine in 10% increments.
#    The design will concentrate doses around the point where half the population 
#    experiences 0 "delta-BP". (the 'zeroPt' parameter in the code)

doses = seq(0, 100, 10)
m=length(doses) # 11 dose levels

zeroPt=63 # the zero-BP point, in units of percent ketamine

# We assume a Normal ("Probit") dose-response curve,
#   and calculate the value of F (i.e.,  prob (delta BP > 0) at the doses:
equivF = pnorm( (doses - zeroPt) / 20)
round(equivF, 3)

# The vector below represents the values feeding into the Fig. 2B barplot.
# "startdose = 6" means the experiment begins from the 6th out of 11 doses, i.e., a 50:50 mix.


  round(cumulvec(cdf = equivF, matfun = classicmat, startdose = 6, n = 30), 3)

# Compare with the *instantaneous* probability distribution to the 30th patient:

round(currentvec(cdf = equivF, matfun = classicmat, startdose = 6, n = 30), 3)
# Classic up-and-down has quasi-periodic behavior with a (quasi-)period of 2. 
# Compare the instantaneous vectors at n=30 and 29:
round(currentvec(cdf = equivF, matfun = classicmat, startdose = 6, n = 29), 3)
# Note the alternating near-zero values. Distributions at even/odd n "communicate"
#    with each other only via the dose boundaries.

# Lastly, the asymptotic/stationary distribution. Notice there is no 'n' argument.

round(pivec(cdf = equivF, matfun = classicmat), 3)

# The cumulative vector at n=30 is not very far from the asymptotic vector. 
# The main difference is that at n=30 there's still a bit more
#    probability weight at the starting dose.
# We can check how much of that extra weight is from the 1st patient, by excluding that data point:

round(cumulvec(cdf = equivF, matfun = classicmat, startdose = 6, n = 30, exclude = 1), 3)