Parameterised reports

Overview

Teaching: 20 min
Exercises: 40 min

Questions

• How can I run reports multiple times with different settings?

• How can I ensure my work is reproducible?

Objectives

• Set parameters to customise reports

• Rerun analyses with changed parameters to change the outputs

• Describe approaches to increase reproducibility of your work

We have now created an R Markdown document that can run our analysis and produce a report at the press of a button. If we were wanting to produce the same report on a different subset of the data (or on a different dataset altogether), we would need to go in and edit the document manually.

Instead, we can provide input parameters to the report that control how it is produced. We then set the parameters at the time we render the report, allowing us to customise the outputs each time.

Adding parameters

To include parameters, we add them to the header block:

---
params:
  param_name: param_value
---

This will set up a parameter called param_name, with a default value of param_value. To access the current value of a parameter, you can refer to it in code with params$param_name.

Parameterising your report

Add a parameter country with the default value Australia. Then change your data manipulation code chunk to refer to this value instead of being hard coded.

Save and Knit your document to check that it is still able to render correctly.

To make it clearer for the reader what we are working on, add a title to our plot showing the country we are working on. Also add a sentence in a text paragraph referencing it using an inline code block

Changing parameters

Now that we have a report template set up, we can start to create multiple documents that use the same analysis steps, but different inputs. To provide new values for the parameters that differ from the default value you defined, use the “Knit with Parameters…” option that can be found in the dropdown from the “Knit” button:

This will open up a new window that allows editing the parameters before rendering the document:

Using parameters

Knit your report after changing the parameter value to a different country.

What does the new rendered document look like? Where is it saved?

You will notice that our previously rendered document has been overwritten by our new report with different parameters. To take more control over how our document gets rendered, we can use rmarkdown::render().

rmarkdown::render() takes an input R markdown file and renders it, exactly as if we had used the “Knit” button. We can also control other parts of the rendering process with arguments, such as the output_file name, or the list of params to use.

rmarkdown::render(
  input = "Template_file.Rmd", 
  output_file = "Singapore.html", 
  params = list(country = "Singapore")
)

Any parameters not specified in the rmarkdown::render() function will use the default values from the R Markdown template.

Challenge

We are going to create two separate versions of our report. One version for drafting, which shows all our code for review. The other version will be a final ‘‘polished’ document, which shows only the results of our code.

• Add a new parameter to your document named draft with the default value TRUE.
• Modify your document so that when draft is TRUE, all your code is shown in the output, and none of the code is shown when draft is FALSE. Hint: You can use parameters inside your global chunk settings
• Use the “Knit with Parameters…” button with different parameters to check that your documents are being rendered as you expect.
• Create an Indonesia_draft.html and an Indonesia_final.html report using rmarkdown::render()

Solution

Your new parameter block should look like:

---
params:
  country: Australia
  draft: TRUE
---

To parameterise how the code chunks get dealt with, you can set the global options using params$draft at the start of the document:

```{r global_options}
knitr::opts_chunk$set(echo=params$draft, message=params$draft, warning=params$draft)
```

To create the final documents:

rmarkdown::render(
    "Template_file.Rmd", 
    output_file = "Indonesia_draft.html", 
    params = list(country = "Indonesia") # draft is TRUE by default
)

rmarkdown::render(
    "Template_file.Rmd", 
    output_file = "Indonesia_final.html", 
    params = list(country = "Indonesia", draft = FALSE) 
)

Reproducibility

Now that you have an understanding of the process of creating final documents from code. Let’s return to the goal of making these reports reproducible. The goal is that we (or someone else) could take our code and data and produce the same final output.

With that goal in mind, a reminder of some recommendations to follow:

Keep everything in a single project folder

Keeping all the files needed for a project in a single, self contained folder will help with portability. You can transfer a single folder to someone that contains everything they need to reproduce your analysis.

Don’t use absolute paths for files

When referring to files within your code, use relative paths (data/input.csv) rather than absolute paths (/Users/<your_name>/project/data/input.csv). Absolute paths won’t work on any machine but the one you wrote them for, and may not even work there if you move things around the file system.

Keep everything in a single project directory and refer to files by their location within that directory.

Include package version info

We have already shown a small example of this using getRversion() and packageVersion(). You can print all the version information about your script as it runs with sessionInfo().

A code chunk like:

```{r reproducibility_info}
sessionInfo()
```

at the end of your document will include information about your R version, operating system and the versions of any packages you have loaded.

Test your reproducibility

There’s nothing worse than expecting to be able to recreate a document but running into errors. Don’t feel shy about testing this out by backing up and deleting your output files and trying to recreate them. It’s far better to learn of any reproducibility issues so that you can fix them before they become a problem.

Key Points

• Set parameters in the YAML with params:

• Access parameters in code using params$<NAME>

• Create multiple documents from the same .Rmd document using rmarkdown::render