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:
for (state in state.name) {
rmarkdown::render('input.Rmd', params = list(state = state))
}
then in input.Rmd
, the object params
will be a list that contains the state
variable:
---
title: "A report for `r params$state`"
output: html_document
---
The area of `r params$state` is
`r state.area[state.name == params$state]`
square miles.
Another way to specify parameters for a report is to use the YAML field params
, e.g.,
---
title: Parameterized reports
output: html_document
params:
state: Nebraska
year: 2019
midwest: true
---
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:
render_one <- function(state, year) {
# assuming the output format of input.Rmd is PDF
rmarkdown::render(
'input.Rmd',
output_file = paste0(state, '-', year, '.pdf'),
params = list(state = state, year = year),
envir = parent.frame()
)
}
Then you can use nested for
-loops to generate all reports:
for (state in state.name) {
for (year in 2000:2020) {
render_one(state, year)
}
}
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:
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.
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.