Setup instructions

Reproducible publishing with Quarto

Dr. Mine Çetinkaya-Rundel

Duke University

Posit, PBC

Dr. Charlotte Wickham

Posit, PBC

2024-08-04

Setup instructions

While you wait for the workshop to begin…

bit.ly/quarto-jsm24

Option 1: (Cloud - Recommended)

Go to https://bit.ly/quarto-jsm24-cloud, create an account, and join the workspace.

Option 2: (Local)

Welcome

Logistics

  • WiFi: JSM2024 / Password: abbvie24

  • Exits: 2 in the back, 1 in the front of the room

  • Restrooms: Out the hallway, to the right

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 us

Mine Çetinkaya-Rundel

mine-cr.com

Professor of the Practice, Department of Statistical Science, Duke University

Developer Educator, Posit

Charlotte Wickham

cwick.co.nz

Developer Educator, Posit

R Markdown user/educators for 10+ years

Quarto user/educators for 3+ years

About you

Please share with the person next to you…

  • Your name
  • Your professional affiliation
  • What you hope to get out of this tutorial
03:00

Workshop structure

My turn

  • Lecture segments
  • Feel free to just watch, take notes, browse docs, or tinker around with the code

Our turn

  • Lecture segments + live coding
  • (Optionally) follow along with live coding

Your turn

  • Practice exercises for you
  • Work on your own or with the person next to you

Schedule

Time Module
08:30 - 10:15 From R Markdown to Quarto
10:15 - 10:30 Break
10:30 - 12:30 Creating computational documents and slides with Quarto
12:30 - 14:00 Lunch
14:00 - 15:15 Creating websites and books with Quarto
15:15 - 15:30 Break
15:30 - 17:00 Authoring manuscripts with Quarto

Getting help

Just raise your hand!

Hello Quarto

Meeting you where you are

I’ll assume you

  • know some R

  • have worked in RStudio

  • want to learn about Quarto

I’ll teach you

  • Quarto syntax and formats

  • More Markdown

  • Even more R along the way!

Checking in one more time

Have you completed the following?

Option 1: (Cloud - Recommended)

Go to https://bit.ly/quarto-jsm24-cloud, create an account, and join the workspace.

Option 2: (Local)

Let’s get started!

What is Quarto?

Quarto …

  • is a new, open-source, scientific, and technical publishing system
  • aims to make the process of creating and collaborating dramatically better
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 the R Markdown ecosystem

Quarto …

unifies + extends the R Markdown ecosystem


unifies for people who love R Markdown

Quarto …

unifies + extends the R Markdown ecosystem


unifies for people who love R Markdown

extends for people who don’t know R Markdown

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
  • Guardrails, particularly helpful for new learners: YAML completion, informative syntax errors, etc.
  • 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! … or follow along with hello-penguins.qmd.

  • Running individual cells
  • Rendering a document
  • Editing with source editor and visual editor
  • Inserting images and lightbox effect
  • Inserting tables
  • Customizing formats: pdf, docx, revealjs
  • Customizing format options: code-fold, toc
  • Code cells: labels, alt-text, execution options (echo, warning)
  • Cross referencing figures and tables, with and without the visual editor

Your turn

Option 1: Start the project 1-rmarkdown-quarto.

Option 2: Launch the project in 1-rmarkdown-quarto.

  • Open hello-penguins.qmd in RStudio and with the visual editor.
  • Render the document.
  • Update your name and re-render.
  • Inspect components of the document and make one more update and re-render.
  • 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.
05:00

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.

mine$ quarto --help

Usage:   quarto
Version: 1.5.56

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               
  use        <type> [target]       - Automate document or project setup tasks.          
  add        <extension>           - Add an extension to this folder or project         
  update     [target...]           - Updates an extension or global dependency.         
  remove     [target...]           - Removes an extension.                              
  convert    <input>               - Convert documents to alternate representations.    
  pandoc     [args...]             - Run the version of Pandoc embedded within Quarto.  
  typst      [args...]             - Run the version of Typst embedded within Quarto.   
  run        [script] [args...]    - Run a TypeScript, R, Python, or Lua script.        
  install    [target...]           - Installs a global dependency (TinyTex or Chromium).
  uninstall  [tool]                - Removes an extension.                              
  tools                            - Display the status of Quarto installed dependencies
  publish    [provider] [path]     - Publish a document or project to a provider.       
  check      [target]              - Verify correct functioning of Quarto installation. 
  help       [command]             - Show this help or the help of a sub-command.

Quarto, more than just knitr

We learned from 10 years of literate programming with knitr + rmarkdown

Quarto, more than just knitr

Quarto: More than just knitr

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 JupyterLab

A screenshot of a Quarto document rendered inside VSCode

A screenshot of a Quarto document rendered inside RStudio

A screenshot of a Quarto document rendered inside Positron

Quarto workflow

Rendering a Quarto file in RStudio via the Render button calls quarto render in a background job, preventing Quarto rendering from cluttering up the R console, and gives you and easy way to stop:

Rendering

  1. Option 1: In RStudio 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

Option 1: Start the project 1-rmarkdown-quarto.

Option 2: Launch the project in 1-rmarkdown-quarto.

  • 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::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”

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

    • HTML reports and websites

    • PDF reports

    • MS Office (Word, Powerpoint)

    • Presentations (Powerpoint, Beamer, revealjs)

    • Books

    • Manuscripts

    • …

  • Any language, exact same approach and syntax

Many Quarto formats

Feature Quarto
Basic Formats html, pdf, docx, typst
Beamer beamer
PowerPoint pptx
HTML Slides revealjs
Advanced Layout Quarto Article Layout
Cross References Quarto Crossrefs
Websites & Blogs Quarto Websites, Quarto Blogs
Books Quarto Books
Interactivity Quarto Interactive Documents
Journal Articles Journal Articles
Dashboards Quarto Dashboards

Your turn

Option 1: Start the project 1-rmarkdown-quarto.

Option 2: Launch the project in 1-rmarkdown-quarto.

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 fact you want to learn and 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, new features are being developed for Quarto.

  • Additionally, Quarto

    • Offers “batteries included” shared syntax across formats

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

    • Comes with richer and more accessible 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?

🔗 bit.ly/quarto-jsm24