Quarto for Reproducible Reporting

Fall 2022 Literate Programming Workshops

Heidi Steiner, PSM | Data Science Educator

I am a health scientist and NOT a computer scientist!

I am very much still learning Quarto, RMarkdown, R, etc.

Content is a mixture of [RStudio Education materials](https://github.com/rstudio-education), CC-BY. All art (unless otherwise noted) is by [Desirée De Leon](https://desiree.rbind.io/) and [Allison Horst](https://www.allisonhorst.com/), CC-BY-NC-ND.

Quarto

Quarto® is an open-source scientific and technical publishing system built to dramatically improve the process of creating and collaborating

Graphic showing R, Python, Julia, and Observable languages flowing to Quarto and then on to html, PDF, and MS Word documents

Quarto documents, and other “literate programming” documents such as .rmd and .ipynb, include code, prose, and results in a single human-readable file

Change your mental model

drake meme shaking head at copy/paste and encouraging source -> output models

Your Turn

  • Clone https://github.com/hidyverse/quarto-examples to RStudio
  • Open Intro_to_Quarto.qmd, and render

Hints

  • “Preview in Viewer Pane” vs “Window”

  • If you’re not new to these concepts, feel free to be flexible with these directions! Comfy outside of RStudio? Give VSCode a try.

  • RStudio should tell you when something needs to be installed…pay close attention!

Change your mental model

Source ↔︎ output

screenshot of blank word.docx

Source → output

Change your mental model

Source ↔︎ output

Small plastic doll of a white girl in a pink and green outfit

Source → output

plastic doll with textile clothing, hair of a white girl in pink and green outfit

Same doll, different occasions

plastic doll with textile clothing, hair of white girl wearing four different themed outfits

Same doll source, different occasions

plastic doll with textile clothing, hair of white girl wearing four different themed outfits

Let’s dive in.

Anatomy of a .qmd

  1. Metadata
  2. Markup
  3. Code
  4. Output

handrawn graphic of literate programming document

Metadata: YAML

“YAML Ain’t Markup Language”

---

key: value

---

  • Save options in your YAML

    • “setup” chunk

  • format: html

the back of an illustrated orchestra conductor

Your Turn

  • Update the YAML header of Intro_to_Quarto.qmd to add a Table of Contents

  • Fold your code!

Hints

  • Did you try RStudio’s tab-completion feature?
  • re-render often when you make changes to your YAML!
  • Do you know how to search documentation? https://quarto.org/docs/reference/

Markdown (…is a Markup language)

# Heading 1
This is a sentence with some **bold text**, some *italic text* and an 
![image](image.png){fig-alt="Alt text for this image"}.

^^ Check out commonmark for a tutorial on common markup languages!

Your Turn

With or without the visual editor…

  • Add an image

  • Add a blockquote text section

Code

```{r}
library(dplyr)
mtcars |> 
  group_by(cyl) |> 
  summarize(mean = mean(mpg))
```

```{python}
from siuba import _, group_by, summarize
from siuba.data import mtcars
(mtcars
  >> group_by(_.cyl)
  >> summarize(avg_mpg = _.mpg.mean())
  )
```
```{ojs}
{
  let sum = 0;
  for (let i = 0; i < 10; ++i) {
    sum += i;
  }
  return sum;
}
```

```{julia}
using Plots

plot(sin, 
     x->sin(2x), 
     0, 
     2π, 
     leg=false, 
     fill=(0,:lavender))
```

Your Turn

  • Investigate Intro_to_Python.ipynb (Hint: Can you open it?)

  • Find your Terminal within RStudio

  • Convert your ipynb to qmd with

    quarto convert Intro_to_Python.ipynb

  • Render Intro_to_Python.qmd

Don’t like RStudio?

A screenshot of a Quarto document rendered inside JupyterLab

Keep your happy place

A screenshot of a Quarto document rendered inside VSCode

Nearly limitless output formats

illustration of brown hedgehod wearing a yellow knitted beanie knitting a turquoise scarf surrounded by possible output options such as pdf and word doc

Your Turn

  • quarto create-project mysite --type website

  • quarto preview mysite/

  • quarto render mysite/

  • Peep the _quarto.yml file and PDF output

Render and Send ’er

In general, if it renders, it’s safe to send!

screenshot of UArizona RStudio Connect service

Style your qmd

CSS

.body {
  font: 100% Helvetica, sans-serif;
  color: #333;
}

scss = CSS +

/*-- scss:defaults --*/

$font-stack: Helvetica, sans-serif;
$primary-color: #333;


/*-- scss:rules --*/

.body {
  font: 100% $font-stack;
  color: $primary-color;
}

Awesome Quarto

Pro-Tip

“awesome” lists are often great resources!

Summary

  • Quarto is a “batteries included” command line tool that shares syntax across output types/languages/editors

  • Learn about revealjs presentations in quarto from this slidedeck

  • Send me feedback! https://tinyurl.com/y2sbf58r

illustration of quarto's rendering process