timeline: A color-coded treatment time-line, with overlaid events

In VizOR: Graphical Visualization Tools for Complex Observational Data with Focus on Health Sciences

Description

This individual-level graphic depicts horizontal time intervals of an ongoing treatment course, color-coded by, e.g., agent. Categorical events which may occur during treatment, such as assessments of response, are annotatated with color-coded arrows.

Usage

timeline(figlabel, txs, resp, bsl, ptid = "patnum", condition = TRUE,
  formula = trt + resp ~ time | patnum, followed = list(from =
  as.difftime(0, units = "days"), to = as.difftime(Inf, units = "days")),
  tx.start = "start", tx.end = "end",
  treatment = as.character(formula[[2]][[2]]),
  response = as.character(formula[[2]][[3]]),
  time = as.character(formula[[3]][[2]]), timeunit = units(resp[[time]]),
  caption = NULL, tx.key = key(txs[[treatment]]),
  resp.key = key(resp[[response]]), cols.rows = c(2, 5),
  prefix.string = "splot", xlim = c(0, as.double(min(followed$to,
  max(resp[[time]])), units = timeunit)), xlab = paste("Time (", timeunit,
  ")", sep = ""), ylab = "", filename = paste(figlabel, "followed",
  sub("[.]", "_", followed$from), "-", sub("[.]", "_", followed$to), "y", sep =
  ""))

Arguments

figlabel	A string to be used as a LaTeX figure label
txs	A data frame describing intervals of treatment
resp	A data frame describing treatment response assessments
bsl	A data frame of subject baseline characteristics
ptid	The name of the unique patient identifier (default is "patnum")
condition	An R expression giving a logical condition (a predicate on subject baseline characteristics) used for selecting the subjects to be plotted
formula	A formula of the form trt+resp~time|patnum, interpreted as "plot treatment and response vs time, by patnum"
followed	A list with difftime components from and to, giving the minimum and maximum durations of follow-up for patients to be plotted. This is necessary to prevent the dwarfing of treatment courses for patients with short follow-up when plotted alongside those of patients with extended follow-up
tx.start	name of treatment start date column of txs
tx.end	name of treatment end date column of txs
treatment	name of treatment column of txs
response	name of response column of resp
time	name of time column of resp
timeunit	The time unit desired for the horizontal axis
caption	The figure caption may be provided explicitly or (if NULL) constructed automatically
tx.key	The plot legend for treatments
resp.key	The plot legend for responses
cols.rows	Trellis layout as c(ncols, nrows)
prefix.string	Prefix string (including possibly a directory) for cached plot output
xlim	x-axis limits
xlab	x-axis label
ylab	y-axis label
filename	Filename pattern for cached plot output

Note

TODO: further notes

Author(s)

David C. Norris

References

TODO: Reference our white paper or pending publication

See Also

TODO: List objects to See Also as help

Examples

## TODO: Provide an example
## TODO: Document usage. If necessary, include sample data sets in package:VizOR.

VizOR documentation built on May 30, 2017, 5:29 a.m.