Beautiful Reports and Presentations
with Quarto

Tom Mock

9/27/22

Quarto - Visual Editor

A snippet of an RStudio window showing the options bar at the top of an RMarkdown document.

Format Insert Table
The contents of the Format drop down menu. The contents of the Table drop down menu.

Static documents

  • A static document is your “daily driver” - has the power for a complex table of contents, figure alignment, control of ouptut/code, and other niceties
  • Useful as a lab notebook, scratchpad, or the final output for your team
  • Most powerful as the combination of written thoughts and observations along with source code

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.

Parameters

Python - Papermill style

#| tags: [parameters]

alpha = 0.1
ratio = 0.1


str(alpha)

R - YAML style

---
title: "My Document"
params:
  alpha: 0.1
  ratio: 0.1
---


str(params$alpha)

CLI/Terminal

quarto render doc.qmd -P alpha:0.2 -P ratio:0.3

Render with Parameters

---
title: "Penguins"
date: today
format: html
params:
  species: Adelie
---
```{r}
#| label: setup
#| include: false
library(tidyverse)
library(palmerpenguins)

penguin_filter <- penguins |>
  filter(species == params$species,
    !is.na(body_mass_g))
diff_rows <- nrow(penguins) - nrow(penguin_filter)
```
We have data about `r nrow(penguins)` penguins. Only
`r diff_rows` are classified as `r params$species`. 
The distribution of the `r params$species` penguins 
are shown below:
```{r}
#| echo: false
penguin_filter |>
  ggplot(aes(body_mass_g)) +
  geom_histogram(binwidth = 100)
```

A screenshot of the output report, displaying the title, date, information about the penguins and a basic histogram.

Render with Parameters

quarto render penguin-report.qmd -P species:Gentoo --output gentoo-report.html
quarto render penguin-report.ipynb -P species:Gentoo --output gentoo-report.html
render_fun <- function(penguin){
  quarto::quarto_render(
    input = "penguin-report.qmd",
    execute_params = list(species = penguin),
    output_file = glue::glue("{penguin}-report.html")
  )
}

unique(penguins$species) |>
  as.character() |> 
  purrr::walk(render_fun)
Output created: Adelie-report.html
Output created: Chinstrap-report.html
Output created: Gentoo-report.html

Parameters for modeling

Example adapted from tidymodels docs

---
format: html
params:
  engine: "ranger"
---
quarto render tidymodels-example.qmd -P engine:randomForest
quarto render tidymodels-example.qmd -P engine:ranger


test_results %>% slice(1:5)

#> # A tibble: 5 × 2
#>   Sale_Price .pred
#>        <dbl> <dbl>
#> 1       5.39  5.27
#> 2       5.28  5.29
#> 3       5.23  5.26
#> 4       5.21  5.25
#> 5       5.60  5.52
test_results %>% metrics(truth = Sale_Price, 
                          estimate = .pred) 

#> # A tibble: 3 × 3
#>   .metric .estimator .estimate
#>   <chr>   <chr>          <dbl>
#> 1 rmse    standard      0.0925
#> 2 rsq     standard      0.742 
#> 3 mae     standard      0.0620
test_results %>% slice(1:5)

#> # A tibble: 5 × 2
#>   Sale_Price .pred
#>        <dbl> <dbl>
#> 1       5.39  5.27
#> 2       5.28  5.28
#> 3       5.23  5.26
#> 4       5.21  5.32
#> 5       5.60  5.51
test_results %>% metrics(truth = Sale_Price, 
                          estimate = .pred) 

#> # A tibble: 3 × 3
#>   .metric .estimator .estimate
#>   <chr>   <chr>          <dbl>
#> 1 rmse    standard      0.0944
#> 2 rsq     standard      0.731 
#> 3 mae     standard      0.0626

Unified Syntax

Quarto’s unified syntax

quarto render boston-terrier.qmd --to html
quarto render boston-terrier.qmd --to pdf

A screenshot of a HTML article about Boston Terriers, the document has an image in the right hard margin, a floating table of contents, and different sections split up by headers

HTML

A screenshot of a PDF article about Boston Terriers, the document has an image in the right hard margin, a floating table of contents, and different sections split up by headers

PDF

Pandoc fenced divs

::: {.class}
All this content can be modified
:::

Structure:

  • Start and end with equal number of : - minimum of 3 :::
  • Add curly brackets to indicate the start/end of class {.class} or {sometimes-class} 
::: {layout-ncol=2}

![](image.png){fig-alt="Description of image 1"}

![](image2.png){fig-alt="Description of image 1"}
:::

Tabsets

Split up and flip between sections of a page, alternative to just two columns

::: {.panel-tabset}

## Element 1
...content...

## Element 2
...content...
:::

Tabsets

```{r}
#| eval: false
head(mtcars)
```
                   mpg cyl disp  hp drat    wt  qsec vs am gear carb
Mazda RX4         21.0   6  160 110 3.90 2.620 16.46  0  1    4    4
Mazda RX4 Wag     21.0   6  160 110 3.90 2.875 17.02  0  1    4    4
Datsun 710        22.8   4  108  93 3.85 2.320 18.61  1  1    4    1
Hornet 4 Drive    21.4   6  258 110 3.08 3.215 19.44  1  0    3    1
Hornet Sportabout 18.7   8  360 175 3.15 3.440 17.02  0  0    3    2
Valiant           18.1   6  225 105 2.76 3.460 20.22  1  0    3    1

Tabsets

::: {.panel-tabset}
## Code
```{r}
#| echo: fenced
#| eval: false
head(mtcars)
```


## Output
```{r}
#| eval: true
#| echo: false
head(mtcars)
```
:::

Pandoc bracketed spans

This is magic text

# this only works in presentations
This is [magic text]{.fragment}

Structure:

  • Surround text with [text]
  • Add curly brackets to indicate the start/end of class {.class} or {sometimes-class}

Footnotes

You can create inline footnotes like so: some inline text with a^[footnote]

If you hover your mouse over the citation and footnote in this sentence you’ll see a popup displaying the reference contents:

format:
  html:
    citations-hover: true
    footnotes-hover: true


For example, did you know that Howard is a dog^[Specifically he is a Boston Terrier, although
sometimes he acts like a cat]?

Unified syntax

Layout image inline with paragraphs

::: {layout="[[30, 70], [100]]"}
![Terrier Seated](Terrier_Seated_(Boston_Public_Library).jpeg){width="50%" fig-alt="Description of boston terrier"} 

...paragraph 1... 

...paragraph 2...

:::

Put image into the “gutter”/column margin

![A young male Boston Terrier with a Brown brindle coat](330px-Boston_Terrier_male.jpeg){.column-margin fig-alt="Description of a young male Boston Terrier with a Brown brindle coat"}

Add footnotes:

The average life span of a Boston Terrier is around 11 to 13 years.^["The Boston Terrier Club Of America". Bostonterrierclubofamerica.org.]

Code

Hide all code

format: html
execute:
  echo: false

Turn back on at individual code-block level:

#| echo: true

Fold code

format:
  html:
    code-fold: true
    code-summary: "Hidden code"

Turn on at individual code-block level:

#| code-fold: true
#| code-summary: "Hidden code"

Code tools

format:
  html:
    code-fold: true
    code-tools: true

Screenshot of Quarto document with the Code tools dropdown

Code tools, source

For example, here we specify that we want only “View Source” (no toggling of code visibility) and no caption on the code menu:

format:
  html: 
    code-tools:
      source: true
      toggle: false
      caption: none

Screenshot of Quarto document with the source option overlay

Code tools, source repo

In some situations (especially for longer documents), you may prefer to send viewers to the source code on a version-control website rather than the built in viewer.

format:
  html: 
    code-tools:
      source: https://github.com/quarto-dev/quarto-web/blob/main/index.md

Code appearance

Code highlighting

Full highlighting options

library(dplyr)
mtcars |> 
  group_by(cyl, am) |> 
  summarize(mean = mean(mpg), n = n(), .groups = "drop")
# A tibble: 6 × 4
    cyl    am  mean     n
  <dbl> <dbl> <dbl> <int>
1     4     0  22.9     3
2     4     1  28.1     8
3     6     0  19.1     4
4     6     1  20.6     3
5     8     0  15.0    12
6     8     1  15.4     2

Code highlighting

format: 
  html:
    highlight-style: arrow
Screenshot of code with a light theme on white background

Code highlighting

format: 
  html:
    highlight-style: arrow
    theme:
      light: flatly
      dark: darkly

Screenshot of dark mode toggle in Quarto doc.

Screenshot of code with a light theme on white background

Code linking with downlit

The goal of downlit is to provide syntax highlighting and automatic linking of R code

format:
  html:
    code-link: true

Aesthetics

HTML Appearance

Out of the box, Quarto is styled with Bootstrap 5 and opinionated defaults.

Bootstrap is the most popular CSS Framework for responsive websites, where v5 is the latest.

Quarto comes pre-installed with 25 themes from Bootswatch and you can use them like so:

---
format:
  html:
    theme: litera
---


Or you can customize a theme with CSS/SCSS/SASS.

---
format:
  html:
    theme: 
      - litera
      - custom.scss
---

Bootswatch themes

Screenshot of 6 bootswatch themes

PDF Articles

format:
  pdf:
    template: mytemplate.tex


See more on Journal Articles at https://github.com/quarto-journals/

----
title: "My Document"
toc: true
format:
   acm-pdf: default
   acm-html: default
---

Screenshot of a rendered Quarto document to the Journal of Statistical Science format.

More PDF + LaTeX templates

Great work from the NFMS Open Science team on “Quarto titlepages”: https://nmfs-opensci.github.io/quarto_titlepages/

The tex templates were written by Eli Holmes and the lua filter along with changes to the Pandoc templates to allow themes was written by Mickaël Canouil.

A screenshot of the titlepages Quarto output PDF. It has a logo, along with the title information and the affiliations of the authors.

Presentations

Output types

  • Quarto supports a variety of formats for creating presentations, including:

Follow-up reading

Shared structures

  • Incremental reveal/lists
  • Multiple columns for layout
  • Title/subtitle/author/etc
  • Headings
  • Code/Output

Creating slides

---
format: revealjs
---

## Slide 1

## Slide 2

Incremental Lists

Controllable via YAML:

format:
  pptx:
    incremental: true

Or turn on/off via fenced divs:

::: {.incremental}

- Howard sleeps
- Howard sprints

:::
::: {.nonincremental}

- Howard eats
- Howard sleeps

:::

Multiple Columns

:::: {.columns}

::: {.column width="50%" .fragment}
Left column
:::

::: {.column width="50%" .fragment}
Right column
:::

::::

Presentations with format: revealjs

SECRET TIP

Alt + Click to Zoom in to a section

Howard dressed as a victorian gentleman

Absolute Position

Absolute position allows for tight control of placement.

::: {.absolute bottom=25 left=100 .fragment}

![](images/howard-gentleman.jpeg){width=150 fig-alt="Howard dressed as a victorian gentleman"}

:::

output-location: column-fragment

```{r}
#| output-location: column-fragment
library(ggplot2)

ggplot(mtcars, aes(x = mpg, y = disp)) +
  geom_point()
```

Themes

Quarto comes with 10 built-in themes:

beige, blood, dark, default, league, moon, night, serif, simple, sky, solarized

---
title: "Presentation"
format:
  revealjs: 
    theme: [simple, custom.scss]
---

Themes + SCSS/SASS

@import url('https://fonts.googleapis.com/css2?family=Fira+Mono&family=Open+Sans:ital,wght@0,300;0,400;0,500;0,600;0,700;0,800;1,300;1,400;1,500;1,600;1,700;1,800&display=swap');

/*-- scss:defaults --*/

$link-color: #EE6331;
$font-family-sans-serif: 'Open Sans', sans-serif;
$font-family-monospace: 'Fira Mono', monospace;

$presentation-title-slide-text-align: left;

/*-- scss:rules --*/

h2 {
  color: #447099 !important;
}

Slide Background

Slide Background

## Slide Background {background-color="black" background-image="images/howard-gentleman.jpeg" background-size="100px" background-repeat="repeat"}
Attribute Default Description
background-image URL of the image to show. GIFs restart when the slide opens.
background-size cover See background-size on MDN.
background-position center See background-position on MDN.
background-repeat no-repeat See background-repeat on MDN.
background-opacity 1 Opacity of the background image on a 0-1 scale. 0 is transparent and 1 is fully opaque.

Slide Background

Changing the background color will modify the font color for better contrast

## Slide Background {background-color="black")

Background videos

Automatically plays a full size video behind the slide.

Attribute Default Description
background-video A single video source, or a comma separated list of video sources.
background-video-loop false Flags if the video should play repeatedly.
background-video-muted false Flags if the audio should be muted.
background-size cover Use cover for full screen and some cropping or contain for letterboxing.
background-opacity 1 Opacity of the background video on a 0-1 scale. 0 is transparent and 1 is fully opaque.

r-stack + fragments

::: {.r-stack}
![](image1.png){.fragment width="450"}

![](image2.png){.fragment width="300"}

![](image3.png){.fragment width="400"}
:::

r-stack + fragments

Custom classes

From Emil’s article:

*-- scss:rules --*/

.blue {
  color: $theme-blue;
  font-weight: bold;
}

.yellow {
  color: $theme-yellow;
  font-weight: bold;
}
[Quarto]{.blue} enables you to weave together [content]{.yellow} and 
[executable code]{.yellow} into a **finished presentation**. 
To learn more about [Quarto]{.blue} presentations see <https://quarto.org/docs/presentations/>.

Custom Classes

Screenshot of Quarto presentation with specific text highlighted yellow/blue.

Applying classes

Use bracketed spans: [text to color]{.yellow} or use RStudio’s Visual Editor:

The end!

Read all the docs at https://quarto.org/docs/guide/

Reports

Presentations

thomasmock.quarto.pub/reports-presentations