plot.CMA1: Plot CMA0-derived objects.

In AdhereR: Adherence to Medications

Plot CMA0-derived objects.

Description

Plots the event data and estimated CMA encapsulated in objects derived from CMA0.

Usage

## S3 method for class 'CMA1'
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,
  show.cma = TRUE,
  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,
  show.event.intervals = TRUE,
  col.na = "lightgray",
  print.CMA = TRUE,
  CMA.cex = 0.5,
  plot.CMA = TRUE,
  CMA.plot.ratio = 0.1,
  CMA.plot.col = "lightgreen",
  CMA.plot.border = "darkgreen",
  CMA.plot.bkg = "aquamarine",
  CMA.plot.text = CMA.plot.border,
  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,
  show.real.obs.window.start = TRUE,
  real.obs.window.density = 35,
  real.obs.window.angle = 30,
  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,
  alternating.bands.cols = c("white", "gray95"),
  bw.plot = FALSE,
  rotate.text = -60,
  force.draw.text = FALSE,
  min.plot.size.in.characters.horiz = 0,
  min.plot.size.in.characters.vert = 0,
  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.directory = NA,
  export.formats.html.template = NULL,
  export.formats.html.javascript = NULL,
  export.formats.html.css = NULL,
  generate.R.plot = TRUE,
  do.not.draw.plot = FALSE
)

## S3 method for class 'CMA2'
plot(...)

## S3 method for class 'CMA3'
plot(...)

## S3 method for class 'CMA4'
plot(...)

## S3 method for class 'CMA5'
plot(...)

## S3 method for class 'CMA6'
plot(...)

## S3 method for class 'CMA7'
plot(...)

## S3 method for class 'CMA8'
plot(...)

## S3 method for class 'CMA9'
plot(...)

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, CMA.cex	numeric values specifying the cex of the various types of text.
show.cma	Logical, should the CMA type be shown in the title?
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).
show.event.intervals	Logical, should the actual event intervals be shown?
col.na	The colour used for missing event data.
print.CMA	Logical, should the CMA values be printed?
plot.CMA	Logical, should the CMA values be represented graphically?
CMA.plot.ratio	A number, the proportion of the total horizontal plot space to be allocated to the CMA plot.
CMA.plot.col, CMA.plot.border, CMA.plot.bkg, CMA.plot.text	Strings giving the colours of the various components of the CMA plot.
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).
show.real.obs.window.start, real.obs.window.density, real.obs.window.angle	For some CMAs, the observation window might be adjusted, in which case should it be plotted and with that attributes?
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.
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.
bw.plot	Logical, should the plot use grayscale only (i.e., the gray.colors function)?
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
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.
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.directory	a string; if exporting, which directory to export to; if NA (the default), creates the files in a temporary directory.
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!
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

Please note that this function plots objects inheriting from CMA0 but not objects of type CMA0 itself (these are plotted by plot.CMA0).

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. Superimposed on these are shown the event intervals and gap days as estimated by the particular CMA method, more precisely plotting the start and end of the available events as solid filled-in rectangles, and the event gaps as shaded rectangles.

The follow-up and the observation windows are plotted as an empty rectangle and as shaded rectangle, respectively (for some CMAs the observation window might be adjusted in which case the adjustment may also be plotted using a different shading).

The CMA estimates can be visually represented as well in the left side of the figure using bars (sometimes the estimates can go above 100%, in which case the maximum possible bar filling is adjusted to reflect this).

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

Finally, the y-axis shows the patient ID and possibly the CMA estimate as well.

Examples

cma1 <- CMA1(data=med.events,
             ID.colname="PATIENT_ID",
             event.date.colname="DATE",
             event.duration.colname="DURATION",
             followup.window.start=30,
             observation.window.start=30,
             observation.window.duration=365,
             date.format="%m/%d/%Y"
            );
plot(cma1, patients.to.plot=c("1","2"));

AdhereR documentation built on July 5, 2022, 5:08 p.m.