Rendering reports

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

Three ways to render

1. RStudio/Quarto integration:

   Render button in RStudio or Cmd/Ctrl + Shift + K keyboard shortcut

2. ✨ Quarto R package ✨

   Console or R script

   quarto::quarto_render(
     input = here::here("2-quarto-render.qmd"),   # Input Quarto file
     execute_params = list(                       # Named list of params
       pet_type = "cats",
       fave_breed = "Snowshoe"))

3. Quarto CLI

   Terminal

   quarto render 2-quarto-render.qmd -P pet_type:'cats' -P fave_breed:'Snowshoe'

💪🏼 Exercise

Change parameters in the YAML and render using Render button.

1. Look at the unique pet breeds and pick your favorite.

   # Run in the console
   pets <- readr::read_rds(here::here("data", "pets.RDS")) |> 
      dplyr::distinct(pet_type, breed) |> View()

2. In 2-quarto-render.qmd, change the default parameters in the YAML to your favorite pet type and breed. Render using the Render button.

   params:
     pet_type: "___"
     fave_breed: "___"

3. 💬 Chat: Which breed did you pick and why? What do you think will happen if you set the pet_type default parameter to “cats” and the fave_breed parameter to “American Bulldog”?

   Try it out and discuss what happend!

07:00

💪🏼 Exercise

Change parameters and render using quarto_render().

1. Render with quarto::quarto_render().

   # Run in the console
    quarto::quarto_render(
      input = here::here("2-quarto-render.qmd"),
      execute_params = list(
        pet_type = "___",
        fave_breed = "___"))

2. 💬 Chat: What kinds of variables will you use as parameters for your reports?

07:00

Render all 538 reports

One HTML report for each cat breed and each dog breed.

• 📊 Data
• 👷🏼‍♂️ Manual 1
• 👷🏻‍♀️ Manual 2
• ⚡ Programatically

pets <- readr::read_rds(here::here("data", "pets.RDS"))

pets |>
  dplyr::distinct(pet_type, breed) |>
  dplyr::count(pet_type) |>
  janitor::adorn_totals()

pet_type	n
cats	104
dogs	434
Total	538

1. Change the default params in the YAML.

2. Render button or Cmd/Ctrl + Shift + K keyboard shortcut.

3. Rename the rendered report to include the parameter & prevent overwriting.

4. Repeat 537 times.

😭

quarto::quarto_render(
  input = here::here("2-quarto-render.qmd"),
  output_file = "dogs-affenpinscher-report.html",
  execute_params = list(
    pet_type = "dogs",
    fave_breed = "Affenpinscher"))

quarto::quarto_render(
  input = here::here("2-quarto-render.qmd"),
  output_file = "dogs-afghan-hound-report.html",
  execute_params = list(
    pet_type = "dogs",
    fave_breed = "Afghan Hound"))

quarto::quarto_render(
  input = here::here("2-quarto-render.qmd"),
  output_file = "dogs-aidi-chien-de-montagne-de-l-atlas-report.html",
  execute_params = list(
    pet_type = "dogs",
    fave_breed = "Aidi Chien De Montagne De L Atlas"))

quarto::quarto_render(
  input = here::here("2-quarto-render.qmd"),
  output_file = "dogs-akita-report.html",
  execute_params = list(
    pet_type = "dogs",
    fave_breed = "Akita"))

# + 534 more times... 
# 😭

Create a dataframe with three columns that match quarto_render() args:

• output_format: file type (html, revealjs, pdf, docx, etc.)

• output_file: file name with extension

• execute_params: named list of parameters

Map over each row:

• purrr::pwalk(dataframe, quarto_render, <arguments for quarto_render>) 😎

Primer on purrr functions for iteration

Map functions apply the same action/function to each element of an object.

• Base R apply() functions are map functions.

• purrr map functions have consistent syntax and the output data type is predictable.

for loops → lapply() → purrr::map()

Learn more:

• Iteration chapter of R for Data Science

• R-Ladies Baltimore presentation Make your R Code purr with purrr

• Jenny Bryan’s tutorial and workshop

Create dataframe to iterate over

pet_reports <- pets |>
  dplyr::distinct(pet_type, breed) |>   # Get distinct pet/breed combos
  dplyr::mutate(
    output_format = "html",             # Make output_format column
    output_file = paste(                # Make output_file column:
      tolower(pet_type),                # cats-abyssiniane-report.html
      tolower(gsub(" ", "-", breed)),           
      "report.html",
      sep = "-"
    ),
    execute_params = purrr::map2(       # Make execute_params column
      pet_type,
      breed,
      \(pet_type, breed) list(pet_type = pet_type, breed = breed)))

Subset to first 2 cat/dog breeds

pet_reports_subset <- pet_reports |>
  dplyr::slice_head(n = 2, by = pet_type) |>
  dplyr::select(output_file, execute_params)

pet_reports_subset

output_file	execute_params
cats-abyssiniane-report.html	cats , Abyssiniane
cats-aegean-cat-report.html	cats , Aegean Cat
dogs-affenpinscher-report.html	dogs , Affenpinscher
dogs-afghan-hound-report.html	dogs , Afghan Hound

Map over each row

• purrr::pwalk() iterates over multiple arguments simultaneously.

• First .l argument is a list of vectors.

  • Dataframe is a special case of .l that iterates over rows.

purrr::pwalk(
  .l = pet_reports_subset,                      # Dataframe to map over
  .f = quarto::quarto_render,                   # Function we are applying to each row
  input = here::here("2-quarto-render.qmd"),    # Named arguments of .f
  .progress = TRUE                              # Show a progress bar :)
)

Note

input is the only named argument of quarto_render() included in pwalk().

output_format, output_file, and execute_params are already passed in through the dataframe.

Multiple formats

Render all reports to all formats

Add to the format: YAML option to render additional output formats from the same .qmd file.

---
format:
  html: 
    embed-resources: true   # Makes the report self-contained
  pdf: default              # If not using any additional format options,
  docx: default             # set value to `default`  
---

Note: the Render button now has a dropdown!

Quarto docs on multiple formats

Format links for HTML output

Links to download the other formats will automatically appear in HTML documents.

Format link options

Choose which format links to include:

---
format:
  html: 
    embed-resources: true
  pdf: default
  docx: default
format-links: [pdf, docx]
---

Or hide all links:

---
format:
  html: 
    embed-resources: true
  pdf: default
  docx: default
format-links: false
---

💃🏻 Demo

Programmatically render all reports in all formats in 3-purrr-render-demo.qmd and 3-purrr-render-demo.R.

💡 Use these files as a template and modify them for your own projects!

Directory limitations

Can’t render reports to another directory.

output-dir YAML option only works for Quarto projects that contain a _quarto.yml config file.

Workaround: use {fs} to move files after rendering.

See 3-purrr-render-demo.R for example.

More info: GitHub discussion and GitHub issue.

Can’t embed resources for a Quarto document in a subfolder.

If using embed-resources: true YAML option, .qmd can’t be in subfolder, otherwise:

[WARNING] Could not fetch resource …

More info: GitHub discussion and GitHub issue.

🚶🏻‍♀ 30-min break 🧘🏾‍♂️️

30:00