doseToxicityGraph: Produce a Dose-Toxicity Curve

In PuzzledFace/crmReporter: Utility Functions for the Design and Reporting of CRM Trials

Description

Produce a dose-toxicity curve with posterior credible intervals for the probability of toxicity at each dose. Optionally, display the target toxicity rate (for CRM and oCRM studies) or the target toxicity band (for nCRM studies).

Usage

doseToxicityGraph(
  data,
  dose = Dose,
  lines = c("Mean", "Median"),
  ribbons = list(quantile = "Q\\d*"),
  quantiles = c(0.05, 0.1, 0.5, 0.9, 0.95),
  colours = c(mean = "black", median = "blue", quantile = "steelblue"),
  yLabel = "p(Toxicity)",
  xLabel = "Dose",
  labels = c(quantile = "Posterior CIs", lines = "Dose-tox curve", quantile1 =
    "10%-90%", quantile2 = "20%-80%"),
  targetTox = 0.33,
  alphaRange = c(0.2, 0.4),
  defaultLegends = TRUE,
  pivot = NA
)

Arguments

data	the input tibble, created by createDoseSummary
dose	the column in data that defines the dose
lines	a vector of Parameters in data whose Values are to be represented as lines in the graph. See Usage notes below.
ribbons	a list of sets of (pairs of) Parameters whose Values define low and high bounds of ribbons on the plot. Each list element defines a separate set of ribbons. Each entry (of two Parameter values) within each list element defines a seperate ribbon within a set. By default, Parameters that define quantiles undergo special processing. See Usage notes below.
quantiles	the numeric quantiles represented by the quantile Parameter values
colours	a named vector defining the colours to be used in the various plot elements. the names define the plot elemets, the values define the colour to be used in the corresponding element
yLabel	the text to be used to label the y axis
xLabel	the text to be used to label the x axis
labels	a named list of legend and category labels. The names define the legend titles and elements. The values define the text to label the corresponding element. See Usage notes below.
targetTox	a scalar or two element vector defining the target toxicity rate (if scalar) or band (if a vector).
alphaRange	a two element vector defining the upper and lower bounds for the alpha (1 minus the transparency) level used to paint all ribbons in the graph.
defaultLegends	if TRUE apply default legends to the various graph elements. If FALSE no legends are defined, the value of codelabels is ignored and the resulting plot will almost certainly need custom post-processing to be useful
pivot	Should data be normalised? If NA, the default, data is normalised if it does not contain only columns dose, Statistic and Value. A warning is printed if pivoting is required. If TRUE, data is pivoted only if necessary, but no warning is printed. If FALSE, data is never normalised and an error occurs if the required columns are not found.

Value

a ggplot object containing the requested plot

Usage notes

TODO: Fix the colour of legend entries for ribbons. Their transparency is correct. TODO: Allow custom colour for the target toxicity rate/band TODO: Allow wild card specification for all ribbon specifications.

The input tibble is spread so that Parameter values become column names for use in the plot.

The definition of ribbons is complex at first sight, but highly flexible. If ribbons=list("ribbonA"=list(c("Stat1", "Stat2"), c(("Stat3", "Stat4")))) then a single set of two ribbons will be produced. The first ribbon is runs from Values corresponding to Parameter == "Stat1" (the lower limit of the ribbon) to Values corresponding to Parameter == "Stat2" (the upper limit of the ribbon). The definition of the second ribbon is similar. The ribbons are drawn in the order they appear in the list and so there is an assumption that the ribbons get narrower as the length of the list increases. In other words, after the input tibble has been spread, that Stat1 < Stat2 < Stat3 < Stat4.

Continuing the example above, if labels=c("ribbonA"="My ribbon label", "ribbonA1"="First category", "ribbonA2"="Second label") then the corresponding legend has a title of "My ribbon label" and its two entries are labelled "First category" and "Second category".

Quantile ribbons undergo special pre-processing. By default, quantiles are flagged by Parameter values of the form "Q<x>", where <x> is a positive integer. First, if the quantiles list contains the value 0.5 in its ith element, then Parameter values of "Q<i>" are changed to "Median". Then the remaining "Q<x>" values are paired. If there are n remaining elements, the pairs are ("Q<1>", Q<n>"), ("Q<2>", Q<n-1>") and so on. These pairs are then processed as described above.

Examples

data(oCRMPosteriorShort)
x <- oCRMPosteriorShort %>%
       tidy() %>%
       augmentOCRMData() %>%
       dplyr::filter(Parameter == "Prob", Index == 2)
doseToxicityGraph(
  createDoseSummary(x) %>% dplyr::select(-N),
  targetTox=c(0.15, 0.30),
  pivot=TRUE)

PuzzledFace/crmReporter documentation built on June 21, 2020, 12:52 a.m.