udplot: Visualizing the time series of an up-and-down experiment

Description

Plotting function for the "trace" (time series) of an up-and-down experiment, showing the observation order on the x-axis, and the dose (treatment, stimulus, etc.) strength on the y-axis. Uses utilities from the cir package.

Usage

udplot(
  x,
  y,
  cohort = NULL,
  shape = "circle",
  connect = TRUE,
  symbcol = 1,
  doselabels = NULL,
  allow1extra = FALSE,
  xtitle = "Observation Order",
  ytitle = "Dose / Stimulus",
  ...
)

Value

Returns invisibly after plotting. If you would like to save the plot to a file, embed the plotting code in a standard R graphics export code sequence, (e.g., pdf(...) before the plotting function, and dev.off() after it).

Arguments

x: numeric vector: sequence of administered doses, treatments, stimuli, etc.
y: numeric vector: sequence of observed responses. Must be same length as x, and must be coded TRUE/FALSE or 0/1.
cohort: for a group/cohort UD design, the cohort/group size (a single number). In case of variable cohort size, this can be a vector the same length as x, y, with each observation's cohort assignment.
shape: the plotting shape (DRtrace only): 'circle' (default), 'square', or 'triangle'.
connect: logical: whether to connect the symbols (generic plotting type 'b'). Default TRUE for udplot() and FALSE for drplot().
symbcol: The color of the main plotting symbols and connecting lines. Default 1 (the current palette's first color). Note: if you change the color and inadvertently use col instead, there might be an error message.
doselabels: (DRtrace only) Dose values to be plotted along the y-axis. If NULL (default), those will be the doses in the dataset (i.e., sort(unique(x))).
allow1extra: logical: allow length(x) to be either equal or 1 greater than length(y)? (default FALSE) The "n+1" dose-allocation, determined from the last allocations and responses, might be tagged onto x. If this point is provided and allow1extra=TRUE, udplot() will show it as a grey diamond; the other functions will ignore it.
xtitle, ytitle: x-axis and y-axis titles. Some reasonable defaults are provided, to avoid an annoying error message.
...: Other arguments passed on to plot (e.g., main for the main title).

Author

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

Details

This simple and handy visualization approach was presented already by Dixon and Mood (1948).

It conveys directly the meaning of "up-and-down", because the administered dose/stimulus strength is on the y-axis, whereas observation order is on the x-axis.
Filled symbols stand for positive responses and open symbols for negative.
The design's transition rules can be usually inferred directly from the plot.

udplot() is a convenience wrapper to cir::plot.DRtrace. This is a base-R plot, so you can use additional options, including preceding the plot command with par statements, or following up with legend. When wishing to save to a file, I recommend utilities such as png() or pdf().

References

Dixon WJ, Mood AM. A method for obtaining and analyzing sensitivity data. J Am Stat Assoc. 1948;43:109-126.
Oron AP, Souter MJ, Flournoy N. Understanding Research Methods: Up-and-down Designs for Dose-finding. Anesthesiology 2022; 137:137–50.

Examples

Run this code


#'  **An up-and-down experiment that has generated some controversy**
#'  
#' Van Elstraete, AC et al. The Median Effective Dose of Preemptive Gabapentin 
#'      on Postoperative Morphine Consumption After Posterior Lumbar Spinal Fusion. 
#'      *Anesthesia & Analgesia* 2008, 106: 305-308.

# It was a classical median-finding up-and-down study.

doses = c(4:7, 6:13, 12:19, 18:21, 20, 19:23, 22, 21:23, 22:19, 20:23, 
          22:24, 23, 22, 23, 22:25, 24:22, rep(23:24,2), 23, 22)
# With U&D, responses (except the last one) can be read off the doses:
responses = c( (1 - sign(diff(doses)))/2, 0 )


#' ### Plots plots plots!

# Saving current settings as now required by the CRAN powers-that-be :0
op <- par(no.readonly = TRUE)

layout(t(1:2), widths=3:2)
par(mar=c(4,4,4,1), mgp=c(2.5,0.8,0), cex.axis = 0.7, las = 1)

#' The experimental trajectory / time-series / "trace" (pick your favorite name!)
#' Note the changed argument names for x and y axis titles
udplot(doses, responses, main='', 
        xtitle = "Patient Number", ytitle = 'Gabapentin (mg/kg)') 
#' Compare with the article's Figure 1; the line below makes it look more similar
udplot(doses, responses, shape='square', connect=TRUE)

# The dose-response plot, rarely encountered in U&D articles. 
# We can also add the CIR estimate right there:
drplot(doses, responses, main=' Dose-Response', percents = TRUE,
       addest = TRUE, target = 0.5, addcurve = TRUE,
       xtitle = 'Gabapentin (mg/kg)', ytitle = "Percent Effective")

#' ### Estimates

#' Let us actually see the numbers of those Centered-Isotonic-Regression (CIR) estimates!
#' Note that our default confidence-interval is 90%. Change it via the 'conf' argument.

udest(doses, responses, target = 0.5)
#' Compare with the article: 21.7 mg/kg (95% CI 19.9–23.5). 
#' They cite a little-known 1991 article by Dixon as the method source.
#' However, in their author rejoinder they claim to have used the Dixon-Mood estimate.
#' 
#' ## Toy example of plotting a group UD dataset
#' 
#' Also showing off some udplot() options
#' 
#' Not an actual experiment (made-up data)
#' The design is purportedly GUD (3,0,1), targeting the 20th percentile
#' 

gsize = 3
x = rep(c(1:3, 2:4), each = gsize)
y = c(rep(0, 8), 1, rep(0,7), 1, 1)

udplot(x=x, y=y, cohort=gsize, connect=FALSE, shape='triangle')

par(op) # Back to business as usual ;)

Run the code above in your browser using DataLab