Parameterizing reports

Jadey Ryan // June 21, 2024
Intermediate Quarto // Cascadia R Conf

Examples of parameterized reports

Ocean floor maps

Fiscal briefs

Bad drivers

Soil health

Another use case: different audiences, different reports

Show code for technical staff and hide code for everyone else (StackOverflow example).

Like a custom function

What makes a report “parameterized”?

• YAML header with params key-value pairs

• Use these params to create different variations of a report from a single .qmd document.

Important

• Valid parameter values are strings, numbers, or Boolean.

• Must serialize a dataframe to pass it as a parameter, then un-serialize it back to a dataframe within the .qmd content.

• See Christophe Dervieux’s answer in Posit Community to understand why.

• See John Paul Helveston’s blog post to learn how to use {jsonlite} as a workaround.

Workflow

1. Write report template with default values hard-coded, and then render & review.

2. Set default params key-value pairs in YAML.

3. Replace hard-coded values with the params variables.

4. Render the single report and review.

5. Render extreme cases and review.

   • Parameter values with barely any data and with tons of data.

6. Render all variations of the report at once.

💪🏼 Exercise

Explore a report without parameters and see where we could add them.

1. Open 1-swiss-cats.qmd.

2. Click the Render button.

3. Look at the source markdown & code and the rendered report.

4. 💬 Chat: What variables could we set as parameters?

   💡 Hint: run the setup chunk and look at the pets dataframe to see what variables it has.

05:00

Set params in YAML header

---
title: "Swiss Cats"             # Metadata
format:                         # Set format types
  html:
    toc: true                   # Set additional options
  docx: default                           
params:                         # Set default parameter key-value pairs
  fave_breed: "Snowshoe"                                
---
    
Report content goes here.       # Write narrative and code

Important

Your default params key-value pairs must be found in your dataset. Otherwise, code will error or output will be blank.

The variable name for params can be anything you choose. Often, it’s a column name in your dataset.

Access params

Run any line or chunk to add params to your environment.

params object is a list.

str(params)

List of 1
 $ fave_breed: chr "Snowshoe"

Access with $ notation.

params$fave_breed

[1] "Snowshoe"

For inline code in YAML or report content, enclose the expression in `r `.

My favorite cat breed is the **`r params$fave_breed`**.

My favorite cat breed is the Snowshoe.

Replace hard-coded values with params

Cmd/Ctrl + F to find where to replace hard-coded values with params.

Replace hard-coded values with params

Use $ list notation in code for plot/table titles and labels, filtering, etc.

paste() syntax:

# ggplot2 code +
    labs(title = paste(params$fave_breed, "population"))

glue::glue() syntax:

# ggplot2 code +
    labs(title = glue::glue("{params$fave_breed} population"))

Use inline R code for markdown.

## My favorite breed: **`r params$fave_breed`**.

💃🏻 Demo

Modify 1-swiss-cats-demo.qmd to add pet_type and fave_breed parameters.

This parameterized version of 1-swiss-cats.qmd is the starting point for the next section’s exercises (2-quarto-render.qmd).