10 Parameterized R Markdown

10.1 Getting Started

R Markdown documents are used as the basis for many types of data products. One variation on the traditional R Markdown document is the Parameterized Report. Parameterized reports let you customize the content of a document without duplicating work. This can be handy in situations where a document template would be preferable to the creation of many individualized reports. For example, you might want to customize a report template to send weekly emails to different departments, or change inputs to create versions of an ETL process. A general overview of Parameterized R Markdown is available as a lesson on the R Markdown Website.

10.1.1 Defining Parameters

To create a parameterized report, declare parameters in the params section of the R Markdown YAML header:

title: Visualizing the Ocean Floor
output: html_document
    data: "hawaii"

In this example, the params field creates a placeholder variable called data and assigns the default value of “hawaii”.

Parameters can be customized to impose constraints or controls on accepted input values. These specifications can be listed as sub-items within the parameter YAML section:

title: My Document
output: html_document
    label: "Number of Previous Days"
    value: 90
    input: slider
    min: 30
    max: 360
    label: "Region:"
    value: Europe
    input: select
    choices: [North America, Europe, Asia, Africa]

This params field defines two parameters, days, which provides a slider input widget with limits on the minimum and maximum values, and region, which is a selector widget with four predefined options to choose from.

Example Parameter Control Widgets

Refer to Chapter 15 of R Markdown: The Definitive Guide for more information on custom parameter input types and controls.

10.1.2 Using Parameters

Parameterized reports can be developed and tested in the RStudio IDE before publishing to RStudio Connect. To access a parameter in code, call params$<parameter name>. Parameters can be referenced in document code chunks or inline code statements:

RStudio IDE Report Development

This example is explored in further detail as a lesson on the R Markdown Website.

10.2 Publishing to RStudio Connect

Publishing parameterized reports to RStudio Connect is identical to publishing regular R Markdown documents in source form. See sections 3 and 3.4.2 for more information on that process.

Once published, an INPUT sidebar will become available in the RStudio Connect dashboard.

Input Sidebar and Panel

Click on the input sidebar to update the parameters and re-run the report.

The default configuration of RStudio Connect will not allow viewers to edit input parameters or run a report if they have not been granted access permissions to do so. The input panel will still be accessible, but the parameter input fields will not be displayed:

Access Denied

The Applications.ViewerOnDemandReports and Applications.ViewerCustomizedReports configuration settings can alter the permissibility of viewer actions on reports. See the RStudio Connect Admin Guide for more information.

10.3 Saved Variants

Document publishers and collaborators can create saved variants of the published report by setting and saving desired parameters.

Saving Variants

The visibility of saved variants can be set to Personal (Only you) or Shared (Everyone with access to the document). In the example above, several Personal variants of the default report have been created so that a user could quickly navigate between the generated output of four sets of parameters.

Each saved variant can be executed on a schedule and will have a separate rendering history associated with it. See sections 6 and 7 for more information. For information on how to set up a custom email distribution for a saved variant, see section 6.4.

10.4 Tracking Visits

Connect tracks information about visits to R Markdown documents that tell you which documents have been seen, when and by whom. The same information is recorded for parameterized R Markdown documents, other rendered types and static content. Visit information is available via an API that may be called by administrators and publishers. Publishers may only retrieve information about content they own.

Learn about the recorded data in the Rendered and Static Content Visit Events section of the RStudio Connect Admin Guide.

Code examples showing how to access this data are in the User Activity API cookbook recipes. The Connect Server API Reference documents each of the Instrumentation APIs used by the recipes.