Intro To Quarto

Alex Edwards
Zane Billings

Learning objectives:

  • Understand the basic components of a Quarto document.

Introduction

  • Quarto is a command line interface tool, not an R package.

  • Quarto unifies the functionality of many packages from the R Markdown ecosystem: rmarkdown, bookdown, distill, xaringan, etc. into a single consistent system.

  • Quarto -> native support for multiple programming languages like Python and Julia in addition to R

Where to find help

Why Quarto documents:

  • reproducible

  • support dozens of output formats: PDFs, Word files, presentations, and more.

3 main uses:

  1. Communication: focus on conclusions not code.
  2. Collaborating with other scientists (including future you!): conclusions and code.
  3. Environment in which to do data science.

Quarto basics

  • Quarto files have .qmd extension.

  • Contains 3 types of contents:

    • and optional YAML header surrounded by 3 dashes (—) at the beginning and end
    • chunks of R code surrounded by 3 back ticks (```)
    • text mixed with simple formatting like #heading or italics

Getting Started

  • To get started with your own .qmd file, select File > New File > Quarto Document… in the menu bar.

Run code in quarto

  • Run each code chunk by clicking the Run icon (each chunk will have this green arrow).

  • You can choose to have the plots and output displayed in the document or on RStudio’s console and plot panes. Go to the gear icon next to “Render” and switch to “Chunk Output Console”.

  • To run the complete report, click “Render” and your report will be displayed in the viewer pane as an HTML file (unless the YAML includes .pdf or other extension).

Visual editor

  • Visual editor -> use the buttons on the menu bar to insert images, tables, cross-references, etc. or you can use the catch-all ⌘ + / or Ctrl + / shortcut to insert just about anything.
  • The visual editor displays your content with formatting, but under the hood, it saves your content in plain Markdown and you can switch back and forth between the visual and source editors.

Source editor

  • The Source editor will feel familiar to those with experience writing R scripts or R Markdown documents.
  • Can also be useful for debugging any Quarto syntax errors since it’s often easier to catch these in plain text.
  • If you forget, you can get to a handy reference sheet with Help > Markdown Quick Reference.
## Text formatting

*italic* **bold** ~~strikeout~~ `code`

superscript^2^ subscript~2~

[underline]{.underline} [small caps]{.smallcaps}

## Headings

# 1st Level Header

## 2nd Level Header

### 3rd Level Header

## Lists

-   Bulleted list item 1

-   Item 2

    -   Item 2a

    -   Item 2b

1.  Numbered list item 1

2.  Item 2.
    The numbers are incremented automatically in the output.

## Links and images

<http://example.com>

[linked phrase](http://example.com)

![optional caption text](quarto.png){fig-alt="Quarto logo and the word quarto spelled in small case letters"}

## Tables

| First Header | Second Header |
|--------------|---------------|
| Content Cell | Content Cell  |
| Content Cell | Content Cell  |

Code chunks

  • To run code inside a Quarto document, you need to insert a chunk.
    1. The keyboard shortcut Cmd + Option + I / Ctrl + Alt + I.
    2. The “Insert” button icon in the editor toolbar.

Chunk label

Chunks can be given an optional label, e.g.

This has three advantages:

  1. Navigate to specific chunks using the drop-down code navigator in the bottom-left of the script editor:

  1. Graphics produced by the chunks will have useful names that make them easier to use elsewhere.

  2. You can set up networks of cached chunks to avoid re-performing expensive computations on every run.

Important!

  • Your chunk labels should be short but evocative and should not contain spaces.
  • We recommend using dashes (-) to separate words (instead of underscores, _) and no other special characters in chunk labels.
  • Use whatever name, except: setup, which is used for a specific reason.
  • Additionally, chunk labels cannot be duplicated.
  • Each chunk label must be unique.

Chunk options

  • Chunk output can be customized with options.

  • You can see the full list at https://yihui.org/knitr/options.

  • Each of these chunk options get added to the header of the chunk, following #|.

The main options are:

  • eval: false prevents code from being evaluated. And obviously if the code is not run, no results will be generated.

  • echo: false prevents code, but not the results from appearing in the finished file.

  • message: false or warning: false prevents messages or warnings from appearing in the finished file.

  • error: true causes the render to continue even if code returns an error. This is rarely something you’ll want to include in the final version of your report, but can be very useful to debug. The default, error: false causes rendering to fail if there is a single error in the document.

Inline code

  • There is one other way to embed R code into a Quarto document: directly into the text, with r inside back ticks.
    • For example, you can inline code include in between text and that will show a result.

The data frame iris has 150 rows.

Figures

  • The figures in a Quarto document can be embedded (e.g., a PNG or JPEG file) or generated as a result of a code chunk.

  • It’s best if plots have consistent width. To enforce this, set fig-width: 6 (6”) and fig-asp: 0.618 (the golden ratio) in the defaults. Then in individual chunks, only adjust fig-asp.

  • Control the output size with out-width and set it to a percentage of the body width of the output document. We suggest to out-width: “70%” and fig-align: center.

Figures

  • To put multiple plots in a single row, set the layout-ncol to 2 for two plots, 3 for three plots, etc. This effectively sets out-width to “50%” for each of your plots if layout-ncol is 2,

  • Great blog post by Thomas Lin Pedersen about controling plot scaling.

Tables

  • You can include two types of tables in a Quarto document:
    • markdown tables that you create directly in your Quarto document, or
    • tables generated as a result of a code chunk.

More on Tables Soon :)

YAML header

  • You can control many other “whole document” settings by tweaking the parameters of the YAML header. You might wonder what YAML stands for: it’s “YAML Ain’t Markup Language”
  • Be careful with the YAML!