Quarto/RMarkdown - What’s Different?

Hymans Robertson R User Group

Ted Laderas

1/18/23

Agenda for Today

  • What is Quarto?
  • Should you switch from RMarkdown?
    • Demo
  • Guide to Converting RMarkdown
  • Questions

About Me

What is Quarto?

What is Quarto?

  • Reproducible Publishing System based on Pandoc
  • One format, many outputs
    • Website
    • Publications
    • Books
    • Dashboards

.qmd files

  • Short for quarto markdown
  • Decoupled from RStudio IDE
    • plugins for VSCode, JupyterLab and RStudio are available
  • Can still Render within RStudio
  • Render with quarto standalone on command line:
quarto render my_document.qmd

Cross Language Support

Jupyter Notebook Support

quarto convert notebook.ipynb

Fast way to publish Jupyter Notebooks!

Code Output Freezing

  • By default, code is not recomputed
  • quarto render --execute will recompute
  • Output is “frozen”
execute:
  freeze: auto  # re-render only when source changes

Code Chunks

Options are moved to within the code chunk using #| (hash-pipe) for each line

RMarkdown

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
library(tidyverse)
library(DT)
library(ggimage)
```

Quarto

```{r}
#| label: "setup"
#| include: false
knitr::opts_chunk$set(echo = TRUE)
library(tidyverse)
library(DT)
library(ggimage)
```

What’s Different with Quarto?

How is Quarto different from RMarkdown?

  • Standardized YAML across formats
  • Decoupled from RStudio
  • More consistent presentation across formats
  • Tab Panels
  • Code Highlighting

Should I Switch to Quarto?

Should you switch to Quarto? Not necessarily. If you find R Markdown meet your need, you can definitely stay there. It is not imperative to switch. - Yihui Xie

Some Killer Apps for Quarto (HTML)

  • Output Freezing
  • Precise Layouts
  • Tab Panels
  • Code Highlighting

Freeze Results and avoid recomputing

  • Creates a _freeze/ directory in your project
  • Saves intermediate output
_quarto.yml
project:
  title: "qmd_rmd"
  type: website
  output-dir: docs
  
freeze: true

Freeze Results: CLI

  • Results are frozen with quarto render by default.
  • Use --execute to recompute:
quarto render . --execute

Layout Example

:::: {.columns}

::: {.column width="50%"}
- Highly customizable
- Less work than using `<div>` tags
:::

::: {.column width="50%"}
- Customizable in terms of layouts

:::
::::

Layout Example

  • Highly customizable
  • Less work than using <div> tags
  • Customizable in terms of layouts

Tabsets

::: {.panel-tabset}

### Code

This is where I would put some code:

### Figure

ggpplot code here

:::

Tabsets

This is where I would put some code:

```{r}
library(palmerpenguins)
library(ggplot2)
data(penguins)
ggplot(penguins, aes(x=bill_depth_mm, y=bill_length_mm, color = species)) + geom_point()
```

Code Highlighting

  • Incremental highlighting (line by line)
  • Killer app for me
  • Really good for teaching!
```{r}
#| echo: TRUE
#| eval: FALSE
#| code-line-numbers: "3|4-6|7"
library(palmerpenguins)
library(ggplot2)
data(penguins)
ggplot(penguins) + aes(x=bill_depth_mm, 
                       y=bill_length_mm, 
                       color = species) + 
  geom_point()
```

Code Highlighting Example

library(palmerpenguins)
library(ggplot2)
data(penguins)
ggplot(penguins) + aes(x=bill_depth_mm, 
                       y=bill_length_mm, 
                       color = species) + 
  geom_point()

How to move to Quarto

Checklist

  1. Start a Quarto Project
  2. For your documents: Change your output: to the corresponding format: in your YAML
  3. Use knitr::convert_chunk_header() to convert your code blocks (outputs a .qmd file)
  4. Render your files
  5. For websites: edit your _quarto.yml file if necessary

1. Start a Quarto Project

File > New Project > New Directory > Quarto Project

Quarto Project Start

2. Convert your Rmarkdown Documents

  • Change your YAML header
  • Instead of output:, use format:

---
title: "Quarto/RMarkdown - What's Different?"
author: Ted Laderas
subtitle: FCT Abuja useR Group
date: 9/15/2022
output:
  xaringan::moon_reader:
    lib_dir: libs
    css: xaringan-themer.css
---

---
title: "Quarto/RMarkdown - What's Different?"
author: Ted Laderas
subtitle: FCT Abuja useR Group
date: 9/15/2022
format: 
  revealjs:
    self-contained: true
    theme: night
    footer: <https://laderast.github.io/qmd_rmd/>
incremental: false
highlight-style: github
---

2. RMarkdown/Quarto Formats

RMarkdown Quarto
output: html_document format: html
output: pdf_document format: pdf
output: word_document format: docx
output: xaringan format: revealjs
output: ioslides format: revealjs
output: distill Quarto Article Layout

3. Convert your RMarkdown Code Chunks

knitr::convert_chunk_header() will convert your RMarkdown code chunks into quarto compatible format.

knitr::convert_chunk_header("filename.Rmd", 
    output = "filename.qmd")

3. Converting Code Chunks

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
library(tidyverse)
library(DT)
library(ggimage)
```
```{r}
#| label: "setup",
#| include: FALSE
knitr::opts_chunk$set(echo = TRUE)
library(tidyverse)
library(DT)
library(ggimage)
```

4. Render via RStudio GUI

  • Render button in RStudio
quarto::quarto_render()`

4. Render via Command Line

> quarto render <filename>

5. Update your _quarto.yml for websites

_quarto.yml
project:
  type: website

website:
  title: "Ted Laderas, PhD"
  description: "Ted's R and Teaching Blog"
  navbar:
    right:
      - teaching.qmd
      - articles.rmd
      - blog.qmd
      - talks.qmd
      - notebook.ipynb #works for Jupyter notebooks!

Mix and Match Formats

_quarto.yml
website:
  title: "Ted Laderas, PhD"
  description: "Ted's R and Teaching Blog"
  navbar:
    right:
      - teaching.qmd
      - articles.rmd
      - blog.qmd
      - talks.qmd
      - notebook.ipynb

Publish your files (on CLI)

quarto publish can push and update a number of different kinds of webhosts. You will need credentials to publish to each of these.

quarto publish gh-pages    # GitHub Pages
quarto publish quarto-pub  # Quarto.pub 
quarto publish netlify     # Netlify
quarto publish connect     # RStudio Connect

Multiple languages

Hand off data objects with multiple languages in a Quarto Document

Languages Method
Python <=> R {reticulate}/Apache Arrow or Pandas
R <=> JavaScript ojs_define() function
Python <=> JavaScript ojs_define function

Apache Arrow

  • “Language Independent Columnar memory format”
  • Handles very large datasets / CSV files
  • Code example here Intro to Apache Arrow

Observable/Shiny

  • Use Observable Components (viewof, Observable Plot) with Shiny
  • viewof inputs are passed into Shiny’s input opject
  • Use ojs_define() function to pass reactives to Observable code chunks
  • Example/Demo

Conclusions

  • Quarto supports multiple languages / IDEs
  • Quarto standardizes a lot of outputs
  • Does a better job of one document, many outputs
  • Lots of publishing features (references, figures, etc.)

Learn More

Thank You! Questions?

https://laderast.github.io/qmd_rmd/