pivec: Key Probability Vectors of Up-and-Down Designs
In upndown: Utilities and Design Aids for Up-and-Down Dose-Finding Studies

pivec

R Documentation

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, marginalize = TRUE, ...)

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

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 `...`. For the k-in-a-row design, use `kmatMarg` for `pivec()` and `kmatFull` otherwise.
`...`	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.
`marginalize`	logical (for `⁠currentvec, cumulvec⁠` when `matfun = kmatFull`) should the returned vector be marginalized over dose levels (`TRUE`, default), or should the full set with internal states be returned?
`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 if using pivec, and otherwise kmatFull.

At present, these functions are unable to incorporate in the calculations the impact of the recommended "fast start" stage for k-in-a-row and biased-coin designs. Such a stage begins with a classic UD run, until the first "minority" outcome is encountered (1 for below-median targets and vice versa). Generally such a fast start would make small-sample probability vectors approach the asymptotic distribution more quickly.

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.

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)

upndown documentation built on April 3, 2025, 10:57 p.m.