A step-by-step guide to parameterized reporting in R using Quarto
Parameterized reporting is one of the best reasons to use R. This technique allows you to generate dozens, hundreds, even thousands of reports at the same time. In this blog post, I give you a walkthrough of how to use parameterized reporting with Quarto. You'll learn what parameterized reporting is, how parameterized reporting works, how to add parameters to your Quarto documents, and how to use an R script file to render multiple reports.
You can watch the full video below or follow the step-by-step walkthrough in the shorter videos that follow. All of these videos come from Going Deeper with R. Ready to learn about parameterized reporting with Quarto? Let's dive in!
What is parameterized reporting?
If you've never heard of parameterized reporting, this video will explain it to you. In the video, I tell a story of making reports manually, which was painful and error-prone. Parameterized reporting can help you avoid these problems! And, as I show in the video below, you can make a lot of nice-looking reports at the same time with parameterized reporting, something we do a lot in our consulting work.
Transcript
Click on the transcript to go to that point in the video. Please note that transcripts are auto generated and may contain minor inaccuracies.
How does parameterized reporting work?
The basic idea behind parameterized reporting is to make a single Quarto document that serves as a template file. This Quarto document is then rendered multiple times to create multiple reports. I show the overall process in this video.
Transcript
Click on the transcript to go to that point in the video. Please note that transcripts are auto generated and may contain minor inaccuracies.
Adding parameters to a Quarto document
In order to use a Quarto document for parameterized reporting, you must first add parameters to it. In this video, I show how this works.
Transcript
Click on the transcript to go to that point in the video. Please note that transcripts are auto generated and may contain minor inaccuracies.
The code shown in this video is below.
---
title: "Life Expectancy Report"
format: html
execute:
echo: false
warning: false
message: false
params:
country: "Afghanistan"
---
```{r}
library(tidyverse)
library(gapminder)
```
```{r}
life_expectancy <-
gapminder |>
select(country, year, lifeExp) |>
filter(country == params$country)
```
## Life Expectancy in `r params$country`
```{r}
ggplot(
data = life_expectancy,
aes(
x = year,
y = lifeExp
)
) +
geom_line() +
theme_minimal()
```Render a Quarto document with an R script file
As I showed in the previous video, adding parameters to your Quarto document is just the first step. If you want to make multiple reports, you need to create a separate R script file. In this R script file, you can write code that can render your Quarto document.
Transcript
Click on the transcript to go to that point in the video. Please note that transcripts are auto generated and may contain minor inaccuracies.
The code shown in the video to render a Quarto document is below.
library(quarto)
quarto_render(
input = "example-report.qmd",
output_file = "Afghanistan.html",
execute_params = list(country = "Afghanistan")
)Render multiple Quarto documents with an R script file
The R script file above worked to render a single report from our Quarto document. But for parameterized reporting, you need to write code to generate multiple reports. In this video, I show how to write code that renders multiple reports in an R script file.
Transcript
Click on the transcript to go to that point in the video. Please note that transcripts are auto generated and may contain minor inaccuracies.
The code I showed in the video is below.
library(quarto)
library(tidyverse)
library(gapminder)
countries <-
gapminder |>
distinct(country) |>
pull(country) |>
as.character()
reports <-
tibble(
input = "example-report.qmd",
output_file = str_glue("{countries}.html"),
execute_params = map(countries, ~ list(country = .))
)
pwalk(reports, quarto_render)We did it!
And that's it! We've now shown how to make multiple reports using parameterized reporting in R using Quarto.
If you want to learn more, check out Going Deeper with R. It teaches parameterized reporting and has exercises for you to learn it yourself.
Now go forth and make dozens, hundreds, even thousands of reports at once with parameterized reporting!
Sign up for the newsletter
Get blog posts like this delivered straight to your inbox.
You need to be signed-in to comment on this post. Login.