R: Plot CMA0 objects.

plot.CMA0 {AdhereR}

R Documentation

Plot CMA0 objects.

Description

Plots the events (prescribing or dispensing) data encapsulated in a basic CMA0 object.

Usage

## S3 method for class 'CMA0'
plot(
  x,
  ...,
  patients.to.plot = NULL,
  duration = NA,
  align.all.patients = FALSE,
  align.first.event.at.zero = FALSE,
  show.period = c("dates", "days")[2],
  period.in.days = 90,
  show.legend = TRUE,
  legend.x = "right",
  legend.y = "bottom",
  legend.bkg.opacity = 0.5,
  legend.cex = 0.75,
  legend.cex.title = 1,
  cex = 1,
  cex.axis = 0.75,
  cex.lab = 1,
  xlab = c(dates = "Date", days = "Days"),
  ylab = c(withoutCMA = "patient", withCMA = "patient (& CMA)"),
  title = c(aligned = "Event patterns (all patients aligned)", notaligned =
    "Event patterns"),
  col.cats = rainbow,
  unspecified.category.label = "drug",
  medication.groups.to.plot = NULL,
  medication.groups.separator.show = TRUE,
  medication.groups.separator.lty = "solid",
  medication.groups.separator.lwd = 2,
  medication.groups.separator.color = "blue",
  medication.groups.allother.label = "*",
  lty.event = "solid",
  lwd.event = 2,
  pch.start.event = 15,
  pch.end.event = 16,
  plot.events.vertically.displaced = TRUE,
  print.dose = FALSE,
  cex.dose = 0.75,
  print.dose.outline.col = "white",
  print.dose.centered = FALSE,
  plot.dose = FALSE,
  lwd.event.max.dose = 8,
  plot.dose.lwd.across.medication.classes = FALSE,
  col.continuation = "black",
  lty.continuation = "dotted",
  lwd.continuation = 1,
  col.na = "lightgray",
  highlight.followup.window = TRUE,
  followup.window.col = "green",
  highlight.observation.window = TRUE,
  observation.window.col = "yellow",
  observation.window.density = 35,
  observation.window.angle = -30,
  observation.window.opacity = 0.3,
  alternating.bands.cols = c("white", "gray95"),
  rotate.text = -60,
  force.draw.text = FALSE,
  bw.plot = FALSE,
  min.plot.size.in.characters.horiz = 0,
  min.plot.size.in.characters.vert = 0,
  suppress.warnings = FALSE,
  max.patients.to.plot = 100,
  export.formats = NULL,
  export.formats.fileprefix = "AdhereR-plot",
  export.formats.height = NA,
  export.formats.width = NA,
  export.formats.save.svg.placeholder = TRUE,
  export.formats.svg.placeholder.type = c("jpg", "png", "webp")[2],
  export.formats.svg.placeholder.embed = FALSE,
  export.formats.html.template = NULL,
  export.formats.html.javascript = NULL,
  export.formats.html.css = NULL,
  export.formats.directory = NA,
  generate.R.plot = TRUE,
  do.not.draw.plot = FALSE
)

Arguments

`x`	A `CMA0` or derived object, representing the CMA to plot
`...`	other possible parameters
`patients.to.plot`	A vector of strings containing the list of patient IDs to plot (a subset of those in the `cma` object), or `NULL` for all
`duration`	A number, the total duration (in days) of the whole period to plot; in `NA` it is automatically determined from the event data such that the whole dataset fits.
`align.all.patients`	Logical, should all patients be aligned (i.e., the actual dates are discarded and all plots are relative to the earliest date)?
`align.first.event.at.zero`	Logical, should the first event be placed at the origin of the time axis (at 0)?
`show.period`	A string, if "dates" show the actual dates at the regular grid intervals, while for "days" (the default) shows the days since the beginning; if `align.all.patients == TRUE`, `show.period` is taken as "days".
`period.in.days`	The number of days at which the regular grid is drawn (or 0 for no grid).
`show.legend`	Logical, should the legend be drawn?
`legend.x`	The position of the legend on the x axis; can be "left", "right" (default), or a numeric value.
`legend.y`	The position of the legend on the y axis; can be "bottom" (default), "top", or a numeric value.
`legend.bkg.opacity`	A number between 0.0 and 1.0 specifying the opacity of the legend background.
`cex`, `cex.axis`, `cex.lab`, `legend.cex`, `legend.cex.title`	numeric values specifying the cex of the various types of text.
`xlab`	Named vector of x-axis labels to show for the two types of periods ("days" and "dates"), or a single value for both, or `NULL` for nothing.
`ylab`	Named vector of y-axis labels to show without and with CMA estimates, or a single value for both, or `NULL` for nonthing.
`title`	Named vector of titles to show for and without alignment, or a single value for both, or `NULL` for nonthing.
`col.cats`	A color or a function that specifies the single colour or the colour palette used to plot the different medication; by default `rainbow`, but we recommend, whenever possible, a colorblind-friendly palette such as `viridis` or `colorblind_pal`.
`unspecified.category.label`	A string giving the name of the unspecified (generic) medication category.
`medication.groups.to.plot`	the names of the medication groups to plot or `NULL` (the default) for all.
`medication.groups.separator.show`	a boolean, if `TRUE` (the default) visually mark the medication groups the belong to the same patient, using horizontal lines and alternating vertical lines.
`medication.groups.separator.lty`, `medication.groups.separator.lwd`, `medication.groups.separator.color`	graphical parameters (line type, line width and colour describing the visual marking og medication groups as beloning to the same patient.
`medication.groups.allother.label`	a string giving the label to use for the implicit `__ALL_OTHERS__` medication group (defaults to "*").
`lty.event`, `lwd.event`, `pch.start.event`, `pch.end.event`	The style of the event (line style, width, and start and end symbols).
`plot.events.vertically.displaced`	Should consecutive events be plotted on separate rows (i.e., separated vertically, the default) or on the same row?
`print.dose`	Logical, should the daily dose be printed as text?
`cex.dose`	Numeric, if daily dose is printed, what text size to use?
`print.dose.outline.col`	If `NA`, don't print dose text with outline, otherwise a color name/code for the outline.
`print.dose.centered`	Logical, print the daily dose centered on the segment or slightly below it?
`plot.dose`	Logical, should the daily dose be indicated through segment width?
`lwd.event.max.dose`	Numeric, the segment width corresponding to the maximum daily dose (must be >= lwd.event but not too big either).
`plot.dose.lwd.across.medication.classes`	Logical, if `TRUE`, the line width of the even is scaled relative to all medication classes (i.e., relative to the global minimum and maximum doses), otherwise it is scale relative only to its medication class.
`col.continuation`, `lty.continuation`, `lwd.continuation`	The style of the "continuation" lines connecting consecutive events (colour, line style and width).
`col.na`	The colour used for missing event data.
`highlight.followup.window`	Logical, should the follow-up window be plotted?
`followup.window.col`	The follow-up window's colour.
`highlight.observation.window`	Logical, should the observation window be plotted?
`observation.window.col`, `observation.window.density`, `observation.window.angle`, `observation.window.opacity`	Attributes of the observation window (colour, shading density, angle and opacity).
`alternating.bands.cols`	The colors of the alternating vertical bands distinguishing the patients; can be `NULL` = don't draw the bandes; or a vector of colors.
`rotate.text`	Numeric, the angle by which certain text elements (e.g., axis labels) should be rotated.
`force.draw.text`	Logical, if `TRUE`, always draw text even if too big or too small
`bw.plot`	Logical, should the plot use grayscale only (i.e., the `gray.colors` function)?
`min.plot.size.in.characters.horiz`, `min.plot.size.in.characters.vert`	Numeric, the minimum size of the plotting surface in characters; horizontally (min.plot.size.in.characters.horiz) refers to the the whole duration of the events to plot; vertically (min.plot.size.in.characters.vert) refers to a single event. If the plotting is too small, possible solutions might be: if within `RStudio`, try to enlarge the "Plots" panel, or (also valid outside `RStudio` but not if using `RStudio server` start a new plotting device (e.g., using `X11()`, `quartz()` or `windows()`, depending on OS) or (works always) save to an image (e.g., `jpeg(...); ...; dev.off()`) and display it in a viewer.
`suppress.warnings`	Logical: show or hide the warnings?
`max.patients.to.plot`	Numeric, the maximum patients to attempt to plot.
`export.formats`	a string giving the formats to export the figure to (by default `NULL`, meaning no exporting); can be any combination of "svg" (just an `SVG` file), "html" (`SVG` + `HTML` + `CSS` + `JavaScript`, all embedded within one `HTML` document), "jpg", "png", "webp", "ps" or "pdf".
`export.formats.fileprefix`	a string giving the file name prefix for the exported formats (defaults to "AdhereR-plot").
`export.formats.height`, `export.formats.width`	numbers giving the desired dimensions (in pixels) for the exported figure (defaults to sane values if `NA`).
`export.formats.save.svg.placeholder`	a logical, if TRUE, save an image placeholder of type given by `export.formats.svg.placeholder.type` for the `SVG` image.
`export.formats.svg.placeholder.type`	a string, giving the type of placeholder for the `SVG` image to save; can be "jpg", "png" (the default) or "webp".
`export.formats.svg.placeholder.embed`	a logical, if `TRUE`, embed the placeholder image in the HTML document (if any) using `base64` encoding, otherwise (the default) leave it as an external image file (works only when an `HTML` document is exported and only for `JPEG` or `PNG` images.
`export.formats.html.template`, `export.formats.html.javascript`, `export.formats.html.css`	character strings or `NULL` (the default) giving the path to the `HTML`, `JavaScript` and `CSS` templates, respectively, to be used when generating the HTML+CSS semi-interactive plots; when `NULL`, the default ones included with the package will be used. If you decide to define new templates please use the default ones for inspiration and note that future version are not guaranteed to be backwards compatible!
`export.formats.directory`	a string; if exporting, which directory to export to; if `NA` (the default), creates the files in a temporary directory.
`generate.R.plot`	a logical, if `TRUE` (the default), generate the standard (base `R`) plot for plotting within `R`.
`do.not.draw.plot`	a logical, if `TRUE` (not the default), does not draw the plot itself, but only the legend (if `show.legend` is `TRUE`) at coordinates (0,0) irrespective of the given legend coordinates. This is intended to allow (together with the `get.legend.plotting.area()` function) the separate plotting of the legend.

Details

The x-axis represents time (either in days since the earliest date or as actual dates), with consecutive events represented as ascending on the y-axis.

Each event is represented as a segment with style lty.event and line width lwd.event starting with a pch.start.event and ending with a pch.end.event character, coloured with a unique color as given by col.cats, extending from its start date until its end date. Consecutive events are thus represented on consecutive levels of the y-axis and are connected by a "continuation" line with col.continuation colour, lty.continuation style and lwd.continuation width; these continuation lines are purely visual guides helping to perceive the sequence of events, and carry no information about the availability of medication in this interval.

When several patients are displayed on the same plot, they are organized vertically, and alternating bands (white and gray) help distinguish consecutive patients. Implicitly, all patients contained in the cma object will be plotted, but the patients.to.plot parameter allows the selection of a subset of patients.

Examples

cma0 <- CMA0(data=med.events,
             ID.colname="PATIENT_ID",
             event.date.colname="DATE",
             event.duration.colname="DURATION",
             event.daily.dose.colname="PERDAY",
             medication.class.colname="CATEGORY",
             followup.window.start=0,
             followup.window.start.unit="days",
             followup.window.duration=2*365,
             followup.window.duration.unit="days",
             observation.window.start=30,
             observation.window.start.unit="days",
             observation.window.duration=365,
             observation.window.duration.unit="days",
             date.format="%m/%d/%Y",
             summary="Base CMA");
plot(cma0, patients.to.plot=c("1","2"));

[Package AdhereR version 0.8.1 Index]