Documenting & Publishing with Quarto

CUNY Data 621 - Spring 2022

Author

Jeff Parks

Quarto

Quarto (quarto.org) is a open-source publishing solution developed by Posit, the makers of RStudio. Originally heralded as the “next generation” R Markdown format, Quarto has evolved into a multi-language technical publishing system that can handle everything from code notebooks to websites, books and presentations.

One of the most attractive features of Quarto is the flexibility and control over layout, and the relative simplicity of setting up well-formatted graphs and plots, margin content, citations, and other features for publication-ready outputs.

While my main use case for Quarto has been HTML and PDF outputs of class projects in R, it fully supports the Python and Julia languages, Jupyter Notebooks and Observable.

The Basics

This quick intro will focus on Quarto as a drop-in replacement for R Markdown in RStudio. After following the installation instructions for your environment, you’ll be able to select Quarto Document in the File > New File dialog, which creates a markdown file in .qmd format.

Just like .Rmd files, markdown syntax is used for body text and a YAML header section (identified by triple-dashes) defines metadata and document-wide settings, such as:

---
title: "My Title"
subtitle: 'My Subtitle'
author: "My Name"
format:
  html:
    theme: journal
page-layout: article
editor: visual
toc: true
---

And just like R Markdown, executable code chunks can be defined with a wide variety of configurable options. These chunk options are defined by ‘hashpipe’ #| comments in the chunk body:

#| label: scatterplot
#| fig-cap: "Figure 1: City and highway mileage for 38 popular models of cars."
#| fig-alt: "Scatterplot of city vs. highway mileage for cars..."
#| fig-link: "https://archive.ics.uci.edu/ml/datasets/auto+mpg"
#| fig-width: 6
#| fig-height: 3.5
#| fig-align: center
#| cap-location: margin

ggplot (mpg, aes (x = hwy, y = cty, color = cyl)) +
geom_point (alpha = 0.5, size = 2) +
scale_color_viridis_c() +
theme_minimal()

Scatterplot of city vs. highway mileage for cars... — Figure 1: City and highway mileage for 38 popular models of cars.

Quarto also helps separate the code and presentation layers of our document – without having to alter our ggplot() function, we can control the plot’s size and orientation, apply labels and even hyperlinks using the chunk options!

Layout Control

One of the most useful features for a typical, plot-rich project is fine-tuned control over page layout, including flexible rows and columns. This allows you to fit a lot more information into a smaller amount of page space.

Here’s simple example of a dynamic side-by-side layout of two plots. Without specifying figure dimensions, simply use layout-ncol to define two columns, and the plots dynamically resize to fit, with independent subcaptions.

#| label: fig-mpg
#| fig-cap: "City and highway mileage for 38 popular models of cars."
#| fig-subcap:
#|   - "Number of Cylinders"
#|   - "Engine Displacement"
#| layout-ncol: 2
#| cap-location: margin

ggplot(mpg, aes(x = hwy, y = cty, color = cyl)) +
  geom_point(alpha = 0.5, size = 2) +
  scale_color_viridis_c() +
  theme_minimal()

ggplot(mpg, aes(x = hwy, y = cty, color = displ)) +
  geom_point(alpha = 0.5, size = 2) +
  scale_color_viridis_c(option = "E") +
  theme_minimal()

So Many Features

There are too many options to detail here, but this is one of my favorites:

Tufte-style Margins

City and highway mileage for 38 popular models of cars.

A tremendous space-saver, the column: margin option publishes chunk outputs in the right margin of the document – a style made famous by statistician Edward Tufte.

#| fig-cap: "City and highway mileage for 38 popular models of cars."
#| column: margin

ggplot (mpg, aes (x = hwy, y = cty, color = cyl)) +
geom_point (alpha = 0.5, size = 2) +
scale_color_viridis_c() +
theme_minimal()

Margin Content

You may have noticed that Figure captions above are being published in the margin using the chunk option cap-location: margin. Other content such as tables and images can also be handled similarly:

manufacturer	model	displ	year
audi	a4	1.8	1999
audi	a4	1.8	1999
audi	a4	2.0	2008

#| column: margin

knitr::kable(
  mpg[1:3, 1:4]
)

Margin Figures Only

And using fig-column: margin, you can even specify figures only to appear in the margin, while other content appears alongside in the main body:

#| fig-column: margin

knitr::kable(
  mpg[1:6, 1:8]
)

ggplot (mpg, aes (x = hwy, y = cty, color = cyl)) +
geom_point (alpha = 0.5, size = 2) +
scale_color_viridis_c() +
theme_minimal()

manufacturer	model	displ	year	cyl	trans	drv	cty
audi	a4	1.8	1999	4	auto(l5)	f	18
audi	a4	1.8	1999	4	manual(m5)	f	21
audi	a4	2.0	2008	4	manual(m6)	f	20
audi	a4	2.0	2008	4	auto(av)	f	21
audi	a4	2.8	1999	6	auto(l5)	f	16
audi	a4	2.8	1999	6	manual(m5)	f	18

Margin References

Citations, Footnotes¹ and Asides can all be pushed into the right margin as well for improved readability.

¹ This is a footnote. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam leo orci, finibus et risus eu, cursus eleifend ante.

Let’s Get Started!

I hope this post inspires you to check out Quarto and get started making your data science projects and presentations even more beautiful!