Vignette (v1): Shiny User Guide
The safetyGraphics Shiny app provides an easy-to-use point-and-click interface to create shareable safety graphics for any study.
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()
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)
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.
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.
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.
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.
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.
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 data must have one record per participant per timepoint per lab test. That is, the data should be long, not wide.
- The data must have columns for:
- Unique Subject Identifier (ID Column)
- Name of Measure or Test (Measure Column)
- Numeric finding or result (Value Column)
- Numeric upper limit of normal for the test
- Numeric lower limit of normal for the test
- Numeric study day
- The following values must be present in the column corresponding to Measure or Test:
- Aminotransferase, alanine (ALT)
- Aminotransferase, aspartate (AST)
- Alkaline phosphatase (ALP)
- Total Bilirubin
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.
Paste the following code into RStudio:
#Code to initialize shiny application
install.packages("safetyGraphics")
library("safetyGraphics")
safetyGraphicsApp()
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.
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.
Now that we've got the data mapping complete, just select "Hepatic Explorer" from the Chart tab drop-down.
The chart has lots of useful interactive features built in, but we'll cover those in a separate vignette.
To export the chart, click the Reports Tab, make sure that the Hepatic Explorer has a check by it, and click the "Export Chart(s)" button. Your chart, along with the other valid charts, will be saved in an .html file and downloaded to your machine.
Open the downloaded file in a new tab in your browser and you'll see tabs for each of the charts and an "Info" tab. The Hepatic Explorer tab will be identical to the chart shown above, with all of your customizations intact. The "Info" tab, shown below, has a brief description of the safetyGraphics package and source code that you can use to recreate the charts in R.
The html file contains all of the data and code for the charts and is easy to share. Just send the file to the person you're sharing with, and tell them to open it in their web browser (just double-click the file) - they don't even need R.
This case study shows how to create a shareable chart created using custom settings in just a few clicks. Continue reading to find out how to add customizations to your chart.
Only the most basic settings used by the safetyGraphics displays are populated by default, but users can also add a wide variety of additional customization. We'll walk through a few common customizations for the Hepatic Explorer chart in this case study including:
- Adding grouping variables
- Adding filter variables
- Defining which rows should be included in the analyses using the Analysis Flag options
- Defining the baseline measurement using the Baseline options
Just paste this code in to RStudio:
#Code to initialize shiny application
install.packages("safetyGraphics")
library("safetyGraphics")
safetyGraphicsApp()
We'll use the pre-loaded example data for this case study, so there is no need to load your own data file.
The SafetyGraphics Hepatic Explorer chart offers native support for data-driven groups and filtering. Any data column can be used to add filter and grouping controls to the chart. One common use case is to add grouping by treatment arm and filtering by site, race and sex. All of this can be done with just a few clicks. As you might have guessed, you just update the "Filter columns" and "Group columns" inputs as shown:
Select "Hepatic Explorer" from the Charts drop-down tab to see the following chart (with orange boxes added around the newly created filters and groups for emphasis):
A word of warning - both grouping and filtering work best using categorical variables with a relatively small number of groups (less than 10 or so). With that said, there is no official limit on the number of unique values to include in a group or filter, so if you followed the example above but chose "AGE" (with over a dozen unique integer values) instead of "AGEGR1" (with 3 categorical levels), you might not love the functionality in the chart. Fortunately, it's easy to go back and update the chart to use the categorized variable instead - just go back to the settings tab and update the corresponding setting.
You can also use the settings page to identify important values in the data. For the Hepatic Explorer chart, you can flag baseline values (using the "Baseline column" and "Baseline values" inputs) and values included in the analysis population (using "Analysis Flag column" and "Analysis Flag values" inputs). In both cases, you need to choose the "column" first, and then choose 1 or more corresponding "values". Here are some suggested settings using our sample data:
In the Hepatic Explorer chart, adding a baseline flag enables the users to view a baseline-adjusted version of the chart. Click the chart tab, and then change the "Display Type" control to "Baseline Adjusted (mDish)".
We're following ADaM conventions and using "flag" columns ending in "FL" and "Y" values for the configuration here, but any column/value combination is allowed. For example, you could use study day 0 to define baseline by setting baseline column to "ADY" and baseline value to "0".
This case study shows how to add some basic customizations to your Hepatic Explorer chart with a few clicks in the shiny application. Note that not all customizations are available in the shiny app. You can access more granular settings by looking at the documentation for the underlying hep-explorer github repo javascript library.