Data Rich Reports

Session 8–Parameterized Reporting

What is Parameterized Reporting?

  • Make one template report in Quarto
  • Create R script file that allows you to make multiple reports from this template

Why Parameterized Reporting?

  • Allows you to make multiple reports at once
  • Avoids copy paste issues if you were to make multiple reports by hand
  • It feels like magic!

Parameterized Reports We Have Made

How Does Parameterized Reporting Work?

File with the word '.qmd' inside and the word 'Function' above.

An arrow points from 'Input' with 'params$year' to the previous image with 'Function' and '.qmd' file.

In addition to the previous two images, arrows point to five reports with years 2019 through 2023 on them in a flow chart.

Source: Jadey Ryan

Manually Create Multiple Reports

  • You can manually make multiple reports by, for example, adjusting the country you filter on in your Quarto document
gapminder_filtered <-
  gapminder |> 
  filter(country == "Afghanistan")
ggplot(data = gapminder_filtered,
       aes(x = year,
           y = lifeExp,
           group = country)) +
  geom_line() +
  theme_minimal()

Parameters

---
title: "Report on Life Expectancy"
format: html
execute: 
  echo: false
  warning: false
  message: false
---

Parameters

YAML

---
title: "Report on Life Expectancy"
format: html
execute: 
  echo: false
  warning: false
  message: false
params: 
  country: Afghanistan 
---

Code

gapminder_filtered <-
  gapminder |> 
  filter(country == params$country)
ggplot(data = gapminder_filtered,
       aes(x = year,
           y = lifeExp,
           group = country)) +
  geom_line() +
  theme_minimal()

Your Turn

  • Install the usethis package with install.packages("usethis")
  • Run this code:
usethis::use_course("https://github.com/rfortherestofus/gw-parameterized-report-example/archive/refs/heads/main.zip")
  • And answer yes to the questions it gives you…
  • Open the project (it should happen automatically)
  • Open the report.qmd file and save it as report2.qmd
  • Change the country parameter in the YAML to be called continent and set the default value to be “Asia”
  • Adjust the code that creates the gapminder_filtered data frame so that it filters to use the continent parameter
05:00

Use Parameters for Inline Code

## Life Expectancy in `r params$country`

Your Turn

  • Working in your report2.qmd file, use inline code to create a line that says “This report is on population in [CONTINENT] from 1952 to 2007.”
  • Use inline code to make the [CONTINENT] portion use your parameter
  • If you finish early, write code to make the 1952 and 2007 values show up using inline R code
05:00

Render with R Script

  • Create a new file (render.R is what I typically call it)
  • Use the quarto_render() function from the quarto package:
library(quarto)

quarto_render(
  input = "report.qmd"
)

Your Turn

  • Install the quarto package using install.packages("quarto")
  • Open the file called render.R file and save it as render2.R
  • Adjust the code to render your report2.qmd document using the quarto_render() function
05:00

Add Arguments to quarto_render()

  • Add additional arguments to quarto_render():
library(quarto)

quarto_render(
  input = "report.qmd",
  output_file = "Afghanistan.html",
  execute_params = list(country = "Afghanistan")
)

Your Turn

  • Working in the render2.R file, add an execute_params argument to the quarto_render() function to render the report for Africa
  • Also change the name of the rendered HTML file to Africa.html using the output_file argument
05:00

Render Multiple Reports with quarto_render()

  • Create a tibble (i.e. data frame) with the data for all of the reports you want to create:
countries <-
  gapminder |>
  distinct(country) |>
  pull(country) |>
  as.character()

reports <-
  tibble(
    input = "report.qmd",
    output_file = str_glue("reports/{countries}.html"),
    execute_params = map(countries, ~list(country = .))
  )

Render Multiple Reports with quarto_render()

  • Use the pwalk() function from the purrr package to render all reports:
pwalk(reports, quarto_render)

Your Turn

  • Working in the render2.R file, create a vector called continents that has all continents for which we want to make reports. Use the code below as a model.
countries <-
  gapminder |>
  distinct(country) |>
  pull(country) |>
  as.character()
02:00

Your Turn

  • Working in the render2.R file, create a tibble called reports that has all of the data needed to render all reports. Use the code below as a model.
reports <-
  tibble(
    input = "report.qmd",
    output_file = str_glue("reports/{countries}.html"),
    execute_params = map(countries, ~list(country = .))
  )
02:00

Your Turn

  • Working in the render2.R file, use the pwalk() function from the purrr package to render all reports. Use the code below as a model.
pwalk(VECTOR, FUNCTION)

Additional Exercise

  • Create a set of parameterized reports for each year that have a bar chart that shows the population in each country

DRR Website