17.4 Parameterized reports

In Section 17.3, we mentioned one way to render a series of reports in a for-loop. In fact, rmarkdown::render() has an argument named params specifically designed for this task. You can parameterize your report through this argument. When you specify parameters for a report, you can use the variable params in your report. For example, if you call:

  1. for (state in state.name) {
  2.   rmarkdown::render('input.Rmd', params = list(state = state))
  3. }

then in input.Rmd, the object params will be a list that contains the state variable:

  1. ---
  2. title: "A report for `r params$state`"
  3. output: html_document
  4. ---
  6. The area of `r params$state` is
  7. `r state.area[state.name == params$state]`
  8. square miles.

Another way to specify parameters for a report is to use the YAML field params, e.g.,

  1. ---
  2. title: Parameterized reports
  3. output: html_document
  4. params:
  5.   state: Nebraska
  6.   year: 2019
  7.   midwest: true
  8. ---

Note that you can include as many parameters in the params YAML field or the params argument of rmarkdown::render(). If both the YAML field and the argument are present, the parameter values in the argument will override the corresponding parameters in YAML. For example, when we call rmarkdown::render(..., params = list(state = 'Iowa', year = 2018) on the previous example that has the params field, params$state will become Iowa (instead of Nebraska) and params$year will become 2018 (instead of 2019) in the R Markdown document.

When rendering the same R Markdown document to a series of reports, you need to adjust the output_file argument of rmarkdown::render(), to make sure each report has its unique filename. Otherwise, you will accidentally override certain report files. For example, you can write a function to generate a report for each state and each year:

  1. render_one <- function(state, year) {
  2.   # assuming the output format of input.Rmd is PDF
  3.   rmarkdown::render(
  4.     'input.Rmd',
  5.     output_file = paste0(state, '-', year, '.pdf'),
  6.     params = list(state = state, year = year),
  7.     envir = parent.frame()
  8.   )
  9. }

Then you can use nested for-loops to generate all reports:

  1. for (state in state.name) {
  2.   for (year in 2000:2020) {
  3.     render_one(state, year)
  4.   }
  5. }

At the end, you will get a series of report files like Alabama-2000.pdf, Alabama-2001.pdf, …, Wyoming-2019.pdf, and Wyoming-2020.pdf.

For parameterized reports, you can also input parameters interactively through a graphical user interface (GUI) created from Shiny. This requires you to provide a params field in YAML, and rmarkdown will automatically create the GUI using the appropriate input widgets for each parameter (e.g., a checkbox will be provided for a Boolean parameter).

To start the GUI, you can call rmarkdown::render() with params = 'ask' if you do not use RStudio:

  1. rmarkdown::render("input.Rmd", params = "ask")

If you use RStudio, you can click the menu Knit with Parameters behind the Knit button. Figure 17.1 shows an example GUI for parameters.

Knit an R Markdown document with parameters that you can input from a GUI.

FIGURE 17.1: Knit an R Markdown document with parameters that you can input from a GUI.

For more information on parameterized reports, you may read Chapter 15 of the R Markdown Definitive Guide (Xie, Allaire, and Grolemund 2018).

References

Xie, Yihui, J. J. Allaire, and Garrett Grolemund. 2018. R Markdown: The Definitive Guide. Boca Raton, Florida: Chapman; Hall/CRC. https://bookdown.org/yihui/rmarkdown.