AdhereR: Interactive plotting (and more) with Shiny

About the App

Clicking on the About button (element 1 in the overview figure) opens a box with info about the App, such as the version of the AdhereR package, and overview of the package and links to where more help (such as vignettes) can be found.

Cleanly exiting the App

It is recommended to cleanly exit the App by clicking the Exit… button (element 2 in the overview figure), as simply closing the browser will not normally also stop the R process running in the background. Please note that currently, exiting the App will not also close the browser window or tab in which the App was running…

The plotting area (and the messages)

The current plot is displayed in the UI element 3 (in the overview figure), a canvas that can be re-sized using the UI elements 4 in the overview figure (see also below) and which, when too big, can be scrolled horizontally and vertically at will. This canvas is currently passive in the sense that it simply displays a plot which which interaction is possible only using the other elements of the UI, but almost all aspects of this plot can be tweaked using controls from the left-hand side vertical panel (element 5 in the overview figure; see details below).

While the interpretation of these plots should be relatively intuitive, it is nevertheless detailed in the AdhereR: Adherence to Medications vignette.

Element 9 in the overview figure displays most of the information messages, warnings and errors generated during the plotting process (please note that currently some messages, warnings and errors might not be captured and only shown in the R console). For example, here, the informational message Plotting patient ID ‘1’ with CMA ‘CMA9’ Plotting patient ID ‘2’ with CMA ‘CMA9’ means that the computation and plotting of CMA9 for patients with IDs 1 and 2 was successful.

Elements 4 in the overview figure allow the control of the horizontal and vertical dimensions of the plot 3 either coupled (i.e., keeping the current width–to-height ratio), when the Keep ratio switch is ON, or independently of each other, when the switch is OFF (in which case a new slider controlling the plot height appears). The interaction with the slider(s) can be done either with mouse or with the arrow keys.

Please note that there is a minimum size requirement for a plot to be displayed, otherwise an error of the type

Plotting area is too small (it must be at least 10 x 0.5 characters per event, but now it is only 31.1 x 0.5)!

is thrown, in which case either the plotting area needs to be increased using the Plot width (and, if visible, Plot height) slider(s), or the number of patients or the duration to be shown need to be reduced. Alternatively, the Advanced section (see Section Setting parameters for details) can be used to decrease these minimum requirements (but this not recommended in most cases).

Saving the current plot to file

The current plot can be exported to a variety of formats by turning the Save plot! switch ON:

Saving the current plot to file. A zoom-in of the new controls (element 10) revealed by turning the Save plot! switch (UI element 6) ON. Also visible is an explanatory tooltip .

These new UI elements (10) allow:

• the definition of the exported plot’s size (width and height)
• in terms of the selected unit, currently in (inches), cm (centimeters), mm (millimeters) and px (pixels)
• the type of image, currently jpg (JPEG), png (PNG), tiff (TIFF), eps (Encapsulated Postscript) and pdf (PDF) – usually TIFF and EPS are accepted for publication
• at a given resultion in dots-per-inch (DPI) – used only by the raster formats JPEG, PNG and TIFF (usually a minimum of 300 DPI are needed for publication).

By pressing the Save plot button, the user can select the location and file name (relative to the local machine) under which the plot will be exported.

Viewing, copying and using the R code that would produce the current plot

While the main use scenarios for this App are built around interactivity, the user may want to generate the same (or similar) plots as the one currently displayed (in element 3 in the overview figure). To allow this, we provide the Show R code… button (element 7 in the overview figure), which opens a box with the clearly commented R code:

Viewing the R code that can generates the current plot.

Clicking the Copy to clipboard button copies the R code to the clipboard, from where it can be pasted into an editor of choice (such as RStudio). In particular, for the plot shown in the overview figure, the R code displayed is:

# The R code corresponding to the currently displayed Shiny plot:
# 
# Extract the data for the selected 2 patient(s) with ID(s):
# "1", "2"
# 
# We denote here by DATA the data you are using in the Shiny plot.
# This was manually defined as an object of class data.frame
# (or derived from it, such a data.table) that was already in
# memory under the name 'med.events'.
# Assuming this object still exists with the same name, then:

DATA <- med.events;

# These data has 5 columns, and contains info for 100 patients.
# 
# To allow using data from other sources than a "data.frame"
# and other similar structures (for example, from a remote SQL
# database), we use a metchanism to request the data for the
# selected patients that uses a function called
# "get.data.for.patients.fnc()" which you may have redefined
# to better suit your case (chances are, however, that you are
# using its default version appropriate to the data source);
# in any case, the following is its definition:
get.data.for.patients.fnc <- function(patientid, d, idcol, cols=NA, maxrows=NA) d[ d[[idcol]] %in% patientid, ]
# Try to extract the data only for the selected patient ID(s):
.data.for.selected.patients. <- get.data.for.patients.fnc(
    c("1", "2"),
    DATA, ### don't forget to put here your REAL DATA! ###
    "PATIENT_ID"
);
# Compute the appropriate CMA:
cma <- CMA9(data=.data.for.selected.patients.,
            # (please note that even if some parameters are
            # not relevant for a particular CMA type, we
            # nevertheless pass them as they will be ignored)
            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,
            followup.window.start.unit="days",
            followup.window.duration=730,
            followup.window.duration.unit="days",
            observation.window.start=0,
            observation.window.start.unit="days",
            observation.window.duration=730,
            observation.window.duration.unit="days",
            date.format="%m/%d/%Y"
           );

if( !is.null(cma) ) # if the CMA was computed ok
{
    # Try to plot it:
    plot(cma,
         # (same idea as for CMA: we send arguments even if
         # they aren't used in a particular case)
         align.all.patients=FALSE,
         align.first.event.at.zero=FALSE,
         show.legend=TRUE,
         legend.x="right",
         legend.y="bottom",
         legend.bkg.opacity=0.5,
         legend.cex=0.75,
         legend.cex.title=1,
         duration=NA,
         show.period="days",
         period.in.days=90,
         bw.plot=FALSE,
         col.na="#D3D3D3",
         unspecified.category.label="drug",
         col.cats=rainbow,
         lty.event="solid",
         lwd.event=2,
         pch.start.event=15,
         pch.end.event=16,
         col.continuation="#000000",
         lty.continuation="dotted",
         lwd.continuation=1,
         cex=1,
         cex.axis=1,
         cex.lab=1.25,
         highlight.followup.window=TRUE,
         followup.window.col="#00FF00",
         highlight.observation.window=TRUE,
         observation.window.col="#FFFF00",
         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.CMA=TRUE,
         CMA.cex=0.5,
         plot.CMA=TRUE,
         CMA.plot.ratio=0.1,
         CMA.plot.col="#90EE90",
         CMA.plot.border="#006400",
         CMA.plot.bkg="#7FFFD4",
         CMA.plot.text="#006400",
         plot.CMA.as.histogram=TRUE,
         show.event.intervals=TRUE,
         print.dose=TRUE,
         print.dose.outline.col="#FFFFFF",
         print.dose.centered=FALSE,
         plot.dose=FALSE,
         lwd.event.max.dose=8,
         plot.dose.lwd.across.medication.classes=FALSE,
         min.plot.size.in.characters.horiz=10,
         min.plot.size.in.characters.vert=0.5
    );
}

This code is pretty much ready to be run, except for some issues that might surround accessing the actual data used for plotting: the user is reminded of these through the yellow-on-red bold italic highlighting of DATA (not shown in the code listing above). In a nutshell (for details, see below), if (a) the user interactively uses the App to load or connect to a data source (such as an external file or an SQL database), then the identity of this data source is known (the file name or the database location), but if (b) the data source was passed to the plot_interactive_cma() function as the data argument, the App cannot know how this data source was named (and this “name” might not even exist if, for example, the data was created on-the-fly while calling the plot_interactive_cma() function). Wickedly, even in case (a), it is generally unsafe to assume that the data source will stay the same (or will be accessible in the same way) in the future. Thus, while we provide as much info about the data source used to produce the current plot as possible, we also warn the user to be careful when running this code!

Computing the CMA for several patients

By switching the UI element 8 (in the overview figure) Compute CMA for several patients… to ON, the user unlocks a new set of UI elements that allow the computation of the currently defined CMA for more patients and the export of the results to an external file.

First, it is important to highlight that the App is not intended for heavy computations, which explains why we are currently limiting this CMA computation to at most 100 patients, at most 5000 events across all patients (if more patients or events are selected, the computation will be done for only the first 100 and 5000, respectively) and for at most 5 minutes of running time (after which the computation is automatically stopped). If seriously heavy computation is needed, we recommend the use of the appropriate CMA() functions from and R session or script, which allow many types of parallel processing and the use of several types of data sources with very fine-grained control, as described in the vignettes AdhereR: Adherence to Medications and Using AdhereR with various database technologies for processing very large datasets. The R code needed to compute the current CMA can be accessed through the Show R code button (UI element 7).

The patients for which the computation of the CMA is to be performed can be done in two main ways:

1. by individually selecting patients by their IDs, through a multiple selection dropdown list (element 11 in the figure below):

Selecting patients individually for the computation of CMA.

2. by selecting a continuous range of patients using two sliders (element 15 in the figure below) which define a set of positions in a list (element 14 in the figure below); this list can contain the patient IDs in their original order in the data source, or can have them sorted in ascending or descending order by ID (element 13 in the figure below).

Selecting patients by range of positions in a list for the computation of CMA. In this example, we ordered the patients descreasingly by ID (using the combobox 13), resulting in a mapping of positions (#) to ID as shown in the list 14, where patient with ID “100” is on psition 1, patient “99” on position 2, etc. The sliders 15 define the range of positions (#) 3 to 24, which means that we selected patients with IDs “98”, “97”, “96” … “78” and “77”.

These two ways of selecting patients should be flexible enough for cover most cases of (semi-)interactive use; for more patients and/or the selection of patients based on more complex criteria, we suggest the use of the R code in a script.

After patients have been selected, the user can press the Compute CMA button (UI element 12) to access a specialized dialog box (see figure below) where the CMA computation can be started, its progress monitored, or stopped, and from where the results can be exported to file.

Starting, stopping and watchin the progress of CMA computation for several patients. The list of patients is given in UI element 16, and the progress of the computation is tracked by theprogress bar and individual success report (UI elements 17). The button Save results (as TSV) allows the user to select a file where the results will be exported as a TAB-separated CSV file.

Setting parameters

The left-hand panel has two tabs: Params and Data, and we are focusing here on Params, which contains various parameters customizing the computed CMA and the plotting of the results. UI element 5 in the overview figure shows part of this panel, but the following principles apply:

• the top Dataset info button gives access to information about the current data source such as its name, type, structure and the five important columns:

Basic information about the current dataset. Here, med.events, showing also the five important columns.

• there are several sections with dark blue bold headings
• the contents of most of sections can be hidden (by default, marked by the “…”) or visible, the two states being toggled by clicking the mouse (see the figure below), the only exception being the first section, General settings, whose contents is always visible

Folding and unfolding the contents of a section. The section Follow-up window (FUW) with content folded (hidden) on the left, and unfolded (visible) on the right.

• some sections may appear or disappear depending on other circumstances, such as the type of CMA selected (e.g., Define episodes exists only for CMA per episodes) or the optional columns being defined (e.g., Show dose exists only if the daily dose column was defined and only for CMA0, CMA5-9, per episodes, and sliding windows).

We will now go through all sections one by one.