Hello Quarto

From R Markdown to Quarto

Andrew Bray

UC Berkeley

Mine Çetinkaya Rundel

Duke University + Posit

While you wait for the workshop to begin, be sure you’ve got all the tools needed for the workshop:


https://andrew.quarto.pub/alaska-asa


In addition, please download and open the exercises for this session:

usethis::use_course("https://tinyurl.com/alaska-asa")

Code of Conduct

The American Statistical Association (ASA) is committed to providing an atmosphere in which personal respect and intellectual growth are valued and the free expression and exchange of ideas are encouraged. Consistent with this commitment, it is the policy of the ASA that all participants in ASA activities enjoy a welcoming environment free from unlawful discrimination, harassment, and retaliation. We strive to be a community that welcomes and supports people of all backgrounds and identities. This includes, but is not limited to, members of any race, ethnicity, culture, national origin, color, immigration status, social and economic class, educational level, sex, sexual orientation, gender identity and expression, age, size, family status, political belief, religion, and mental and physical ability.

Expected Behavior

  • Model and support the norms of respect necessary to promote the conditions for healthy exchange of scientific ideas.

  • In speech or conduct, do not insult or disparage other participants.

  • Be conscious of hierarchical structures, specifically the existence of stark power differentials between students, early career statisticians and established career statisticians—noting that fear of retaliation from more established statisticians can make it difficult for students and early career statisticians to express discomfort, rebuff unwelcome advances, and report violations of the conduct policy.

  • Be sensitive to indications that may suggest that individuals are feeling unwelcome.

About me

  • Associate Teaching Professor
    Department of Statistics
    UC Berkeley
  • R Markdown user for 10+ years
  • Quarto user for 1+ years

About you

Please share:

  • Name
  • Professional affiliaton
  • What do you use R and R Markdown for?
02:00

Meeting you where you are

These materials are pitched at someone who:

  • knows some R + Markdown

  • has worked in RStudio

  • wants to learn about Quarto

I’ll teach you

  • More Markdown

  • New Quarto formats

  • New Quarto projects

Workshop structure

  • My turn: Lecture segments + live coding

  • Our turn: Live coding + follow along

  • Your turn: Exercises

Checking in one more time

1. Software: Download and install the latest versions of R, RStudio, and Quarto:

2. R Packages: Install the following packages:

pkg_list <- c("tidyverse", "gt", "ggthemes", "palmerpenguins", 
              "quarto", "here", "usethis")
install.packages(pkg_list)

3. Exercises: Download and open the exercises for this session. The easiest way is to run this line of R code at the console in RStudio.

usethis::use_course("https://tinyurl.com/alaska-asa")

Let’s get started!

What is Quarto?

Quarto …

  • is a new, open-source, scientific, and technical publishing system.
A schematic representing the multi-language input (e.g. Python, R, Observable, Julia) and multi-format output (e.g. PDF, html, Word documents, and more) versatility of Quarto.

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

Quarto

With Quarto you can weave together narrative text and code to produce elegantly formatted output as documents, web pages, blog posts, books and more.


just like R Markdown…


but not just like it, there’s more to it…

Quarto unifies + extends R Markdown

  • Consistent implementation of attractive and handy features across outputs: tabsets, code-folding, syntax highlighting, etc.
  • More accessible defaults as well as better support for accessibility
  • Support for other languages like Python, Julia, Observable, and more via Jupyter engine for executable code chunks.

A tour of Quarto



Sit back and enjoy!

Your turn

Open hello-penguins.qmd in RStudio and with the visual editor . . .

  1. Render the document.
  2. Update your name and re-render.
  3. Inspect components of the document and make one more update and re-render.
  4. Compare notes with neighbors about updates you’ve made and note any aspects of the document that are not clear after the tour and your first interaction with it.
10:00

How it Works

Introducing the Quarto CLI

Revisit: What is Quarto?

Quarto is a command line interface (CLI) that renders plain text formats (.qmd, .rmd, .md) OR mixed formats (.ipynb/Jupyter notebook) into static PDF/Word/HTML reports, books, websites, presentations and more.

andrewbray$ quarto --help

  Usage:   quarto 
  Version: 1.3.340

  Description:

    Quarto CLI

  Options:

    -h, --help     - Show this help.                            
    -V, --version  - Show the version number for this program.  

  Commands:

    render          [input] [args...]     - Render files or projects to various document types.        
    preview         [file] [args...]      - Render and preview a document or website project.          
    serve           [input]               - Serve a Shiny interactive document.                        
    create          [type] [commands...]  - Create a Quarto project or extension                       
    create-project  [dir]                 - Create a project for rendering multiple documents          
    convert         <input>               - Convert documents to alternate representations.            
    pandoc          [args...]             - Run the version of Pandoc embedded within Quarto.          
    run             [script] [args...]    - Run a TypeScript, R, Python, or Lua script.                
    add             <extension>           - Add an extension to this folder or project                 
    install         [target...]           - Installs an extension or global dependency.                
    publish         [provider] [path]     - Publish a document or project. Available providers include:
    check           [target]              - Verify correct functioning of Quarto installation.         
    help            [command]             - Show this help or the help of a sub-command.

Under the hood

  • knitr or jupyter evaluates R/Python/Julia code and returns a .md file along with the evaluated code
  • Quarto applies Lua filters + CSS/LaTeX which is then evaluated alongside the .md file by Pandoc and converted to a final output format

Aside: Lua filters

return {
  {
    Strong = function (elem)
      return pandoc.SmallCaps(elem.c)
    end,
  }
}
  • Lua filters written by R/Python/Julia developers should be interchangeable between formats - not language specific!
  • We won’t go into the details of writing Lua filters in this workshop, and you don’t need to worry about learning about Lua filters unless you’re working on extending Quarto.

From the comfort of your own homeworkspace

A screenshot of a Quarto document rendered inside RStudio

A screenshot of a Quarto document rendered inside JupyterLab

A screenshot of a Quarto document rendered inside VSCode

Rendering

  1. Option 1: In RStudio with as a background job, and preview the output.
  1. Option 2: In the Terminal via quarto render:
quarto render document.qmd # defaults to html
quarto render document.qmd --to pdf
quarto render document.qmd --to docx
  1. Option 3: In the R console, via the quarto R package:
library(quarto)

quarto_render("document.qmd") # defaults to html
quarto_render("document.qmd", output_format = "pdf")

Your turn

  • Open the last .qmd file you were working on in RStudio.
  • Compare behavior of rendering with
    • RStudio > Render,
    • using the CLI with quarto render, and
    • in the R console via quarto_render().
  • If you’re an RStudio user, brainstorm why you might still want to know about the other two ways of rendering Quarto documents.
03:00

Quarto formats

One install, “Batteries included”

  • RMarkdown grew into a large ecosystem, with varying syntax.

  • Quarto comes “batteries included” straight out of the box

    • HTML reports and websites
    • PDF reports
    • MS Office (Word, Powerpoint)
    • Presentations (Powerpoint, Beamer, revealjs)
    • Books
  • Any language, exact same approach and syntax

Many Quarto formats

Feature R Markdown Quarto
Basic Formats

html_document

pdf_document

word_document

html

pdf

docx
Beamer beamer_presentation beamer
PowerPoint powerpoint_presentation pptx
HTML Slides

xaringan

ioslides

revealjs

 revealjs
Advanced Layout

tufte

distill

 Quarto Article Layout

Many Quarto formats

Feature R Markdown Quarto
Cross References

html_document2

pdf_document2

word_document2

 Quarto Crossrefs
Websites & Blogs

blogdown

distill

Quarto Websites

Quarto Blogs
Books bookdown Quarto Books
Interactivity Shiny Documents Quarto Interactive Documents
Journal Articles rticles Journal Articles
Dashboards flexdashboard Coming soon!

Your turn

In RStudio, go to File > New File > Quarto document to create a Quarto document with HTML output. Render the document, which will ask you to give it a name – you can use my-first-document.qmd.

Use the visual editor for the next steps.

  • Add a title and your name as the author.

  • Create two sections, one with things you would like to use Quarto for and a second with your favorite thing about R.

  • Add a table of contents.

  • Stretch goal: Change the html theme to sketchy.

05:00

Wrap up

What about R Markdown?

  • You can render existing R Markdown documents with Quarto and you can rename them to .qmd files to turn them into Quarto documents.

  • You don’t have to do this – R Markdown continues to be maintained.

  • However, Quarto

    • Offers “batteries included” shared syntax across formats

    • Allows you to choose your own editor and your preferred data science language

    • Comes with richer features out of the box

    • Is actively developed

Questions

Any questions / anything you’d like to review before we wrap up this module?

One last thing!

Where does the name “Quarto” come from?

andrew.quarto.pub/alaska-asa