Get Started with Quarto

species	island	bill_length	bill_depth	flipper_length	body_mass	sex
Adelie	Torgersen	39.1	18.7	181	3,750	MALE
Adelie	Torgersen	39.5	17.4	186	3,800	FEMALE
Adelie	Torgersen	40.3	18	195	3,250	FEMALE
Adelie	Torgersen	36.7	19.3	193	3,450	FEMALE
Adelie	Torgersen	39.3	20.6	190	3,650	MALE
Adelie	Torgersen	38.9	17.8	181	3,625	FEMALE
Adelie	Torgersen	39.2	19.6	195	4,675	MALE
Adelie	Torgersen	42	20.2	190	4,250
Adelie	Torgersen	37.8	17.1	186	3,300
Adelie	Torgersen	37.8	17.3	180	3,700
Adelie	Torgersen	41.1	17.6	182	3,200	FEMALE
Adelie	Torgersen	38.6	21.2	191	3,800	MALE
Adelie	Torgersen	36.6	17.8	185	3,700	FEMALE
Adelie	Torgersen	38.7	19	195	3,450	FEMALE
Adelie	Torgersen	42.5	20.7	197	4,500	MALE
Adelie	Torgersen	46	21.5	194	4,200	MALE
Adelie	Biscoe	37.8	18.3	174	3,400	FEMALE
Adelie	Biscoe	37.7	18.7	180	3,600	MALE
Adelie	Biscoe	35.9	19.2	189	3,800	FEMALE
Adelie	Biscoe	38.2	18.1	185	3,950	MALE
Adelie	Biscoe	38.8	17.2	180	3,800	MALE
Adelie	Biscoe	35.3	18.9	187	3,800	FEMALE
Adelie	Biscoe	40.6	18.6	183	3,550	MALE

VS Code

VS Code YAML

VS Code, YAML Intelligence

Jupyter/Jupyter Lab

Jupyter

quarto preview notebook.ipynb --to html

Jupyter YAML

Treat YAML as a “raw cell” in Jupyter - Jupyter doesn’t care about YAML, but it’s needed/used by Quarto

Quarto, for collaboration

contents:
  - datalake-extracts-dplyr-aws.rmd
  - data-cleaning-siuba.ipynb
  - python-r-handoff.ipynb  
  - computer-vision-r-torch.qmd

Quarto Publish

 terminal

quarto publish --help

  Usage:   quarto publish [provider] [path]
  Version: 1.0.36                          
                                           
  Description:
    Publish a document or project. Available providers include:
                                                               
     - Quarto Pub (quarto-pub)                                 
     - GitHub Pages (gh-pages)                                 
     - RStudio Connect (connect)                               
     - Netlify (netlify)

What about for Data Science at Work?

Use Quarto in RStudio Workbench (v2022.07.1) and RStudio Connect (v2022.07.0)!

One install, “Batteries included”

Quarto is bundled and comes pre-installed with RStudio v2022.07.1 and beyond!

RStudio 2022.07.1+554 'Spotted Wakerobin', July 25th, 2022 New: Update Quarto to 1.0.36

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 revealjs	revealjs
Advanced Layout	tufte distill	Quarto Article Layout

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
Paged HTML	pagedown	Summer 2022
Journal Articles	rticles	Summer 2022
Dashboards	flexdashboard	Fall 2022

What to do with my existing `.Rmd` or `.ipynb`?

For some of you - nothing changes! Keep using RMarkdown and Jupyter.

However, most existing .rmd or .ipynb can be rendered as-is via Quarto

 terminal

quarto render my-favorite.rmd --to html

Since Jupyter notebooks can either be treated as a linear document to be re-executed or an already evaluated document there are additional options like: --execute

 terminal

quarto render my-favorite.ipynb --to html --execute

Why Quarto, instead of RMarkdown

Batteries included, shared syntax
Choose your own editor and your preferred data science language
Better accessibility and richer features out of the box
More enhancements overtime - RMarkdown still maintained, but majority of new features built into Quarto

Collaboration with other colleagues in other languages - shared format, choose your editor and your native language

Rendering

System shell via quarto render

 terminal

quarto render document.qmd # defaults to html
quarto render document.qmd --to pdf
quarto render document.qmd --to docx

R console via quarto R package

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

Change your mental model

Source

A blank Word document

Output

A blank Word document

Change your mental model

---
title: "ggplot2 demo"
author: "Norah Jones"
date: "5/22/2021"
format: 
  html:
    fig-width: 8
    fig-height: 4
    code-fold: true
---

## Air Quality

@fig-airquality further explores the impact of temperature 
  on ozone level.

```{r}
#| label: fig-airquality
#| fig-cap: Temperature and ozone level.
#| warning: false

library(ggplot2)
ggplot(airquality, aes(Temp, Ozone)) + 

  geom_point() + 
  geom_smooth(method = "loess"
)
```

A `.qmd` is a plain text file

Metadata (YAML)

format: html
engine: knitr

format: html
engine: jupyter

Code

```{r}
library(dplyr)
mtcars |> 
  group_by(cyl) |> 
  summarize(mean = mean(mpg))
```

```{python}
from siuba import *
(mtcars
  >> group_by(_.cyl)
  >> summarize(avg_mpg = _.mpg.mean()))
```

Text

# Heading 1
This is a sentence with some **bold text**, *italic text* and an 
![image](image.png){fig-alt="Alt text for this image"}.

Metadata: YAML

The YAML metadata or header is:

processed in many stages of the rendering process and can influence the final document in many different ways. It is placed at the very beginning of the document and is read by each of Pandoc, Quarto and knitr. Along the way, the information that it contains can affect the code, content, and the rendering process.

YAML

---
title: "My Document"
format: 
  html:
    toc: true
    code-fold: true
---

Markdown

Quarto is based on Pandoc and uses its variation of markdown as its underlying document syntax. Pandoc markdown is an extended and slightly revised version of John Gruber’s Markdown syntax.

Markdown is a plain text format that is designed to be easy to write, and, even more importantly, easy to read

Text Formatting

Markdown Syntax	Output
`italics and bold`	italics and bold
`superscript^2^ / subscript~2~`	superscript² / subscript₂
`~~strikethrough~~`	~~strikethrough~~
`verbatim code`	`verbatim code`

Headings

Markdown Syntax	Output
`# Header 1`	Header 1
`## Header 2`	Header 2
`### Header 3`	Header 3
`#### Header 4`	Header 4
`##### Header 5`	Header 5
`###### Header 6`	Header 6

Code

```{r}
#| output-location: column
#| label: fig-airquality
#| fig-cap: Temperature and ozone level.
#| warning: false

library(ggplot2)

ggplot(airquality, aes(Temp, Ozone)) + 
  geom_point() + 
  geom_smooth(method = "loess"
)
```

Code, more than just R

```{python}
#| eval: false
#| label: fig-polar
#| fig-cap: "A line plot on a polar axis"

import numpy as np
import matplotlib.pyplot as plt

r = np.arange(0, 2, 0.01)
theta = 2 * np.pi * r
fig, ax = plt.subplots(
  subplot_kw = {'projection': 'polar'} 
)
ax.plot(theta, r)
ax.set_rticks([0.5, 1, 1.5, 2])
ax.grid(True)
plt.show()
```

What about the CLI?

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

thomasmock$ quarto --help

  Usage:   quarto
  Version: 1.0.36

  Description:
    Quarto CLI

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

  Commands:
    render          [input] [args...]   - Render input file(s) to various document types.            
    preview         [file] [args...]    - Render and preview a document or website project.          
    serve           [input]             - Serve a Shiny interactive document.                        
    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.                
    install         <type> [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.    thomasmock$ quarto --help

  Usage:   quarto
  Version: 1.0.36

  Description:
    Quarto CLI

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

  Commands:
    render          [input] [args...]   - Render input file(s) to various document types.            
    preview         [file] [args...]    - Render and preview a document or website project.          
    serve           [input]             - Serve a Shiny interactive document.                        
    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.                
    install         <type> [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.    thomasmock$ quarto --help

  Usage:   quarto
  Version: 1.0.36

  Description:
    Quarto CLI

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

  Commands:
    render          [input] [args...]   - Render input file(s) to various document types.            
    preview         [file] [args...]    - Render and preview a document or website project.          
    serve           [input]             - Serve a Shiny interactive document.                        
    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.                
    install         <type> [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.    thomasmock$ quarto --help

  Usage:   quarto
  Version: 1.0.36

  Description:
    Quarto CLI

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

  Commands:
    render          [input] [args...]   - Render input file(s) to various document types.            
    preview         [file] [args...]    - Render and preview a document or website project.          
    serve           [input]             - Serve a Shiny interactive document.                        
    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.                
    install         <type> [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.    thomasmock$ quarto --help

  Usage:   quarto
  Version: 1.0.36

  Description:
    Quarto CLI

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

  Commands:
    render          [input] [args...]   - Render input file(s) to various document types.            
    preview         [file] [args...]    - Render and preview a document or website project.          
    serve           [input]             - Serve a Shiny interactive document.                        
    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.                
    install         <type> [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.    thomasmock$ quarto --help

  Usage:   quarto
  Version: 1.0.36

  Description:
    Quarto CLI

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

  Commands:
    render          [input] [args...]   - Render input file(s) to various document types.            
    preview         [file] [args...]    - Render and preview a document or website project.          
    serve           [input]             - Serve a Shiny interactive document.                        
    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.                
    install         <type> [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.

Navigating in the terminal

Because Quarto is a command line interface (CLI), there are times you’ll need to use it via the terminal. A great overview of using the command line and navigating files/directories is available via the Data Carpentries or a great interactive tool for understanding commands: https://tldr.ostera.io

Command	Action
`pwd`	Print name of current working directory
`cd`	Change current working directory
`ls`	List directory contents
`quarto --help`	Return `quarto` help docs
`mkdir howdy`	Make a new folder/directory called “howdy”
`rm folder-name/some-file.qmd`	Delete `some-file.qmd` in the `folder-name` directory