AdhereR: Interactive plotting (and more) with Shiny

General settings

The General settings section is always visible and allows the selection of:

• CMA type: the type of CMA to compute, which can be (please see Dima & Dediu, 2017, and the vignette AdhereR: Adherence to Medications for more details):

  • simple: one of the “simple” CMAs, currently CMA0 tot CMA9,
  • per episode: computes one of the “simple” CMAs repeatedly for each treatment episode,
  • sliding window: computes one of the “simple” CMAs repeatedly for a set of sliding windows

• CMA to compute: the “simple” CMA to compute, either by itself (for CMA type == simple) or iteratively (for the other two “complex” types); please note that by definition CMA0 cannot be used with “complex” CMAs (which explains why it cannot be selected in these cases)

• Patient(s) to plot: the list of patient IDs, selected from a drop-down list (which allows multiple selections) containing all the patient IDs in the current data source (at least one patient must be selected, otherwise an error is generated)

Depending on these selections the plot may change or various types of errors or warnings may be thrown.

Follow-up window (FUW) and Observation window (OW)

These two sections are very similar and allow the definition of the follow-up (FUW) and observation (OW) windows by specifying:

• their start: this can be either:

  • the number of units (days, weeks, months or years) relative to the first event (for FUW) and to the start of the FUW (for OW), or
  • an absolute calendar date

• and their duration as a number of units (days, weeks, months or years).

Carry over

This section is shown only for CMA5 to CMA9 and concerns the way carry over is considered:

• For same treat.only: only for the treatment class or across classes
• Consider dosage changes: should dosage changes be considered when computing the carry over?

Define episodes

This section is shown only for CMA per episodes and concerns the way treatment episodes are defined:

• Treat. change starts new episode?: does changing the treatment class trigger a new episode?
• Dose change starts new episode?: does changing the dose trigger a new episode?
• Max. gap duration: the duration of a gap above which a new episode is triggered; the gap can be in units (Max. gap duration unit) of days, weeks, months or years, or as a percent of the last prescription
• Append gap?: should the maximum permissible gap be added to the episodes with a gap larger than this maximum? If “no” (the default), nothing is added, if “yes” then the maximum permissible gap is appended at the end of the episodes
• Plot CMA as histogram?: should the distribution of CMA estimates across episodes for a given participant be plotted as a histogram or as a barplot

Define sliding windows (SW)

This section is shown only for sliding windows and concerns the way this sequence of regularly spaced and uniform sliding windows is defined:

• SW start: when is the first sliding window starting (relative to the start of the OW) in terms of units (SW start unit) that can be days, weeks, months or years

• how long is one such sliding window SW duration in terms of SW duration unit (days, weeks, months or years)

• the step between two consecutive sliding windows can be defined either in terms of:

  • SW number of steps: the total number of steps (i.e., sliding windows of the given duration covering the OW), or
  • the duration of a setp (i.e., one sliding window) in terms of how many (SW step duration) units (SW step unit; days, weeks, months or years) it lasts

• Plot CMA as histogram?: should the distribution of CMA estimates across sliding windows for a given participant be plotted as a histogram or as a barplot

Defining sliding windows. Here we show 90-days sliding windows lagging by 60 days and starting right at the begining of the observation window. The regularly spaced bars at the top of the plot represent the sliding window, each with its own CMA estimate (here, CMA9). The histogram on the left (which can be toggled to a barplot) shows the distribution of the CMA estimates across the sliding windows.

Align patients

This section is shown only if there’s more than one patient selected, and controls the way the plots of several patients are displayed vertically:

• Align patients?: should all the patients be vertically aligned relative to their first event?
• Align 1st event at 0?: should the first event (across patients) be considered as the origin of time?

Vertically aligning multiple patients. The top panel shows two patients (with IDs ‘1’ and ‘15’) plotted using the actual dates of their events (as difference between the earilest event and their own) versus the same two patients aligned vertically relative to each other.

Duration & period

This section controls the amount of temporal information displayed (on the horizontal axis):

• Duration (in days): the period to show (in days); this is independent of the length of the FUW, OW or the events actually displayed and can be used to zoom-in or zoom-out; if 0 it is automatically computed so as all the events in the plot are shown
• Show period as: if “days”, it displays on the horizontal axis the number of days since the first plotted event on the horizontal axis; if “dates”, it displays the actual calendar dates – Period (in days): the interval (in days) at which info is shown on the horizontal axis and vertical dashed lines are drawn on the plot

CMA estimates

This section is shown for all CMAs except CMA0 and controls how the CMA estimates are to be shown on the plot:

• Print CMA?: this is visible only for the “simple” CMAs and controls whether the CMA estimates should be shown next to the participant’s ID
• Plot CMA?: should the CMA estimate be plotted next to the participant’s ID?

Show dose

This section is shown only a daily dose column is defined for the current data source, and only for CMA0, CMA5–CMA9, per episodes, and sliding windows (CMA1–CMA4 by definition are unaware of dose and treatment categories) and controls how the dose is visually shown (if at all):

• Print it?: print the dosage (i.e., the actual numeric values) next to each event; if so:

  • Font size: which font size¹ to use
  • Outline color: which outline color to use
  • Centered?: should the text be centered or not?

• As line width?: show the dose as the event line width; if so:

  • Max dose width: what is the line width of the maximum given dose?
  • Global max?: should this maximum dose be computed across all treatment classes or per class?

Please see the overview figure for an example where the dose is printed.

Legend

This section controls the visual appearance of the legend:

• Show legend?: should the legend be shown at all; if so:

  • Legend x: the legend’s horizontal position (“left” or “right”)
  • Legend y: the legend’s vertical position (“bottom” or “top”)
  • Title font size: the legend title’s font size
  • Text font size: the legend text and symbols’ font size
  • Legend bkg. opacity: the legend’s background opacity, between 0.0 (fully transparent) and 1.0 (fully opaque)

Aesthetics

This section controls many aspects of the visual presentation of the plots, including colors, font sizes and line styles; some of these depend on other factors, so may or may not be visible:

• Grayscale?: when ON, it makes the plots use only shades of gray (and hides many other controls in this section), but when OFF, it allows various colors to be used
• Missing data color: the colors of missing data
• Unspec. cat. label: the label to use for an unspecified treatment class (free text)
• Treatment palette: shown only if the treatment class column was defined, allows the selection of a color palette from which particular colors for the actual treatment classes will be picked²; currently the available palettes are: rainbow, heat.colors, terrain.colors, topo.colors, cm.colors, magma, inferno, plasma, viridis, cividis (the last two are color-blind-friendly³)
• Event line style: controls the line style for plotting the events, and can be:

The possible line styles used for the event lines.

• Event line width: the width of the event lines
• Event start and Event end: the symbols used to mark the start and end of an event, and can be:

The possible point symbols used to mark the start and the end of an event.

• attributes of the continuation lines between events (only for CMA0, per episode, and sliding windows): Cont. line color, Cont. line style and Cont. line width
• Show event interv.?: should the event intervals be shown? (only for simple CMAs except CMA0)
• the relative font size of various elements: General font size, Axis font size and Axis labels font size
• follow-up window visual attributes: Show FUW? (should we show it or not), and if yes, FUW color, what color to use?
• observation window visual attributes: Show OW? (should we show it or not), and if yes, with what color (OW color), line density (OW hash dens.) and angle (OW hash angle) and opacity (OW opacity)
• CMA8 uses a “real observation window”, which ca be shown or not (Show real OW?) and whose attributes are the line density (Real OW hash dens) and angle (Real OW hash angle)
• for all CMAs (except CMA0), we can control various attributes of the CMA estimate: the relative font size (CMA font size), the percent of the plotting area dedicated to plotting it (CMA plot area %), its color (CMA plot color), border color (CMA border color), background color (CMA bkg. color) and text color (CMA text color)

Advanced

This section controls several advanced settings:

• Min plot size (horiz.) and Min plot size (vert.): the minimum plotting size (in characters) required for the whole duration to be plotted (horizontally) and for each event/episode/sliding window (vertically)

Data already in memory

This is, in some respects, the simplest type of data source. When selected, the tab looks like:

Selecting and in-memory data source.

The In-memory dataset UI element contains the list of all objects in the current global environment derived from data.table that have at last 1 row and 3 columns, and they can be selected simply by clicking on their name (here, we select the med.events example dataset):

Selecting the med.events example dataset. Please note that the selection ca be done by looking through the list, or by typing the delete/backspace key (⌫) and then starting to type the name of the dataset.

After clicking on it, the dataset is selected and optionally available for inspection using the Peek at dataset button:

Peeking at (i.e., inspecting) the in-memory dataset med.events. This box shows basic info about the dataset, including the number of rows and columns and, for each column, its name and type, plus the first few rows.

If the dataset is not the desired one, it can be replaced with anything else using the interface, but, if it is the one, we can continue by selecting the important columns and the format of the dates.

Selecting the “important” columns – here, the one contaning the Patient IDs – from the in-memory dataset med.events. Please note that the list give extra summary info about the columns in the dataset (namely, its name, type, and first few values). The App automatically maps the first three columns in the dataset to the first three required columns (Patient ID column, Event date column and Event duration column) but this is most probably wrong and no type checks are done at this time. The “optional” columns (Daily dose column and Treatment class column may be left undefined by selecting the [not defined] value. Date format is different, being a free text field where the format of the dates in the dates column must be defined (please see, for example here, for how this format looks like).

Please note that, at this time, the dataset is not selected to be used for plotting: this is an explicit action done by pressing the Validate & use! button at the bottom, which does perform various checks (such as that each column is used at most once and that the types more or less fit the expected type and format, among others) and, if OK, makes this dataset the one to be used for plotting.

Load from file

This is a very useful case, where the data is stored in an external file. When selecting load from file in the Datasource type list, the panel becomes:

Loading a dataset from file.

The App supports loading data from several file formats:

• Comma/TAB-separated (.csv; .tsv; .txt): this is the default format and refers to a class of open and flexible file formats where tabular data is stored as rows of values separated by a pre-defined delimiter; the best known are Comma-Separated Values (CSV) and TAB-Separated Values (TSV) formats, but the App allows a lot of flexibility by defining:

  • the Field separator can be: the [TAB] character (\t), the comma (,), one or more whitespaces, the semicolon (;) or the colon (:)
  • the individual values can be quoted (or not) using the Quote character: [none] (no quoting of values), single quotes (’) or double quotes (“)
  • the Decimal point character: dot (.) or comma (,)
  • the Missing data symbols: a free text listing (within double quotes and separated by commas) the symbol(s) to be interpreted as missing data (by default, “NA”)
  • if the 1^st row of the file represents the header (containing the column names) or not (Header 1^st row)

• Serialized R object (.rds): this loads data (such as objects derived from data.frame) previously exported from R using readRDS() (usually as “.rds”)

• Open Document Spreadsheet (.ods) and Microsoft Excel (.xls; .xlsx) loads data from these widespread formats, used by office suites such as LibreOffice/OpenOffice’s Calc and Micrsoft Office’s Excel programs, among others; for both these formats, the user can specify the particular sheet to be loaded for files containing more than one (Which sheet to load?)

• SPSS (.sav; .por), SAS Transport data file (.xpt), SAS sas7bdat data file (.sas7bdat) and Stata (.dta): these are file formats exported by the popular statistical platforms IBM SPSS, SAS and Stata

Please note that while Comma/TAB-separated (.csv; .tsv; .txt), Serialized R object (.rds) and Open Document Spreadsheet (.ods) should be imported without issues, for the others there might limitations and fringe cases.

After the file format has been selected, the user can use the Load from file control (its Selecte button) to browse for the desired file and upload it. Basic checks might be performed and a file might be rejected, but if the loading was successful, a new set of UI elements becomes visible. These elements are virtually identical to those used for in-memory datasets.

Use an SQL database

This allows the access to data stored in standard Relational Database Management Systems (RDBMS’s) which use the Structured Query Language (SQL) – for more info about the facilities offered by AdhereR, please see the Using AdhereR with various database technologies for processing very large datasets vignette.

Currently, the App supports SQLite, a small engine designed to be embedded in larger applications and which stored the data in normal files, and MySQL/MariaDB, which are widely-used, full-featured free and open-source RDBMSs.

While SQLite is intended only as a demo of the App’s capabilities and uses an in-memory database with a single table that contains a verbatim copy of the med.events example dataset, MySQL/MariaDB allows the use of actual databases, local or over the internet. Except for the selection of the database, the UI for the two is identical, so we will only discuss here the MySQL/MariaDB case

We can connect to a local or remote server, and we can (optionally) define the following:

• Host name/address: the fully qualified host name or IP address of the server (if [none] or localhost, the database is stored on the local machine)
• TCP/IP port number: the port number (0 for default)
• Database name: the name of the database
• Username and Password: the username and password for accessing the database (the password is hidden using *)

Inputting the info needed to connect to a remote MySQL server. We use here a MySQL database contaning the med.events sample dataset hosted on the internet.

When clicking the Connect! button, the App attempts to connect the server, authenticate and access the desired database: if everything’s OK, it fetches basic information over all the tables/views in the database (avoiding thus unnecessary traffic) and displays it:

Basic information about an SQL database. This shows, for each table/view in the database, the columns with their name, type and first few values. The same info is accessible by clicking on the Peek at database… button.

New UI elements become visible, most being virtually identical to those used for loading from file and in-memory datasets, but the specific ones being:

• the Disconnect! button; this disconnects from the database cleanly (not required by nice to do)
• Which table/view lists the tables and views in the database, also showing for each the number of rows and columns

UI elements for using an SQL database.

For example, when using the MySQL database described in the vignette Using AdhereR with various database technologies for processing very large datasets in package AdhereR, we can create, for example, a view (named testview) that brings together these data in the needed format with the following SQL commands in MySQL Workbench:

USE med_events;

CREATE VIEW `testview` AS 
SELECT patients.`id`, `date`, `category`, `duration`, `perday`
FROM event_date
JOIN event_info
ON event_info.`id` = event_date.`id`
JOIN event_patients
ON event_patients.`id` = event_info.`id`
JOIN patients
ON patients.`id` = event_patients.`patient_id`;