08 - Advanced
Quarto +knitr

Parameters

You may have a set of parameters that are used to create different variations of a report. For example:

  • Showing results for a specific geographic location.
  • Running a report that covers a specific time period.
  • Running a single analysis multiple times for different assumptions.

knitr parameters

---
title: "My Document"
params:
  alpha: 0.1
  ratio: 0.1
---
quarto render file.qmd -P alpha:0.2 -P ratio:0.3
quarto::quarto_render(execute_params = list(alpha = 0.2, ratio = 0.3))

Accessing parameters

Parameters are accessed as params$NAME in the document.

params$alpha # returns 0.1
params$ratio # returns 0.1

Or in inline code r params$NAME

Paramaterized report

---
title: "Penguins"
date: 2020-08-11
format: html
params:
  species: Adelie
---
```{r}
#| label: setup
#| include: false
library(tidyverse)
library(palmerpenguins)
smaller <- penguins |> 
  filter(species == params$species, 
         !is.na(body_mass_g))
```

We have data about `r nrow(penguins)` penguins. 
The distribution of the 
`r params$species` penguins are shown below:

```{r}
#| echo: false
smaller |> 
  ggplot(aes(body_mass_g)) + 
  geom_histogram(binwidth = 100)
```

Rendering

quarto::quarto_render(
  "penguin-params.qmd",
  execute_params = list(species = "Chinstrap"),
  output_file = "choose-chinstrap.html"
)


Directory matters!

render_fun <- function(penguin){
  quarto::quarto_render(
    "materials/workshop/08-knitr/penguin-params.qmd",
    execute_params = list(species = penguin),
    output_file = glue::glue(
      "materials/workshop/08-knitr/{penguin}-report.html"
      )
  )
}


Use purrr to iterate across the distinct species

penguin_names <- 
  distinct(penguins, species) |> 
  pull() |> 
  as.character() 
penguin_names
[1] "Adelie"    "Gentoo"    "Chinstrap"
penguin_names |> 
  purrr::walk(render_fun) # or lapply(penguin_names, render_fun)

Your Turn

  • Open materials/workshop/08-knitr/penguin-params.qmd
  • Open materials/workshop/08-knitr/render-params.R
  • Follow the instructions in render-params.R

Commenting

This page has commenting with Hypothes.is enabled via the following YAML option:

comments:
  hypothesis: true

Conditional content

::: {.content-visible when-format="html"}

Will only appear in HTML.

:::
::: {.content-visible unless-format="pdf"}

Will not appear in PDF.

:::

Quarto Extensions

Quarto Extensions are a powerful way to modify or extend the behavior of Quarto, and can be created and distributed by anyone. There are two types of extensions available:

  • Shortcodes are special markdown directives that generate various types of content. For example, you could create shortcodes to embed tweets or videos in a document.

  • Filters are a flexible and powerful tool for introducing new global behaviors and/or new markdown rendering behaviors. For example, you could create filters to implement output folding, an image carousel, or just about anything you can imagine!

Note that you have to use at least version Quarto v1.0.15 to use extensions

Available extensions can be found at: https://github.com/quarto-ext/

Extensions

Extensions are project-specific installs, installed into _extensions directory in your Quarto Project (or any directory where you want to affect quarto render).

The Quarto team will develop extensions and host at quarto-ext, but you can also download extensions from the community.

Extension Trust

It’s important to note that Quarto extensions may execute code when documents are rendered. If you do not trust the authors of an extension, we recommend that you do not install or use the extension.

Managing extensions

You can install extensions directly from Quarto!

cd MyQuartoProject # or any directory
quarto install extension quarto-ext/lightbox
quarto list extensions # list all installed extensions
quarto update extension quarto-ext/fontawesome # update specific extension
quarto remove extension quarto-ext/fontawesome # remove specific extension


Extensions + Version control

If you are using version control you should check the _extensions directory in to your repo along with your other code. Installed extensions are treated as source code for your project to ensure very long term reproducibility—your project doesn’t need to rely on the availability of an external package manager (or the maintenance of older extension versions) to successfully render now and far into the future.

Install Flow

thomasmock$ quarto install extension quarto-ext/fontawesome


Quarto extensions may execute code when documents are rendered. If you do not 
trust the authors of the extension, we recommend that you do not install or 
use the extension.
 ? Do you trust the authors of this extension (Y/n) › Yes
[✓] Downloading
[✓] Unzipping
    Found 1 extension.


The following changes will be made:
Font Awesome support   [Install]   0.0.1 (shortcode)
 ? Would you like to continue (Y/n) › Yes

[✓] Extension installation complete.
Learn more about this extension at https://github.com/quarto-ext/fontawesome


```{bash}
quarto list extensions
```
Id                            Version    Contributes
quarto-ext/fontawesome        0.0.1      shortcodes 
quarto-ext/lightbox           0.0.1      filters    
quarto-ext/grouped-tabsets    0.0.1      filters

Check fontawesome

There once was a who was lost at

He was rescued by a and a wee 


There once was a {{< fa dog >}} who was lost at {{< fa water >}}

He was rescued by a {{< fa sailboat >}} and a wee {{< fa life-ring >}}

Your Turn

  • Open materials/workshop/08-knitr/lightbox-extension.qmd
  • Explore and render it!

Feedback

Please complete the post-workshop survey. Your feedback is crucial! Data from the survey informs curriculum and format decisions for future conf workshops and we really appreciate you taking the time to provide it.

<rstd.io/conf-workshop-survey>

Get started with Quarto