Standards for Visual Appearance

Like all web-based USGS applications, Shiny applications that will be publicly deployed to the web are required to follow the USGS visual identity standards template for web-based applications (fig. 2), which includes an approved USGS header and footer. This template is made available through the USGS Office of Communication and Publishing (OCAP) Digital Services, and users should check for updates before publication of web applications.

Not all components of the template are required (for example, the search bar and social media links can be hidden). However, the USGS logo and footer links must be present. Additionally, the header and footer should stretch across the full width of the page.

Although there are several ways to apply the visual identity template in Shiny applications, one straightforward approach is to save the header and footer templates as HTML documents in the Shiny application’s “www” folder. Then, they can be included in the application by calling them from the user interface (UI) script. Here is an example:

# header absolutePanel( tags$head(tags$style( includeHTML("www/header.html") ))

If the application is being distributed as an R package (R project for Statistical Computing; https://www.r-project.org/), the HTML documents can be saved in the “inst” folder and called using the system.file() and htmlTemplate() functions.

Disclaimers

All Shiny applications made available to the public must include the appropriate software disclaimer text (see the FSP—Guidance on Disclaimer Statements at https://www.usgs.gov/about/organization/science-support/office-science-quality-and-integrity/fundamental-science-5). The required text differs based on whether an application is provisional or approved, and scientific or non-scientific. Approved Scientific Software applications will need to include the disclaimer for Scientific Software:

However, while in the development stage (before approval and release), the preliminary language must be used:

The disclaimer text can easily be included on Shiny applications using one of the supported HTML tags. For example, the p() tag will add text directly to the page. There are also commands for including R markdown documents (includeMarkdown()) and text files (includeText()).

Deployment of Shiny Applications to the Web

There is no Bureau-wide standard for deployment of software over the web. However, multiple options exist for deploying and distributing Shiny applications.

For Shiny applications requiring public web access, USGS CHS has made available RStudio Connect/Posit, a cloud-based publishing platform for Shiny applications. Through this service, users may deploy Shiny applications to the web through RStudio desktop. Alternatively, applications may be deployed to RStudio Connect/Posit via USGS OpenSource GitLab, allowing direct deployment of approved Scientific Software applications. Users should note that, although RStudio Connect/Posit is a public-facing environment, applications deployed for public visibility must first be approved by following one of the established procedures outlined in this document. Licenses for RStudio Connect/Posit will be provisioned through USGS CHS and are available upon request.

When a public-facing website is not required, Shiny applications can be released as an R package on CRAN if the authoritative source code has first been released on USGS OpenSource GitLab. Shiny applications can also be configured to run from online sources. For example, Shiny applications can be deployed locally from a uniform resource locator (URL) if the target audience is able to use RStudio and install R packages on their computer. The Shiny package provides a command to download and run Shiny applications (distributed as a .zip file) from a downloadable web link: runURL(). This command will download and launch a Shiny application (stored as a .zip file) within RStudio on a user’s personal computer. Many R functions can also download data from a URL, which enables Shiny applications to draw from external data sources.

Testing

Make sure to thoroughly test the application to avoid last minute changes and hold ups. Remember that all changes performed after the administrative security review will require an additional security review. When possible, write unit tests for individual functions (see the section on testing in the USGS documentation at https://www.usgs.gov/products/software/software-management/testing-and-automation). Shiny applications may involve several dependencies between reactive objects in the R backend and user inputs on the user interface. For this reason, it is important to test that all HTML components (including action buttons, file menus, numeric input fields, and user uploads) respond and update correctly after user interaction. Shiny applications will frequently crash if reactive components and their dependencies are not properly defined in the server script.

Error Messages

Default Shiny error messages can be confusing and uninformative. Use the validate() and showNotification() functions to create helpful messages that allow the application to fail gracefully and warn the user in an informative way. Applications that include user input data, such as coordinates, can include validation steps to inform the user if input files are improperly formatted or outside the area of coverage.

Documentation

Documentation of source code is a required component of software development and must be included when developing Shiny applications as Scientific Software. Although documentation of source code is required to be present in the authoritative GitLab repository (see “Software Release Process for Shiny Applications”), authors of Shiny applications that will be deployed on a public website need to make online documentation available so that users can understand the science behind an application on the website. If an application is associated with another USGS product (for example, a journal article or data release), this online documentation is a good place to link to these associated resources.

One of the easiest ways to provide documentation is to include a help page as a separate tab in a Shiny application. For example, an HTML help file can be written in R Markdown and stored as an HTML page. The includeHTML() command can then place the help document on a tabPanel() in the application.

Versioned Updates to Shiny Applications

If the Shiny application requires updates after the approved release, changes can be made in a provisional software release if there are no substantial scientific changes. Such changes could include the addition of new data or new features to the application. Whether or not planned changes require the full review process is to be determined by the PI and their supervisor, with Science Center Director approval. As always, any changes to source code in the provisional release is subject to administrative security reviews.

The frequently asked questions on the USGS software management page provides additional detail on the different types of versioned updates. These include patches, minor revisions, and major revisions. Major revisions require a new IPDS approval record from the Science Center Director.The following is a suggested workflow for updating software: