R: Visualizing the dose-response summary of an up-and-down...

drplot {upndown}

R Documentation

Visualizing the dose-response summary of an up-and-down experiment

Description

Dose-response plotting function for up-and-down data, with doses/stimuli on the x-axis, and the proportion of positive responses on the y-axis. Includes an option to plot the target-dose estimate. Uses utilities from the cir package.

Usage

drplot(
  x,
  y,
  shape = "X",
  connect = FALSE,
  symbcol = 1,
  percents = FALSE,
  addest = FALSE,
  addcurve = FALSE,
  target = NULL,
  balancePt = target,
  conf = 0.9,
  estcol = "purple",
  estsize = 2,
  estsymb = 19,
  esthick = 2,
  curvecol = "blue",
  ytitle = "Frequency of Positive Response",
  xtitle = "Dose / Stimulus",
  ...
)

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.
`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.
`percents`	logical, whether to represent the y-axis as percents rather than a fraction.
`addest`	logical: should we add the CIR target-dose estimate and its confidence interval? If `FALSE` (default), then arguments `⁠addcurve, target, balancePt, conf, estcol, estsize, estsymb, esthick, curvecol⁠` - are all ignored.
`addcurve`	logical: should we add the complete estimated CIR dose-response curve? Default `FALSE`, and only relevant when `addest = TRUE`.
`target`	The target response rate for which target dose estimate is requested. Must be a single number in `(0,1).`
`balancePt`	In case the design's inherent balance point differs somewhat from `target`, specify it here to improve estimation accuracy. See Details for further explanation. Otherwise, this argument defaults to be equal to `target`.
`conf`	The desired confidence level for the confidence interval. Default `90\%.` We do not recommend increasing to `95\%` unless you have `\sim 100` or more observations.
`estcol`, `estsize`, `estsymb`, `esthick`, `curvecol`	graphical parameters controlling the colors, symbol choice, size, thickness, of the target-dose and CIR-curve visuals.
`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).

Details

After an up-and-down experiment, it is highly recommended to plot not just the experiment's "trace" time-series (udplot), but also the dose-response summaries. This utility provides a convenient interface for doing that.

It summarizes the response rates at each participating dose, and plots them. At default, symbol area is proportional to the number of observations at each dose.
Optionally, the centered-isotonic-regression (CIR) target-dose estimate and its confidence interval are also calculated and plotted.
A further option allows for plotting the entire estimated CIR dose-response curve.

drplot() is a convenience wrapper to cir::plot.doseResponse, with the added option of plotting the estimate. Some specific options, such as disabling the proportional-area symbol plotting, are accessible only via plot.doseResponse arguments (specified in your drplot() call and passed through the ...).

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().

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).

Author(s)

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

References

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