R/Medicine: Introduction to Quarto

J.J. Allaire (RStudio, PBC)

August 25th, 2022

What is Quarto?

Quarto is the next generation of R Markdown

Quarto Overview

https://quarto.org

Quarto is an open-source scientific and technical publishing system that builds on standard markdown with features essential for scientific communication.

  • Computations: Python, R, Julia, Observable JS
  • Markdown: Pandoc w/ many enhancements
  • Output: Documents, presentations, websites, books, blogs

Literate programming system in the tradition of Org-mode, Sweave, Weave.jl, R Markdown, iPyPublish, Jupyter Book, etc.

Origins

  • Open source project sponsored by RStudio, PBC.
  • 10 years of experience with R Markdown (a similar system that was R-specific) convinced us that the core ideas were sound.
  • The number of languages and runtimes used for scientific discourse is very broad.
  • Quarto is a ground-up re-imagining of R Markdown that is fundamentally multi-language and multi-engine.

Goal: Computational Documents

  • Documents that incorporate the source code required for their production
  • Notebook and plain text flavors
  • Automation and reproducibility

Goal: Scientific Markdown

Goal: Single Source Publishing

https://coko.foundation/articles/single-source-publishing.html

Why a New System?

  • The number of languages and runtimes used for scientific discourse is very broad (and the Jupyter ecosystem in particular is extraordinarily popular).
  • Quarto is at its core multi-language and multi-engine (supporting Knitr, Jupyter, and Observable today and potentially other engines tomorrow).
  • On the other hand, R Markdown is heavily tied to R which limits the number of peoople it can benefit.
  • Quarto is RStudio’s attempt to bring R Markdown to everyone!

Quarto Engines

  • Knitr
  • Jupyter
  • Observable JS
  • Others possible…

Knitr Engine

For R, Quarto still uses Knitr under the hood. Consequently, the vast majority of existing Rmd files can be rendered unmodified.

Note that the standard syntax for chunk options has changed (old syntax still works):

```{r}
#| echo: false
#| fig-cap: "Cars"
plot(cars)
```

Knitr Engine

Jupyter Engine — ipynb

The Jupyter engine supports the use of Python, Julia, and any other language that has a Jupyter kernel.

Jupyter supports two input file formats:

  • Traditional notebooks (.ipynb)
  • Markdown w/ chunks (.qmd)

Hello Jupyter: https://quarto.org/#hello-quarto

Jupyter Engine: ipynb

You can also render Jupyter notebooks (.ipynb files) directly. Note that in this case no execution occurs by default:

Jupyter Engine: Tooling

Side-by-side preview for JupyterLab, VS Code, Emacs, etc.:

$ quarto preview notebook.ipynb

Observable JS

Quarto includes native support for Observable JS, a set of enhancements to vanilla JavaScript created by Mike Bostock (also the author of D3).

Observable JS is distinguished by its reactive runtime, which is especially well suited for interactive data exploration and analysis.

Demo: https://quarto.org/docs/interactive/ojs/#example

Shared Core Syntax

Core features have similar expression across formats:

  • Code folding

  • Tabsets

  • Theming

  • Anchor links

R Markdown

The R Markdown ecosystem was built over nearly a decade (resulting in lots of inconsistency & duplication)

Packages
  • tufte
  • rticles
  • revealjs
  • xaringan
  • bookdown
  • blogdown
  • distill
Features
  • Floating TOC
  • Code folding / copying
  • Syntax highlighting
  • Page layout
  • Theming
  • Tabsets
  • Section anchors

Code folding / copying

Code
```{r}
#| code-fold: true

library(ggplot2)
dat <- data.frame(cond = rep(c("A", "B"), each=10),
                  xvar = 1:20 + rnorm(20,sd=3),
                  yvar = 1:20 + rnorm(20,sd=3))

ggplot(dat, aes(x=xvar, y=yvar)) +
    geom_point(shape=1) + 
    geom_smooth() 
```

Tabsets

fizz_buzz <- function(fbnums = 1:50) {
  output <- dplyr::case_when(
    fbnums %% 15 == 0 ~ "FizzBuzz",
    fbnums %% 3 == 0 ~ "Fizz",
    fbnums %% 5 == 0 ~ "Buzz",
    TRUE ~ as.character(fbnums)
  )
  print(output)
}
def fizz_buzz(num):
  if num % 15 == 0:
    print("FizzBuzz")
  elif num % 5 == 0:
    print("Buzz")
  elif num % 3 == 0:
    print("Fizz")
  else:
    print(num)

Tabset syntax: https://quarto.org/docs/output-formats/html-basics.html#tabsets

Theming

Universal themeing system (based on SCSS) for all HTML output formats (shared by HTML and RevealJS slides, extendable to work with anything).

Based on core variables defined by bslib (so fully compatible with Shiny, Flexdashboard, & R Markdown themes).

Sample theme file: https://quarto.org/docs/output-formats/html-themes.html#theme-options

New Features

  • Cross references
  • Advanced layout
  • Figure/layout panels
  • Callouts
  • Diagrams
  • Extensions
  • YAML intelligence
  • Publishing

Cross References

Cross reference figures, tables, equations, sections, theorems, etc.

Plain markdown: https://quarto.org/docs/authoring/cross-references.html#subfigures

Knitr/Jupyter: https://quarto.org/docs/authoring/cross-references.html#computations

Advanced layout

https://quarto.org/docs/authoring/article-layout.html

Advanced article layout features inspired by Tutfe, Distill, and Hugo Prose.

  • Figures and tables that span the entire page
  • Use of margin for figures, equations, captions, asides, footnotes, and citations
  • Responsive show/hide of site navigation and TOC
  • Examples: HTML, PDF

Figure/Layout Panels

::: {layout="[[40,-20,40], [100]]"}
![Surus](surus.png)
![Hanno](hanno.png)
![Lin Wang](lin-wang.png)
:::

Callouts

Work in HTML, PDF, MS Word, and ePub output

Diagrams

Quarto has native support for embedding Mermaid and Graphviz diagrams.

```{mermaid}
flowchart LR
  A[Hard edge] --> B(Round edge)
  B --> C{Decision}
  C --> D[Result one]
  C --> E[Result two]
```

Quarto Extensions

https://quarto.org/docs/extensions/

  • Shortcodes are special markdown directives that generate various types of content. For example, you could create shortcodes to embed tweets or videos in a document.

  • Filters are a flexible and powerful tool for introducing new global behaviors and/or new markdown rendering behaviors.

  • Formats enable you to create new output formats by bundling together document options, templates, stylesheets, and other content.

YAML Intelligence

  • YAML code completion for config files, front matter, and chunk options
  • Real-time diagnostics and clear errors at render time for invalid YAML

Completion

Diagnostics

Publishing

https://quarto.org/docs/publishing/

Integrated quarto publish command that targets a variety of services:
 

Quarto Pub Free publishing service ideal for blogs, course or project websites, books, presentations, and personal hobby sites.
GitHub Pages Publish content based on source code managed within a GitHub repository.
RStudio Connect Publishing platform for secure sharing of data products within an organization.
Netlify Professional web publishing platform with many advanced features including custom domains and authentication.
Other Services Content rendered with Quarto uses standard formats (HTML, PDFs, MS Word, etc.) that can be published anywhere.

Advanced Formats

  • Websites

  • Books

  • Blogs

  • Presentations

  • Journal Articles

Quarto Websites

  • Arbitrary content depth / organization

  • Multi-level navigation (navbar / sidebar / hybrid)

  • Full text search (client side or Algolia)

  • Freezing computational output

  • Examples: https://quarto.org/docs/gallery/#websites

Quarto Books

  • Inherit features of Quarto websites (navigation, search, etc.)
  • Support cross references across chapters
  • Formats include HTML, PDF, MS Word, and ePub
  • Examples: https://quarto.org/docs/gallery/#books

Quarto Blogs

Quarto Presentations

https://quarto.org/docs/presentations/revealjs/demo/

  • Based on a (heavily customized) version of RevealJS:
    • Image, video, and iframe backgrounds
    • PDF Printing
    • Speaker view
    • Plugin system
  • Many features inspired by xaringanExtra:
    • Chalkboard / drawing on slides
    • Multicast (synced presenter / viewer slides)
    • Slide tone (for accessibility)
    • Absolute positioning of slide elements

Quarto Journals

https://quarto.org/docs/journals/

Custom format system designed to accomodate the creation of articles for publishing in professional Journals:

  • The ability to flexibly adapt the native LaTeX templates provided by Journals for use with Pandoc.

  • The use of spans and divs to apply formatting (which enables targeting by CSS for HTML output and LaTeX macros/environments for PDF output).

  • A standardized schema for authors and affiliations so that you can express this data once and then have it automatically formatted according to the styles required for various Journals.

  • The use of Citation Style Language (CSL) to automate the formatting of citations and bibliographies according to whatever style is required by various Journals.

Example: https://quarto-journals.github.io/jss/

Quarto Tools

  • Quarto CLI

  • RStudio IDE

  • VS Code Extension

  • Jupyter Lab

  • Text Editors

  • Visual Editor

Quarto CLI

Core component that drives Quarto rendering. This is the only thing you need to render plain markdown (it includes Pandoc 2.18).

  • Add knitr to render documents w/ R
  • Add jupyter to render with Jupyter kernels

Like git, this is a system level compontent that is used by RStudio, VS Code, Jupyter Lab, terminal sessions, etc.

Download/install: https://quarto.org/docs/get-started/

RStudio IDE

Current release of RStudio IDE has Quarto tooling on-par w/ R Markdown tooling

VS Code Extension

https://quarto.org/docs/tools/vscode.html

  • Render command with integrated preview pane
  • Syntax highlighting for markdown and embedded languages
  • Completion for embedded languages (e.g. Python, R, Julia, LaTeX, etc.)
  • Completion and diagnostics for project files and document/cell options
  • Completion for citations and cross references
  • Commands and key-bindings for running cells and selected line(s)
  • Automatic navigation to render errors for Jupyter, Knitr, and YAML
  • Live preview for embedded mermaid and graphviz diagrams
  • Assist panel for contextual help, image preview, and math preview
  • Code snippets for common markdown constructs
  • Code folding and document outline for navigation within documents
  • Workspace symbol provider for navigation across project files

Jupyter Lab

Text Editors

Visual Editor

https://quarto.org/docs/visual-editor/

  • The Quarto visual editor provides a WYSIWYM editing interface for all of Pandoc markdown

  • Tables, citations, cross-references, footnotes, divs/spans, definition lists, attributes, raw HTML/TeX, etc.

  • Includes support for executing code cells and viewing their output inline.

Learning More

Slides: https://jjallaire.quarto.pub/rmedicine-introduction-to-quarto

Questions?