Quarto for Reproduceable Reporting (with Confetti!)

Quarto - My favorite thing

Lisa Anders - Posit Solutions Engineer and R nerd learning to also love Python. Excited to share lessons learned the hard way to make things easier for others. Awkward at writing intros in the third person!

Logistics

Ask questions as they come up, this is meant to be interactive! ✋

Objectives:

Understand what quarto is
Learn how to create new projects for ALL the content types
Explore the bells and whistles to take it to the next level
(Not-so-hidden agenda: Plant the seeds for other best practices for reproduceable reporting)

Acknowledgements

🫶

“Artwork from”Hello, Quarto” keynote by Julia Lowndes and Mine Çetinkaya-Rundel, presented at RStudio Conference 2022. Illustrated by Allison Horst

What is Quarto?

Quarto is an open source scientific and technical publishing framework. Use your favorite languages to create versatile, beautiful, and reproducible outputs.

Open source project sponsored by Posit, based on 10+ years of experience with RMarkdown
Re-imagining of rmarkdown to be completely language agnostic (with inspiration from jupyter notebooks)

“Artwork from”Hello, Quarto” keynote by Julia Lowndes and Mine Çetinkaya-Rundel, presented at RStudio Conference 2022. Illustrated by Allison Horst

How it works

Quarto gives you options for the actual tool being used to render your project into a plethora of output types.

Choice of rendering engines: jupyter, knitr
Computational languages: Python, R, Julia, Observable JS
Outputs: Documents, presentations, websites, books, blogs

Bundled into RStudio starting with 2022.07.1

“Artwork from”Hello, Quarto” keynote by Julia Lowndes and Mine Çetinkaya-Rundel, presented at RStudio Conference 2022. Illustrated by Allison Horst

Getting started

Programmatically create a project:

quarto create project
quarto create project <type> <name>

Create a project using the RStudio editor:

Anatomy of a Quarto project

---
title: "Untitled"
format: html
editor: visual
---

## Quarto

Quarto enables you to weave together content and executable 
code into a finished document. To learn more about Quarto 
see <https://quarto.org>.

When you click the **Render** button a document will be 
generated that includes both content and the output of 
embedded code. You can embed code like this:

```{r}

#| echo: false

1 + 1

```

YAML - define the format, theme

Markdown - language between sections will be processed as Quarto markdown syntax.

Code block - include live computations. Execution options are added to the top of the block with #|, for example #| echo: true to include code in the rendered article.

Rendering

Knitr engine:

Jupyter engine:

Coming from R? RMarkdown Workflow

Rendering (execute and write to disk):

Programmatically

quarto render script.qmd

The RStudio editor comes with rendering built-in:

Live preview:

quarto preview script.qmd

Coming from Python? Notebooks Workflow

Rendering (execute and write to disk):

# plain text qmd
quarto render python.qmd
quarto render python.qmd --to pdf

# ipynb notebook
quarto render python.ipynb
quarto render python.ipynb --execute

Live preview:

# plain text qmd
quarto preview python.qmd
quarto preview python.qmd --to pdf

# ipynb notebook
quarto preview python.ipynb
quarto preview python.ipynb --execute

The different content types

Report / Document / Book
- HTML doc
- PDF doc
- Word doc
Presentation
Website / Blog
- The home page is a listing page for all of the documents in the posts directory
Dashboard 🆕
Email 🆕

Make ALL the content types!

Creating a Quarto Document

---
title: "Temperature and ozone level"
author: "Norah Jones"
date: "5/22/2021"
format: 
  html:
    fig-width: 8
    fig-height: 4
    code-fold: true
---

## Air Quality

```{r}
#| label: fig-airquality
#| warning: false

library(ggplot2)
ggplot(airquality, aes(Temp, Ozone)) + 
  geom_point() + 
  geom_smooth(method = "loess")
```

Learn more about all the html options here

Publish it with the Quarto CLI:

quarto publish connect
 ? Server URL: › https://connect.example.com/
 ? API Key: ›

Publish it through RStudio:

Creating a Quarto Presentation

Example code:

---
title: "Habits"
author: "John Doe"
format: revealjs
---

## Getting up

- Turn off alarm
- Get out of bed

## Going to sleep

- Get in bed
- Count sheep

Learn more here

Publish it with the Quarto CLI:

quarto publish connect
 ? Server URL: › https://connect.example.com/
 ? API Key: ›

Publish it through RStudio:

Creating a Quarto Website

Create the website:

quarto create project website mysite

Website layout is defined through a seperate _quarto.yml file:

project:
  type: website

website:
  title: "today"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd

format:
  html:
    theme: cosmo
    css: styles.css
    toc: true

Learn more here

Publish it with the Quarto CLI:

quarto publish connect
 ? Server URL: › https://connect.example.com/
 ? API Key: ›

Publish it through RStudio:

Creating a Quarto Email 🆕

Example code:

---
title: Something wonderful
format: email
---

::: {.email}

::: {.subject}
Alert
:::

Water the plants
:::

Learn more here

Publish it with the Quarto CLI:

quarto publish connect
 ? Server URL: › https://connect.example.com/
 ? API Key: ›

Publish it through RStudio:

Creating a Quarto Dashboard 🆕

Example code:

---
title: "Diamonds Explorer"
author: "Hello Quarto"
format: dashboard
---

## Row {height=60%}

Here's a widget block, and 
can include live code!

## Row {height=40%}

Here's a widget block, and 
can include live code!

Learn more here

Publish it with the Quarto CLI:

quarto publish connect
 ? Server URL: › https://connect.example.com/
 ? API Key: ›

Publish it through RStudio:

Things have gone wrong, help!

Capture the current system to see if anything looks off / submit a git issue or stackoverflow that will give folks enough info to be able to meaningfully help you:

sessionInfo()
Sys.getenv()
.libPaths()

# If the sessioninfo package is available, 
# it provides output that is easier to read,
# and can write its results to a file
sessioninfo:::session_info(to_file = "quarto-session-info-output.txt")

Get more diagnostics while running a command:

quarto render hello.qmd --to html --execute-debug

Misc best practices

Version control your code

Reproduceable environments

Keep secrets secret

Imagine a world where code doesn’t disappear and is backed up in version control, environments are explicit and easily reproduced, and secrets are responsibly managed.

“It’s Dangerous to go Alone! Take This” is a memorable quote from the 1986 action-adventure Nintendo game The Legend of Zelda. Online, the expression is typically used as a stock caption for image macros in which an animal or an object is offered to the viewer as a kind gesture.

On to the bells and whistles!

There’s a lot to love 💙

Dashboards
Emails
Interactive reports
Code chunks
Custom formatting
Hybrid code projects
Extensions
Comments
Scheduling
Publishing

Programmatic formatting
Parameterization
Conditionals
Including code / nested qmd’s
Environment management
Version control
Storing secrets in env variables

Image a meme of The Sound of Music

Quarto Resources

Quarto

Documentation
Cheat sheet
Reproduceable presentations in quarto
Quarto awesome list
Quarto the definitive guide
R without statistics, reproduceable reporting with quarto
Quarto tip a day
Quarto callouts
Thomas Mock’s presentation to Austin Python meetup in 2024
Parameterized Reports with Quarto: R-Ladies DC Workshop
Extending quarto

Workshops and talks from posit:::conf(2023):

Upcoming Workshops for posit:::conf(2024)

Build-a-Dashboard Workshop (with Quarto, R and/or Python)
Introduction to Quarto
Quarto Websites

Interested in our Enterprise Products? Click here

Best Practices Resources

Version control:

Cheat sheet for git (contributed): https://rstudio.github.io/cheatsheets/contributed-cheatsheets.html
What They Forgot to Teach You About R : https://rstats.wtf/
Happy Git with R : https://happygitwithr.com/
Oh sh-t git: https://ohshitgit.com/
Cheat sheet for git (contributed): https://rstudio.github.io/cheatsheets/contributed-cheatsheets.html
Missing semester of your CS education on version control: https://missing.csail.mit.edu/2020/version-control/
Learn git branching: https://learngitbranching.js.org/

Environment management:

Get started with renv in the RStudio IDE: https://docs.posit.co/ide/user/ide/guide/environments/r/renv.html
You should be using renv: https://www.youtube.com/watch?v=GwVx_pf2uz4
Using Public Package Manager : https://support.rstudio.com/hc/en-us/articles/360046703913-FAQ-for-RStudio-Public-Package-Manager

Secrets:

Environment variables on Connect: https://docs.posit.co/connect/user/content-settings/#content-vars

Interested in our Enterprise Products? Click here

Thanks! Questions?

Backup

Default Slide

This text size is normal.

This text size is smaller.

Bullet points

Point 1
Point 2

Blocking comment

Column 1

Link to external resource

Column 2

Lisa Anders - Posit Solutions Engineer and self-professed R nerd learning to love Python. Engineer turned data scientist turned Posit admin and excited to share lessons learned the hard way to make things easier for others. Also awkward at writing intros in the third person!

“Illustration from Hadley Wickham’s talk”The Joy of Functional Programming (for Data Science).” by Allison Horst

So you’ve got a finished product, now what? Publish to Connect

So you’ve got a finished product, now what? Job scheduling

Image from Ryan Johnson’s companion GitHub repository for the June 2023 Posit Team Community demo