17.4 Parameterized reports
In Section17.3, we mentioned one way to render a series of reports in afor-loop. In fact,rmarkdown::render() has an argument namedparams specifically designed for this task. You can parameterize your report through this argument. When you specify parameters for a report, you can use the variableparams in your report. For example, if you call:
for (statein state.name) { rmarkdown::render('input.Rmd',params =list(state = state))}then ininput.Rmd, the objectparams will be a list that contains thestate 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 fieldparams, e.g.,
---title: Parameterized reportsoutput: html_documentparams:state: Nebraskayear:2019midwest:true---Note that you can include as many parameters in theparams YAML field or theparams argument ofrmarkdown::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 callrmarkdown::render(..., params = list(state = 'Iowa', year = 2018) on the previous example that has theparams field,params$state will becomeIowa (instead ofNebraska) andparams$year will become2018 (instead of2019) in the R Markdown document.
When rendering the same R Markdown document to a series of reports, you need to adjust theoutput_file argument ofrmarkdown::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 nestedfor-loops to generate all reports:
for (statein state.name) {for (yearin2000:2020) {render_one(state, year) }}At the end, you will get a series of report files likeAlabama-2000.pdf,Alabama-2001.pdf, …,Wyoming-2019.pdf, andWyoming-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 aparams field in YAML, andrmarkdown 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 callrmarkdown::render() withparams = 'ask' if you do not use RStudio:
rmarkdown::render("input.Rmd",params ="ask")If you use RStudio, you can click the menuKnit with Parameters behind theKnit button. Figure17.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 readChapter 15 of theR Markdown Definitive Guide(Xie, Allaire, and Grolemund 2018).