RStudio PBC is now Posit PBC

What is Quarto?

https://quarto.org

Origins

Goal: Computation document

• Documents that include source code for their production
• Notebook AND plain-text flavors
• Programmatic automation and reproducibility

Goal: Scientific Markdown

Goal: Single Source Publishing

Simple Example

---
title: "matplotlib demo"
format:
  html:
    code-fold: true
jupyter: python3
---

For a demonstration of a line plot on a polar 
axis, see @fig-polar.

```{python}
#| 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()
```

Simple Example, multi-format

Can be rendered to dozens of output formats with Quarto (via Pandoc):

$ quarto render hello.qmd --to html
$ quarto render hello.qmd --to pdf
$ quarto render hello.qmd --to docx
$ quarto render hello.qmd --to epub
$ quarto render hello.qmd --to pptx
$ quarto render hello.qmd --to revealjs

So what is Quarto?

Quarto® is an open-source scientific and technical publishing system built on Pandoc.

thomasmock$ quarto --help

Usage:   quarto
Version 1.4.193

Commands:
  render  [input] [args...] - Render input file(s) to various document types.            
  preview [file] [args...]  - Render and preview a document or website project.          
  publish [provider] [path] - Publish a document or project.

Basic Workflow

Rendering (execute and write to disk):

# plain text qmd
$ quarto render python.qmd
$ quarto render python.qmd --to pdf

# ipynb notebook
$ quarto render python.ipynb
$ quarto render python.ipynb --execute

# plain text qmd
$ quarto preview python.qmd
$ quarto preview python.qmd --to pdf

# ipynb notebook
$ quarto preview python.ipynb
$ quarto preview python.ipynb --execute

IPython

For execution of R, Quarto uses knitr as the engine, but for Python Quarto natively executes Python with Jupyter kernels such as IPython.

---
title: "My doc"
date: today
jupyter: python3
---

Stored/frozen computation and reproducibility

1. Jupyter natively approaches this as storing the source code, output file, and cache the resulting computation in a single document (.ipynb which is JSON)

A .qmd is a plain text file

format: html
jupyter: python3

format: html
engine: knitr

```{python}
import polars as pl
(mtcars
  .groupby("cyl")
  .agg([(pl.col("mpg").mean())]))
```

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

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

But Quarto doesn’t have to be plain-text

Rendering pipeline

What to do with my existing .ipynb?

# --execute flag is optional - forces re-execution
quarto render my-favorite.ipynb --to html --execute

quarto convert --help

Usage:   quarto convert <input>
Description:
    Convert documents to alternate representations.

Convert notebook to markdown:                quarto convert doc.ipynb                
Convert markdown to notebook:                quarto convert doc.qmd                  
Convert notebook to markdown, write to file: quarto convert doc.ipynb --output doc.qmd

Comfort of your own workspace

Auto-completion in RStudio + VSCode

Both RStudio and VSCode with the Quarto extension have rich auto-completion

Quarto Extensions and Visual/Live Editor

Quarto, unified document layout

quarto render boston-terrier.qmd --to html

quarto render boston-terrier.qmd --to pdf

Quarto, unified syntax across markdown and code

::: {layout-ncol=2}
![Surus](surus.png)

![Hanno](hanno.png)
:::

```{python}
#| layout-ncol: 2
#| fig-cap: ["Scatter", "Boxplot"]

from plotnine import ggplot, geom_point, geom_boxplot, aes, stat_smooth, facet_wrap, theme
from plotnine.data import mtcars

# plot 1 in column 1
plot1 = (ggplot(mtcars, aes('wt', 'mpg', color='factor(gear)'))
   + geom_point() + stat_smooth(method='lm')
   + facet_wrap('~gear')).draw(show=True)

# plot 2 in column 2
plot2 = (ggplot(mtcars, aes('cyl', 'mpg', color='factor(cyl)'))
+ geom_boxplot()).draw(show=True)
```

Built-in vs custom

One goal of Quarto is to provide a markdown-centric format-agnostic syntax as shown in previous slides.

Extending Quarto with extensions

{{< fa thumbs-up >}} 

---
title: "Cool Company 2022 Presentation"
format: coolco-revealjs
---

Interactivity, Jupyter Widgets

import plotly.express as px
import plotly.io as pio
df = px.data.iris()
fig = px.scatter(df, x="sepal_width", y="sepal_length", 
                 color="species", 
                 marginal_y="violin", marginal_x="box", 
                 trendline="ols", template="simple_white")
fig.show()

Interactivity, Observable

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

viewof bill_length_min = Inputs.range(
  [32, 50], 
  {value: 35, step: 1, label: "Bill length (min):"}
)
viewof islands = Inputs.checkbox(
  ["Torgersen", "Biscoe", "Dream"], 
  { value: ["Torgersen", "Biscoe"], 
    label: "Islands:"
  }
)

Plot.rectY(filtered, 
  Plot.binX(
    {y: "count"}, 
    {x: "body_mass", fill: "species", thresholds: 20}
  ))
  .plot({
    facet: {
      data: filtered,
      x: "sex",
      y: "species",
      marginRight: 80
    },
    marks: [
      Plot.frame(),
    ]
  }
)

Inputs.table(filtered)

data = FileAttachment("palmer-penguins.csv").csv({ typed: true })

filtered = data.filter(function(penguin) {
  return bill_length_min < penguin.bill_length &&
         islands.includes(penguin.island);
})

Interactivity, on the fly Observable “widgets”

Quarto including Observable means you can create new “widgets” or allow the user to modify portions of the doc on the fly.

viewof temp = Inputs.range([0, 100], {step: 1, value: 34, label: htl.html`Temp ℃`})

```{ojs}
viewof temp = Inputs.range([0, 100], {step: 1, value: 34, label: htl.html`Temp ℃`})
```

Converting temperature from &#x2103; to &#x2109; <br>  
Celsius = ${d3.format(".0f")(temp)}&#x2103; and Fahrenheit = ${d3.format(".1f")(temp * 9/5 + 32)}&#x2109;.

Parameters - one source, many outputs

• Showing results for a specific geographic location.
  
• Running a report that covers a specific time period.
  
• Running a single analysis multiple times for different assumptions.

```{python}
#| tags: [parameters]

alpha = 0.1
ratio = 0.1
```

```{python}
str(alpha)
```

---
title: "My Document"
params:
  alpha: 0.1
  ratio: 0.1
---

```{r}
str(params$alpha)
```

Rendering with parameters

To render using different parameters you can pass them on the command line using the -P flag:

quarto render notebook.ipynb -P alpha:0.2 -P ratio:0.3

quarto render notebook.ipynb --execute-params params.yml

Quarto Publish

quarto publish --help

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

Quarto, crafted with love and care

Development of Quarto is sponsored by Posit, PBC (formerly known as RStudio, PBC). The same core team works on both Quarto and R Markdown:

• Carlos Scheidegger (@cscheid)

• Charles Teague (@dragonstyle)

• Christophe Dervieux (@cderv)

• J.J. Allaire (@jjallaire)

• Yihui Xie (@yihui)

Here is the full contributors list. Quarto is open source and we welcome contributions in our github repository as well! https://github.com/quarto-dev/quarto-cli.

Quarto

• Batteries included, shared syntax across output types and languages
• Single source publishing across document types, with raw customization allowed
• Choose your own editor for plain text .qmd or Jupyter notebooks
• Quarto projects + freeze for managing stored computation

Follow @quarto_pub #QuartoPub on Twitter/Fosstodon to stay up to date!

Quarto resources

• Quarto for the Curious - 20 min video
• ‘Welcome to Quarto’ workshop - 120 min video

General Quarto

• Hello Quarto - RStudio::Conf Keynote, 60 min
• Literate Programming With Jupyter Notebooks and Quarto - 20 min

Why the name “Quarto”?¹