Easing access to R using 'shiny' to create graphical user interfaces:
An example for the R package 'Luminescence'

Christoph Burow1, Sebastian Kreutzer2, Michael Dietze3, Margret C. Fuchs4, Christoph Schmidt5, Manfred Fischer5, Helmut Brückner1

Abstract

Since the release of the R package 'Luminescence' (Kreutzer et al., 2012) the functionality of the package has been greatly enhanced by implementing further functions for measurement data processing, statistical analysis and graphical output. Despite its capabilities for complex and non-standard analysis of luminescence data, working with the command-line interface (CLI) of R can be tedious at best and overwhelming at worst, especially for users without experience in programming languages. Even though much work is put into simplifying the usage of the package to continuously lower the entry threshold, at least basic knowledge of R will always be required. Thus, the potential user base of the package cannot be exhausted, at least as long as the CLI is the only means of utilising the 'Luminescence' package.
But even experienced users may find it tedious to iteratively run a function until a satisfying results is produced. For example, plotting data is also at least partly subject to personal aesthetic tastes in accordance with the information it is supposed to convey and iterating through all the possible options in the R CLI can be a time-consuming task. An alternative approach to the CLI is the graphical user interface (GUI), which allows direct, interactive manipulation and interaction with the underlying software. For users with little or no experience with command-lines a GUI offers intuitive access that counteracts the perceived steep learning curve of a CLI. Even though R lacks native support for GUI functions, its capabilities of linking it to other programming languages allows to utilise external frameworks to build graphical user interfaces. A recent attempt to provide a GUI toolkit for R was the introduction of the 'shiny' package (Chang et al., 2016), which allows automatic construction of HTML, CSS and JavaScript based user interfaces straight from R.
Here, we give (1) a brief introduction to the 'shiny' framework for R, before we (2) present a GUI for the R package 'Luminescence' in the form of interactive web applications. These applications can be accessed online so that a user is not even required to have a local installation of R and which provide access to most of the plotting functions of the R package 'Luminescence'. These functionalities will be demonstrated live during the PICO session.

Affiliations

University of Cologne, Institute of Geography, Department of Geosciences, Cologne, Germany (christoph.burow@uni-koeln.de)
IRAMAT-CRP2A, Université Bordeaux Montaigne, Maison d'Archéologie, Esplanades des Antilles, 33607 Pessac Cedex, France
Section 5.1: Geomorphology, Helmholtz Centre Potsdam, GFZ German Research Centre for Geosciences, Potsdam, Germany
Helmholtz-Zentrum Dresden-Rossendorf, Helmholtz-Institut Freiberg for Resource Technology, Freiberg, Germany
Chair of Geomorphology, University of Bayreuth, Bayreuth, Germany

« Working with the command-line interface (CLI) of R can be tedious at best and overwhelming at worst. »

An anonymous userR

Expectation

Reality

« For users with little or no experience with command-lines (CLI) a graphical user interface (GUI) offers intuitive access that counteracts the perceived steep learning curve of a CLI »

Burow et al. (2016)

  Creating a plot: a common task in R

Consider the following situation:
You, as a scientist, are facing the task to visualise your data in a more complex chart using R. Let us further assume that someone else already provided a custom R function that produces this kind of non-standard plot (here: plot_AbanicoPlot()). The desired plot may look like the one below.

Naturally, to complete the task you would fire up the R command-line and start hacking away. Assuming we have the data already in place, the essential part is is the call of the specific plotting function. For the plot to look like it does right now the user would be required to write the R code below. To be fair, some or even most of the arguments do not to be explicitly specified if their default values are sufficient. But there is still an overwhelming number of arguments that need to be recognized and used to make the plot appear exactly as seen on the left-hand side.

Alternatively, you could be provided a graphical user interface with input widgets that control the numerous arguments of this particular function. You would no longer be required to look up all the arguments and their required input type and/or structure.

To be fair, this is of course only a small subset of input widgets required to control all the options listed in the CLI code. But for a user new to R we could safely assume that a GUI is the much more comfortable alternative.
In the next section The 'shiny' framework you will learn more about the basic structure of a shiny application, the different input widgets and how to share the applications with others.

Hello Shiny!

Input Widgets

This is a non-exhaustive collection of input widgets available in the shiny framework. Most of the widgets here are bound to a parameter of the plot on the right-hand side. Feel free to test them all and observe its effect on the plot. You can also check the R console output to see the value returned by each widget.

Action button

Checkbox

Checkbox group

Date input

Date range

to

File input

Numeric input

Radio buttons

Select box

Slider

Slider range

Text input

Action button

                          

                        

                        

                          
Checkbox

                          

                            

                          

                        

                        

                          
Checkbox group

                          

                            

                          

                        

                        

                          
Date input

                          

                            

                          

                        

                        

                          
Date range

                          

                            

                          

                        

                        

                          
File input

                          

                            

                          

                        

                        

                          
Numeric input

                          

                            

                          

                        

                        

                          
Radio buttons

                          

                            

                          

                        

                        

                          
Select box

                          

                            

                          

                        

                        

                          
Slider

                          

                            

                          

                        

                        

                          
Slider range

                          

                            

                          

                        

                        

                          
textInput

                          

                            

                          

                        

                      

                    

                  

                

              

            

          

          

            

              

                

                  

                    

                      
                    

                    

                      

                        

                        
« Sharing shiny applications is simple! »

                        
Another anonymous userR

                        

                      

                    

                  

                  

                    

                      
                      

                        

                          
The easist and fastest way to share your self-written shiny applications
                                          is by using the commercial service Shinyapps.io by RStudio. 
                                          On this self-service platform users can upload, run and share their shiny
                                          applications. The service offers different subscription plans depending
                                          on the desired number of allowed applications, service availability and
                                          feature content. A free subscription is also available.

                          
                        

                        

                          
If you do not want to rely on a third-party service to host your shiny
                                          applications there is also the option to host your own instance of 
                                          Shiny-Server. Naturally, apart from the software itself, which is
                                          also available in an open-source version, a server or suitable webspace
                                          is required beforehand. While setting up a server yourself requires more
                                          preparation, knowledge and potentially costs, the benefit of having full
                                          control over the service can very well be justified.

                          
                        

                        

                          
Running shiny applications as a service over the internet is not a must, it is always possible
                                          to run any shiny application locally on any computer with a working instance
                                          of R and RStudio. Shiny applications can also be included in R packages (like in RLumShiny), which
                                          can be downloaded e.g. from GitHub or, of course, from CRAN. Running a shiny application
                                          on your local computer does require a HTML5 compliant webbrowser, but no internet connection!

                          
                        

                      

                    

                  

                

              

            

          

          

            

              

                

                  

                    

                      
                    

                    

                      

                        

                        
« R allows the creation of complex and transparent data analysis routines for experimental protocols that are not available in existing software. »

                        
Kreutzer et al. (2012)

                        

                      

                    

                  

                  

                    

                      

                        
Why?

                        

                          
                        

                      

                      

                        

                      For routine luminescence dating applications the commonly used [measurement devices] 
                      are bundled with analysis software, such as Viewer or Analyst. These software 
                      solutions are appropriate for most of the regular dating and publication jobs, 
                      and enable assessment of luminescence characteristics and provide basic statistical 
                      data treatment. However, for further statistical analysis and data treatments, 
                      this software may reach its limits. In such cases, open programming languages 
                      are a more appropriate approach.
                      
modified after Kreutzer et al. (2012)

                      

                      

                    

                  

                  

                    

                      
                      

                        

                          
Reference: Duller 2015

                          
                        

                        

                          
Reference: Duller 2015

                          
                        

                        

                          
Reference: Duller 2015

                          
                        

                        

                          
Reference: Olley & Reed 2003

                          
                        

                        

                          
Reference: Vermeesch 2009

                          
                        

                      

                    

                  

                

              

            

          

          

            

              

                

                  
A potpourri of functions

                  

                    
                  

                

                

                  
Since its release in 2012 the functionality of the R package Luminescence drastically increased.
                              What started with a handful of functions to apply a very specific type of signal
                              analysis and to plot the data is now a collection of >100 functions for all sorts
                              of (non-)specialised tasks.

                  

                

              

            

            

              

                

                  
Current content of Luminescence (v0.8.0)

                

                

                  

                

              

            

          

          

            

              

                

                  
Statistics

                  

                    
                  

                

                

                  
It is generally hard to measure and keep track of the distribution and reception of
                              the R package Luminescence (or RLumShiny). The official CRAN download statistics,
                              however, may provide at least some indication on how many and where people are using
                              our package. The data you see on the right-hand side are generated from the raw CRAN logs.

                  

                    
                    

                      

                        
                      

                      

                        
                      

                    

                  

                  

                    
                    

                      

                        
                      

                      

                        
                      

                      

                        
                      

                      

                        
                      

                      

                        
                      

                    

                  

                

              

            

            

              

                

                  

                    
                  

                

                

                  

                

              

            

          

          

            

              

                

                  

                    

                      
Motivation

                      

                        
                      

                    

                    

                      
The general motivations have already been outlined in the introduction.
                                    In short, using the R command-line can be tedious, even if your
                                    experienced in R. If you are new to R and only want to quickly
                                    produce a plot, the initial experience can be overwhelming. 


                                    In the context of the R package Luminescence over the time we learned
                                    that many colleagues were struggling 
                                    to get started with the package. While writing tutorials and manuals helped
                                    to ease the access to the package, it still takes a certain amount of dedication
                                    to learn the basic functionality of the package. Quite understandably many colleagues
                                    do not feel like having to learn basic R programming first only to use a very small
                                    subset of functions provided by the package. By providing a GUI to at least some
                                    of the more basic and/or 'popular' functions of the Luminescence package
                                    we can are able to practically remove these restrictions and make both R and
                                    the Luminescence more accessible to our colleagues.

                    

                  

                

              

              

                

                  

                    
                    

                      

                        
Shiny applications available in the R package RLumShiny (v0.1.1). 
                                                           Each application can be started using the function app_RLum() with a 
                                                           corresponding keyword as input for the parameter app
                                                           (e.g., app_RLum(app = 'abanico')). All functions are part of the Luminescence package.
                                                          See the 'Examples' section to test some of the listed applications yourself!

                        

                      

                      

                        
Functions in the R package RLumShiny (v0.1.1). The main function is app_RLum(), which must be used to start
                                                any of the applications given in the other table. All other functions are used internally and extend the functionality of the shiny
                                                package (see 'Extending shiny' section).

                        

                      

                    

                  

                

              

            

          

          

            

              

                

                  

                    

                      
                    

                    

                      

                        

                        
« [...] 'shiny' is based on 
                                                  modern programming and markup languages, which allows
                                                  easy integration of existing JavaScript libraries, thus greatly
                                                  increasing the capabilities of 'shiny' and R itself. »

                        
Burow et al. (2016)

                        

                      

                    

                  

                  

                    

                      

                        
RLumShiny::jscolorInput()

                        

                          
                        

                      

                      

                        
jscolorInput(inputId, label, value, position = 'bottom',
                        color = 'transparent', mode = 'HSV', slider = TRUE, close = FALSE) 

The RLumShiny package includes the JavaScript library
                        jscolor (http://jscolor.com/) along with a function to
                        create a JSColor (Javascript/HTML Color Picker) widget to be used in shiny applications.

                        
 

                        
                        
                        

                        

                      

                    

                  

                  

                    

                      

                        
RLumShiny::popover()

                        

                          
                        

                      

                      

                        
popover(title, content, header = NULL, html = TRUE,
                          class = 'btn btn-default', placement = c('right', 'top', 'left',
                          'bottom'), trigger = c('click', 'hover', 'focus', 'manual')) 

Create a bootstrap button with popover, i.e. a small overlays of content for housing secondary information.

                        Click me!
                      

                    

                  

                  

                    

                      

                        
RLumShiny::tooltip()

                        

                          
                        

                      

                      

                        
tooltip(refId, text, attr = NULL, animation = TRUE, delay = 100, html = TRUE, placement = 'auto', trigger = 'hover') 

Create bootstrap tooltips for any HTML element to be used in shiny applications.

                        
                      

                    

                  

                

              

            

          

          

            

              

                
                

                  

                    
Application for: Luminescence::plot_AbanicoPlot()


                                The Abanico Plot is a combination of the classic Radial Plot and a kernel density estimate plot.
                                It allows straightforward visualisation of data precision, error scatter around
                                a user-defined central value and the combined distribution of the values, 
                                on the actual scale of the measured data (e.g. seconds, equivalent dose, years). 
                                The principle of the plot is shown in Galbraith & Green (1990).

                    

                  

                  

                    
Application for: Luminescence::plot_KDE()


                                Plot a kernel density estimate of measurement values in combination with the actual values
                                and associated error bars in ascending order. Optionally, statistical measures such as
                                mean, median, standard deviation, standard error and quartile range can be provided
                                visually and numerically.

                    

                  

                  

                    
Application for: Luminescence::calc_CosmicDoseRate()


                                This application calculates the cosmic dose rate taking into account the soft- and hard-component
                                of the cosmic ray flux and allows corrections for geomagnetic latitude, altitude above sea-level
                                and geomagnetic field changes.

                    

                  

                

              

            

          

          

            

              

                

                  

                    A collection of useful resources
                  

                

                

                  

                    

                      
                      

                        

                          

                            

                              
                                
QR Code
                                Link
                                Description
                              

                              
                                

                                  
                                    
                                  
                                  
                                    https://shiny.rstudio.com/gallery/
                                  
                                  
                                    
Gallery of example apps

                                  		
                                

                                

                                  
                                    
                                  
                                  
                                    https://shiny.rstudio.com/tutorial/
                                  
                                  Tutorial on how to build a Shiny app
                                

                                

                                  
                                    
                                  
                                  
                                    http://shiny.rstudio.com/images/shiny-cheatsheet.pdf
                                  
                                  A cheat sheet for building Shiny apps
                                

                                

                                  
                                    
                                  
                                  
                                    https://rstudio.github.io/shinydashboard/
                                  
                                  Building a shiny dashboard (like this presentation)
                                

                                

                                  
                                    
                                  
                                  
                                    https://www.rstudio.com/products/shiny/shiny-server/
                                  
                                  Shiny Server product information
                                

                              
                            

                          

                        

                        

                          

                            

                              
                                
QR Code
                                Link
                                Description
                              

                              
                                

                                  
                                    
                                  
                                  
                                    http://www.r-luminescence.de/
                                  
                                  
                                    
R.Luminescence project page

                                  		
                                

                                

                                  
                                    
                                  
                                  
                                    https://github.com/R-Lum/Luminescence
                                  
                                  GitHub repository of the R package 'Luminescence'
                                

                                

                                  
                                    
                                  
                                  
                                    http://www.r-luminescence.de/en/manuals_en.html
                                  
                                  Manuals for the R package 'Luminescence'
                                

                              
                            

                          

                        

                        

                          

                            

                              
                                
QR Code
                                Link
                                Description
                              

                              
                                

                                  
                                    
                                  
                                  
                                    https://github.com/tzerk/RLumShiny
                                  
                                  GitHub repository of the R package 'RLumShiny'
                                

                                

                                  
                                    
                                  
                                  
                                    http://www.ecu.edu/cs-cas/physics/ancient-timeline/upload/ATL_34-2_Burow_p22-32.pdf
                                  
                                  'Ancient TL' journal article
                                

                                

                                  
                                    
                                  
                                  
                                    http://rlum.geographie.uni-koeln.de
                                  
                                  Freely accessible Shiny Server of the Insitute of Geography (University of Cologne)
                                

                              
                            

                          

                        

                      

                    

                  

                  

                    

                      

                        
This presentation

                        

                          
                        

                      

                      

                        

                          The code of this presentation is freely available on
                          
                          GitHub
                        

                        
                        
                      

                    

                  

                

              

            

          

          

            

              

                

                  

                

              

            

          

        

        

          
Copyright © 2017 Christoph Burow |  This presentation is provided 'as is' without express or implied warranty.