index.qmd

---
title: "Quarto/RMarkdown - What's Different?"
author: Ted Laderas
subtitle: Hymans Robertson R User Group
date: 1/18/2023
format: 
  revealjs:
    standalone: true
    theme: night
    progress: true
    footer: <https://laderast.github.io/qmd_rmd/>
incremental: false
highlight-style: a11y
---

## Agenda for Today

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

## About Me

:::: {.columns}

::: {.column width="65%"}
- Bioinformatics Trainer at [DNAnexus](https://dnanexus.com)
- [Posit Academy](https://www.posit.co/academy) Data Science Mentor
- RStudio/Carpentries Certified Instructor
- Twitter: @tladeras 
- Web: <https://laderast.github.io/>
:::

::: {.column width="35%"}
![](ted.jpg)
:::

::::

# What is Quarto?

## What is Quarto?

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

## .qmd files

- Short for **q**uarto **m**ark**d**own
- Decoupled from RStudio IDE
  - plugins for VSCode, JupyterLab and RStudio are available
- Can still Render within RStudio
- Render with quarto standalone on command line:

```{.bash}
quarto render my_document.qmd
```

## Cross Language Support

- Supports a number of languages:
    - R
    - Python
    - Julia
    - Observable
- Can [interchange between languages using Apache Arrow](https://gist.github.com/hrbrmstr/23355194d1964688596553a0e6a0050a)


## Jupyter Notebook Support

- [Jupyter Notebooks are cross compatible](https://quarto.org/docs/tools/jupyter-lab.html)
- One command to interchange: 

```{.bash}    
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"

```{.markdown}
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 {auto-animate="true"}
````{.markdown}
```{{r setup, include=FALSE}}
knitr::opts_chunk$set(echo = TRUE)
library(tidyverse)
library(DT)
library(ggimage)
```
````

## Quarto {auto-animate="true"}

````{.markdown}
```{{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

::: aside
<https://yihui.org/en/2022/04/quarto-r-markdown/>
:::

## 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

```{bash}
#| eval: false
#| echo: true
#| filename: _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:

```{bash}
#| echo: true
#| eval: false

quarto render . --execute
```

## Layout Example

````{.markdown}
:::: {.columns}

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

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

:::
::::
````

## Layout Example

:::: {.columns}

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

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

:::
::::

## Tabsets

````{.markdown}
::: {.panel-tabset}

### Code

This is where I would put some code:

### Figure

ggpplot code here

:::
````

## Tabsets

::: {.panel-tabset}

### Code

This is where I would put some code:

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

### Figure

```{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!

````{.markdown}
```{{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

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

# How to move to Quarto

## Checklist

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

## 1. Start a Quarto Project

:::: {.columns}

::: {.column width="50%"}
**File >** 
**New Project >** 
**New Directory >** 
**Quarto Project**
:::

::: {.column width="50%"}
![Quarto Project Start](quarto_project.png)
:::
::::

## 2. Convert your Rmarkdown Documents

- Change your YAML header
- Instead of `output: `, use `format: `

## {auto-animate="true"}

````{.markdown}
---
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
---
````
## {auto-animate="true"}

````{.markdown}
---
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`](https://quarto.org/docs/output-formats/html-basics.html)|
| `output: pdf_document` | [`format: pdf`](https://quarto.org/docs/output-formats/pdf-basics.html) |
| `output: word_document` | [`format: docx`](https://quarto.org/docs/output-formats/ms-word.html) |
| `output: xaringan` | [`format: revealjs`](https://quarto.org/docs/presentations/revealjs/) |
| `output: ioslides` | [`format: revealjs`](https://quarto.org/docs/presentations/revealjs/) |
| `output: distill` | [Quarto Article Layout](https://quarto.org/docs/authoring/article-layout.html)

::: aside
<https://quarto.org/docs/faq/rmarkdown.html>
:::

## 3. Convert your RMarkdown Code Chunks

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

```{{r}}
knitr::convert_chunk_header("filename.Rmd", 
	output = "filename.qmd")
```

## 3. Converting Code Chunks

::: {.panel-tabset}

### Original Chunk

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

````{.markdown}
```{{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
```r
quarto::quarto_render()`
```
## 4. Render via Command Line

```{.bash}
> quarto render <filename>
```

## 5. Update your `_quarto.yml` for websites

- Controls [navigation and visibility of documents](https://quarto.org/docs/websites/)

```{markdown}
#| echo: TRUE
#| eval: FALSE
#| filename: _quarto.yml
#| code-line-numbers: "1-2|4-6|7-13"
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

```{markdown}
#| echo: TRUE
#| eval: FALSE
#| code-line-numbers: "7|8|10"
#| filename: _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.

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

::: aside
<https://quarto.org/docs/publishing/>
:::


## 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](https://github.com/laderast/intro_to_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](https://github.com/laderast/ojs_shiny_example)

## 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

- Workshop materials from Andrew Bray: <https://github.com/rstudio-conf-2022/rmd-to-quarto>
- Repository for this talk: <https://github.com/laderast/qmd_rmd>


# Thank You! Questions?