Documentation for Shiny app submission

[rpodcast]

A critical part of the pilot 2 submission is the documentation that covers how a reviewer can successfully install the app package and run it locally on their R installation. I have tried this once before with the Complex Innovative Designs (CID) initiative in partnership with FDA. Below is an excerpt from the repository I created for the particular project which we can adapt to our needs. (Note that the application reference in this template depended on key analytical libraries that are likely out of scope for our pilot submission)

## Documentation

This document outlines the general procedure for deploying and using the Shiny application. A separate document with complete instructions on accessing and downloading the contents of this repository will be supplied to all collaborators on this project.

Pre-requisites

The following pre-requisites must be fulfilled in order to access and use the application:

Compute Environment

The application is construction with the R statistical computing language (version 3.6.0), and the Shiny package is used to create the application's web interface. Since the application utilizes more R packages besides Shiny, the {packrat} package dependency manager is utilized such that the same package versions will be deployed once the source code is cloned from the GitHub repository. Here are the additional software requirements:

Git

The Git version control system is required to clone the source code for the application. For details on installing Git for different computer operating systems, refer to the install Git chapter of Jenny Bryan's Happy Git and GitHub for the useR online book. This book also contains a comprehensive overview of configuring RStudio to use Git and online repositories such as GitHub and GitLab.

JAGS

JAGS (Just Another Gibbs Sampler) version 4.3.0 is required for the {rjags} R package. Here are installation notes based on the computing environment's operating system:

• Windows Installation: Download and install JAGS-4.3.0.exe from the JAGS SourceForge file repository.
• Linux Installation: Use your distributions package manager to install JAGS. Here are the most common package names based on the Linux distribution:
  • Debian/Ubuntu: Execute sudo apt-get install jags
  • Red Hat Enterprise Linux/CentOS: Create a file called `/etc/yum.repos.d/jags.repo with the below contents:

[home_cornell_vrdc]
name=Sundry packages for scientific computing (CentOS_7)
type=rpm-md
baseurl=http://download.opensuse.org/repositories/home:/cornell_vrdc/CentOS_7/
gpgcheck=1
gpgkey=http://download.opensuse.org/repositories/home:/cornell_vrdc/CentOS_7//repodata/repomd.xml.key
enabled=1

Then execute the following commands:

sudo yum update
sudo yum install jags4-devel 

ZeroMQ

The ZeroMQ library is required by {clustermq} to perform simulations on a High-Performance Computing (HPC) cluster. For computing environments using Windows, no additional software is required as the binary is included with the dependency package rzmq. For computing environments using Linux, the following system packages associated with ZeroMQ must be installed depending on the Linux distribution:

• Debian/Ubuntu: libzmq3-dev
• Red Hat Enterprise Linux/CentOS: yum install -y epel-release && yum install -y zeromq-devel

RStudio

It is highly recommended that the RStudio IDE also be installed, as RStudio comes with additional functionality that enhances the experience of using R. Please refer to the linked download page for installation instructions.

Shiny Server

If it is desired for multiple users to access the application via a web link instead of running it directly on their computers, it is recommended to deploy the application on RStudio's Shiny Server product. An open-source version of Shiny server can be install for free on any server running Ubuntu, Red Hat Enterprise Linux, CentOS, or SUSE Enterprise Linux. It is recommended that the server is running on 64-bit hardware. Complete documentation on installing and administering Shiny Server can be found on the Administrator's Guide.

Installation

This application has been constructed as an R package via the {golem} package. In addition, the dependencies of the application are tracked in this repository via the {packrat} dependency management system. Here are installation instructions tailored to different methods of interacting with the application:

Local system installation

You can interact with this application within a local R session. It is recommended to use the RStudio interactive development environment (IDE) to execute the application. Assuming the source code of this repository has been cloned to a local directory per the instructions outlined in the Source code access section, here are instructions for running the application on a local installation:

1. Launch RStudio and open the project file by choosing File -> Open Project in the RStudio menu and navigating to the directory of the cloned repository files. Open the pmp_cid_app.Rproj file.
2. Execute the following command in the R console: packrat::restore(). You should see a dialog confirming the installation of the package dependencies to the local packrat library. Confirm by typing Y at the R prompt. The package installation may take some time to complete depending on your internet connection speed. Note that this step only needs to be performed once, since the packages will be available for any future RStudio sessions using this project. You may see warning messages after the procedure completes that reference unused arguments in a tar command. These warnings can be safely disregarded.
3. Restart the R session by selecting Session -> Restart R in RStudio.
4. Execute the application by opening the app.R script in RStudio and clicking the Run App button. Note that if the equations in the first portion of the interface do not render correctly in the default RStudio viewer, you may need to chose the option of running the application in an external browser window. It is recommended to use Google Chrome as the browser.

Installation on Shiny Server

Pre-requisites

The server hosting the Shiny Server platform must be running R version 3.6.0 and have the {packrat} R package installed on the default R library for the server. For complete details on administering Shiny Server, please refer to the Administrator's Guide.

Installation Procedure

To deploy this application, the server administrator will need to follow this procedure:

1. Clone the application's repository to any local directory that is outside of the Shiny Server's application source directory. Refer to the separate document for instructions on cloning the repository.
2. Launch R in the same directory with the clone of the repository. Once R completes initialization, a message should appear that this is a packrat-enabled project.
3. Create a bundle of the application by executing this R command: packrat::bundle(). After some time, a new file called pmp_cid_app.tar.gz should be present in the same directory. Once complete, exit R.
4. Launch a new R session on the Shiny server. In this R session, run the following command: packrat::unbundle("/path/to/pmp_cid_app.tar.gz", "/path/to/application_directory") where /path/to/application_directory is the app_dir configured for Shiny Server.
5. In the same R session, change the working directory to the new location above: setwd("/path/to/application_directory/pmp_cid_app")
6. Run the following command to re-enable packrat for the project: packrat::on().

[michaelmayer2]

Happy to work on this with you. I think there already is really good content. Still new to the WG but not new to the submission business.

[NNaikp]

I would also be happy to help if needed 😃
@rpodcast do you think there will be much technical information needed in addition to what is already added in the ADRG from pilot 1?

Since the app will be in a package my initial thought was to ask the reviewer to unpack using pkglite. Load the package and run a function that has runApp() wrapped.

After that it would be the data upload and app navigation/features that would take up space.

[jwildfire]

@rpodcast I'm happy to help as well. Package-based approach makes sense to me. Seems like installation and usage should be very straight-forward if we just put the study data in the \data folder and then reference it directly in the app.