Quarto and .qmd’s: Revisited

Nicky Wakim

Recap and today’s goals

  • Last time (and what we’ve been using), we covered the building blocks of a .qmd:

    • YAML metadata, text, and code chunks
    • Creating, editing, saving, and rendering a file

 

  • Today, we’ll level up with tools that are especially useful when writing and styling reports:

    • Inline code
    • LaTeX math
    • Code chunks: cross-references and code folding
    • Fenced divs: callouts and tabsets

Inline code: mixing R results into text

  • Inline code is helpful for reports and updates: your write-up automatically updates if your data or code change!!
  • Instead of typing a number by hand, you can pull it directly from your code using inline code

Written in qmd:

The HRS dataset has `r nrow(hrs_00)` rows and `r n_distinct(hrs_00$hhid)` 
households.

Which renders as:

The HRS dataset has 2728 rows and 1468 households.

 

Inline code uses single backticks with a lowercase r right after the first backtick (no curly braces, unlike a chunk)

Inline code: helpful pairings

  • round():control decimal places
  • comma(): format big numbers with commas (in scales package)
  • percent(): format proportions as % (in scales package)

Code it in R and assign to objects:

mean_income <- mean(hrs_00$income, na.rm = T) |> round(1) |> comma()
perc_sleep <- mean(hrs_00$sleep == "Yes", na.rm = T) |> percent(accuracy = 0.1)

Written in qmd:

The mean income in the HRS dataset is $`r mean_income` and the percent 
of responders who have trouble sleeping is `r perc_sleep`.

Which renders as:

The mean income in the HRS dataset is $91,813 and the percent of responders who have trouble sleeping is 19.6%.

LaTeX math: writing equations

Quarto renders LaTeX math using MathJax — no extra setup needed

  • Inline math: wrap with single dollar signs — $...$
  • Display math: wrap with double dollar signs — $$...$$

Written in qmd:

The slope $\beta_1$ describes the change in $Y$ for a one-unit change in $X$.

$$
Y_i = \beta_0 + \beta_1 X_i + \epsilon_i
$$

Which renders as:

The slope \(\beta_1\) describes the change in \(Y\) for a one-unit change in \(X\).

\[ Y_i = \beta_0 + \beta_1 X_i + \epsilon_i \]

LaTeX math: a worked example

We can use LaTeX math to write equations for the mean and proportion of a variable in our dataset

Written in qmd:

$$
\overline{\text{income}} = \frac{1}{n}\sum_{i=1}^{n} \text{income}_i
$$

$\overline{\text{income}} = \text{$} `r mean_income`$

Which renders as:

\[ \overline{\text{income}} = \frac{1}{n}\sum_{i=1}^{n} \text{income}_i \]

\(\overline{\text{income}} = \text{\$}91,813\)

Previously: code chunk options

You can control how a chunk behaves with #| options at the top of the chunk:

Option What it does
echo: false Hides the code in output (results still show)
warning: false Hides warnings from the output
include: false Hides both code and results (still runs)
eval: false Don’t run the code (no output) 
```{r}
#| echo: false
#| warning: false 
#| eval: false
```
1
This is helpful if you do not want to show your code
2
This is helpful if your qmd file has code that doesn’t work or takes a long time to run, but you still want to render the document

More code chunk options: code folding

  • Code folding lets readers choose whether to see your code
  • Keeps reports cleaner

Written in qmd:

```{r}
#| code-fold: true
#| code-summary: "Calculating mean income and percent trouble sleeping"

mean_income <- mean(hrs_00$income, na.rm = T) |> round(1) |> comma()
perc_sleep <- mean(hrs_00$sleep == "Yes", na.rm = T) |> percent(accuracy = 0.1)
```

Which renders as:

Calculating mean income and percent trouble sleeping 
mean_income <- mean(hrs_00$income, na.rm = T) |> round(1) |> comma()
perc_sleep <- mean(hrs_00$sleep == "Yes", na.rm = T) |> percent(accuracy = 0.1)

More code chunk options: cross referencing

  • You can label a code chunk with a figure or table, then reference it anywhere with @
  • Labels must start with a prefix: fig-, tbl-, eq-, or sec-
  • Quarto auto-numbers them and updates the numbers if you reorder slides

 

  • We format our code chunk with a label and a figure caption (caption is “Plot of _____”)
```{r}
#| label: fig-summ-stats
#| fig-cap: "Plot of _____"

# Code for plot goes here!
```

Then we reference inline with @fig-summ-stats

More code chunk options: Example for cross referencing

If we want to create a table of summary statistics, we can use the label to reference it later in the text:

```{r}
#| label: tbl-summ-stats
#| fig-cap: "Summary statistics for income and trouble sleeping"

hrs_00 |> 
  select(income, sleep) |>
  tbl_summary(
    statistic = list(all_continuous() ~ "{mean} ({sd})")
  )
```

In @tbl-summ-stats, we see the mean and standard deviation for income and 
the proportion of respondents who report trouble sleeping.

 

hrs_00 |> 
  select(income, sleep) |>
  tbl_summary(statistic = list(all_continuous() ~ "{mean} ({sd})")) |>
  as_gt() |>
  tab_options(table.font.size = "40px")
Table 1
Characteristic N = 2,7281
Total Household Income 91,813 (128,588)
Ever Had Sleep Disorder 534 (20%)
1 Mean (SD); n (%)

Summary statistics for income and trouble sleeping

In Table 1, we see the mean and standard deviation for income and the proportion of respondents who report trouble sleeping.

Callout blocks: highlight key info

  • Callouts are a “fenced div” that draws the reader’s eye to important notes, warnings, or tips
  • There are five types of callouts: note, tip, warning, important, and caution
  • You also have options for the appearance type: default, minimal, and simple

 

  • We use ::: and {.callout-<type>} to create a callout block, then close it with ::: at the end

Written in qmd:

::: {.callout-note appearance="minimal"}
This is a neutral, informational note.
:::

Which renders as:

This is a neutral, informational note.

Tabsets

  • Tabsets are a “fenced div” that organizes multiple views with clickable tabs
  • We use ::: {.panel-tabset} to create a tabset, then close it with ::: at the end
    • Each tab is created with a header (e.g., ### Plot or ### Table) and the content for that tab goes below the header

Written in qmd:

::: {.panel-tabset}
### Plot
Your ggplot code here

### Table
Your gt table here
:::

Which renders as:

Your ggplot code here

Your gt table here

Wrap-up

  • We covered a few more tools for writing reports in Quarto!

 

  • Inline code keeps numbers in your prose synced with your analysis
  • LaTeX math lets you write clean equations, inline or on their own line
  • Cross-references and code folding are code chunk options that help readers navigate your work
  • Callouts and tabsets are fenced divs that help you write clear, well-organized reports

Resources