plot.CMA_per_episode: Plot CMA_per_episode and CMA_sliding_window objects.

Description

Plots the event data and the estimated CMA per treatment episode and sliding window, respectively.

Usage

# S3 method for CMA_per_episode
plot(x, ..., patients.to.plot = NULL,
  duration = NA, align.all.patients = FALSE,
  align.first.event.at.zero = TRUE, show.period = c("dates",
  "days")[2], period.in.days = 90, show.legend = TRUE,
  legend.x = "right", legend.y = "bottom", legend.bkg.opacity = 0.5,
  cex = 1, cex.axis = 0.75, cex.lab = 1, show.cma = TRUE,
  col.cats = rainbow, unspecified.category.label = "drug",
  lty.event = "solid", lwd.event = 2, pch.start.event = 15,
  pch.end.event = 16, col.na = "lightgray",
  col.continuation = "black", lty.continuation = "dotted",
  lwd.continuation = 1, print.CMA = TRUE, CMA.cex = 0.5,
  plot.CMA = TRUE, plot.CMA.as.histogram = 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, show.real.obs.window.start = TRUE,
  real.obs.window.density = 35, real.obs.window.angle = 30,
  bw.plot = FALSE)
# S3 method for CMA_sliding_window
plot(...)

Arguments

A CMA0 or derived object, representing the CMA to plot

...

other parameters (to be passed to the estimation and plotting of the simple CMA)

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

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.

lty.event, lwd.event, pch.start.event, pch.end.event

The style of the event (line style, width, and start and end symbols).

col.na

The colour used for missing event data.

col.continuation, lty.continuation, lwd.continuation

The color, style and width of the contuniation lines connecting consecutive events.

print.CMA

Logical, should the CMA values be printed?

CMA.cex

... and, if printed, what cex (numeric) to use?

plot.CMA

Logical, should the CMA values be represented graphically?

plot.CMA.as.histogram

Logical, should the CMA plot be a histogram or a (truncated) density plot? Please note that it is TRUE by deafult for CMA_per_episode and FALSE for CMA_sliding_window, because usually there are more sliding windows than episodes. Also, the density estimate canot be estimated for less than three different values.

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

highlight.observation.window

Logical, should the observation window be plotted?

observation.window.col, observation.window.density, observation.window.angle

Attributes of the observation window (colour, shading density and angle).

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?

bw.plot

Logical, should the plot use grayscale only (i.e., the gray.colors function)?

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 avilability of medicine in this interval.

Above these, the treatment episodes or the sliding windows are represented in a stacked manner from the earlieast (left, bottom of the stack) to the latest (right, top of the stack), each showing the CMA as percent fill (capped at 100% even if CMA values may be higher) and also as text.

The follow-up and the observation windows are plotted as empty an 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 kernel density ("smoothed histogram") of the CMA estimates across treatment episodes/sliding windows (if more than 2) can be visually represented as well in the left side of the figure (NB, their horizontal scales may be different across patients).

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.

Any not explicitely defined arguments are passed to the simple CMA estimation and plotting function; therefore, for more info about possible estimation parameters plese see the help for the appropriate simple CMA, and for possible aesthetic tweaks, please see the help for their plotting.

Examples

Run this code

# NOT RUN {
cmaW <- CMA_sliding_window(CMA=CMA1,
                        data=med.events,
                        ID.colname="PATIENT_ID",
                        event.date.colname="DATE",
                        event.duration.colname="DURATION",
                        event.daily.dose.colname="PERDAY",
                        medication.class.colname="CATEGORY",
                        carry.only.for.same.medication=FALSE,
                        consider.dosage.change=FALSE,
                        followup.window.start=0,
                        observation.window.start=0,
                        observation.window.duration=365,
                        sliding.window.start=0,
                        sliding.window.start.unit="days",
                        sliding.window.duration=90,
                        sliding.window.duration.unit="days",
                        sliding.window.step.duration=7,
                        sliding.window.step.unit="days",
                        sliding.window.no.steps=NA,
                        date.format="%m/%d/%Y"
                       );
plot(cmaW, patients.to.plot=c("1","2"));
cmaE <- CMA_per_episode(CMA=CMA1,
                        data=med.events,
                        ID.colname="PATIENT_ID",
                        event.date.colname="DATE",
                        event.duration.colname="DURATION",
                        event.daily.dose.colname="PERDAY",
                        medication.class.colname="CATEGORY",
                        carry.only.for.same.medication=FALSE,
                        consider.dosage.change=FALSE,
                        followup.window.start=0,
                        observation.window.start=0,
                        observation.window.duration=365,
                        date.format="%m/%d/%Y"
                       );
plot(cmaE, patients.to.plot=c("1","2"));
# }

Run the code above in your browser using DataLab

Description

Usage

Arguments

Details

See Also

Examples