safetyGraphics Shiny App - User Guide

Jeremy Wildfire

2019-06-14

Overview

The safetyGraphics Shiny app provides an easy-to-use point-and-click interface to create shareable safety graphics for any study.

Starting the Shiny App

After opening RStudio and making sure you are running R version 3.5 or higher, the application can be started with just a few lines of code. In general, you’ll want to load the latest stable release from CRAN:

install.packages("safetyGraphics")
library("safetyGraphics")
safetyGraphicsApp()

To load the latest development release from GitHub with devtools:

install.packages("devtools")
library("devtools")
devtools::install_github("SafetyGraphics/safetyGraphics")
library("safetyGraphics")
safetyGraphicsApp()

Loading Large Files

By default, Shiny only allows users to load files smaller than 5mb. If you want to load a larger file, use the maxFileSize setting when calling the app:

safetyGraphicsApp(maxFileSize = 100)

Typical Workflow

After opening the app, you will typically follow the workflow below. In short, you will load data (once), tweak settings and view charts (maybe more than once), and then export a snapshot of the charts for other users.

This workflow lines up with the items in the toolbar for the App.

More information about each step in the process is shown below.

Load Data

When you open the app, you are taken to the Home Tab which contains some general information about the app and links to helpful documentation. Click on the Data Tab and you should see the “Data Upload” and “Data Preview” panels. The preview for the pre-loaded “Example data” dataset is shown by default.

To load your own data, simply click the browse button and select a .csv or .sas7bdat data set. Once the file is loaded, select it in the list at the bottom of the “Data Upload Panel”. Once selected, the “Data Preview” panel will update automatically (along with the Settings, Charts, and Reports tabs).

The charts in the safetyGraphics app are specifically designed for clinical trial safety monitoring, and require laboratory datasets that contain one row per participant per time point per measure. Data mappings for two common CDISC data standards - SDTM and ADaM - are pre-loaded in the application. As described below, the app can automatically generate charts for data sets using these standards; other data sets require some user configuration.

Update Settings

After loading your data, navigate to the Settings tab to customize the behavior of the charts. This tab includes a Charts panel for selecting the charts you want to visualize and other panels for different types of chart settings. For example, the “Data Mappings” panel (shown below for the “Example Data” ADaM data set) can be used to specify the column that contains the unique subject ID, and on the more general “Appearance Settings” panel, there is an option to specify a warning message to be displayed when the chart loads. You can hover the mouse over any setting label to get more details. The small numbers to the right of the settings labels indicate the number of charts that use the relevant setting. Mousing over them presents a list of these charts.

When possible, items on the settings tab are pre-populated based on the data standard of the selected data set. If a SAS data set with labels is provided, the relevant column labels will appear within brackets [] next to their variable names. You can see this in the Data Mappings screenshot above. See the Case Studies below for more details regarding working with non-standard data and adding customizations to the charts.

View Chart

Once the settings configuration is complete, click on the Charts tab to view a drop-down of the available charts. A green check will display by charts that are ready to be visualized and a red X will indicate that settings need to be changed in order to render the chart. Simply click one of the options to view it. The chart tab updates automatically when settings are changed or new data is loaded. More details about chart functionality will be documented in separate vignettes.

Export Results

Navigate to the Reports tab to choose reports for export and click the “Export Chart(s)” button at the bottom to create a standalone copy of the charts using the current configuration. The export functionality combines the data, code, and settings for the charts in to a single file. In addition to the charts themselves, the export includes a summary of the tool, and code to recreate the customized charts in R.

Case Study #1 - Mapping Non-Standard data

Overview

When a new data file is loaded, the app will detect whether the dataset is formatted according to ADaM or SDTM data standards. If the uploaded dataset matches one of these standards, the settings tab will be pre-populated accordingly, and little or no custom user customization will be needed to generate a basic chart. However, no data standard is strictly required; the app also works with data in other formats. The specific data columns required varies between charts. For example, the only firm data requirements for the Hepatic Explorer chart are:

The app also supports data sets that partially match the pre-loaded data standards. The step-by-step instructions below outline how to create a chart for one such data set.

Step-by-step

1. Open the App

Paste the following code into RStudio:

#Code to initialize shiny application
install.packages("safetyGraphics")
library("safetyGraphics")
safetyGraphicsApp()

2. Load Data

Use the “Browse..” button on the data upload section of the data tab to load a non-standard data set. We’ll use the .csv saved here, but the process is similar for other data sets. Notice that once the data is loaded, the app will detect whether the data matches one of those pre-loaded standards, and a note is added to indicate whether a match is found. Our sample data is a partial match for the SDTM standard. Once you select the newly loaded data set, the app should look like the screen capture below. Click on the Charts tab and note the red X’s in the drop-down indicating that user customization is needed.

3. Select Columns

Next, click the “Settings” tab in the nav bar at the top of the page. The page should look something like this:

Behind the scenes, a validation process is run to check if the selected settings match up with the selected data set to create a valid chart. Green (for valid) and red (for invalid) status messages are shown after each label in the Settings tab - you can hover the mouse over the status to get more details.

As you can see, we’ve got several invalid settings with red status messages. We now need to go through and update each invalid setting and turn its status icon into a green check. Once all of the individual settings are valid, the red Xs in the Charts drop-down will turn to green checks, and the chart will be created. Let’s hover over the red X by the Measure Column Setting to see the detailed description of the failed check:

As you might’ve guessed from the empty select box, the check failed because no value is specified for the setting. Choosing the measure column is simple. Click the select box to see pre-populated options corresponding to the columns in the data.

Now select ID for the ID column, LBTEST for the Measure Column, and LBDY for the Study Day Column option. Your setting page should look something like this:

Now we need to fill in the 4 inputs beneath Measure Column. You may have noticed that there were no options available for these inputs when the page loaded. This is because these options are field level data that depend on the Measure Column option. Once you selected a Measure Column, the options for these inputs were populated using the unique values found in that data column. To fill them in, just type the first few letters of the lab measure in the text box. For example, type “Alan” for the Alanine Aminotransferase value input and select the correct option.

Repeat the process for the other 3 “value” inputs and viola, the red X changes to a green check, and the Hepatic Explorer chart is ready.