index.qmd

---
title: "Quarto"
subtitle: "Recherche reproductible en écologie numérique"
author:
  - name: "François Guilhaumon"
    url: https://fguilhaumon.github.io/
    orcid: "0000-0003-4707-8932"
    affiliations: "IRD (ENTROPIE)"
date: "2023-11-21"
date-format: long
format:
  revealjs:
    theme: night
    transition: slide
    background-transition: fade
    scrollable: true
    css: assets/custom.css
    chalkboard: true
slide-number: true
self-contained: false
footer: "Quarto -- CESAB Data Toolbox -- 2023-11-21"
smaller: false
---

# Notebooks

##

RMarkdown & Jupyter Notebook

::: columns
::: {.column width="33%"}
[![](https://bookdown.org/yihui/rmarkdown/images/cover.png)](https://bookdown.org/yihui/rmarkdown/)
:::

::: {.column width="33%"}
[![](https://bookdown.org/yihui/rmarkdown-cookbook/images/cover.png)](https://bookdown.org/yihui/rmarkdown-cookbook/)
:::

::: {.column width="33%"}
[![](https://github.com/ipython-books/cookbook-2nd/raw/master/cover-cookbook-2nd.png)](http://ipython-books.github.io/)
:::
:::

## RMarkdown

With time, RMarkdown gathered an entire ecosystem of R packages

![](https://mine.quarto.pub/hello-quarto/images/1-share/rmd_ecosystem.png){style="text-align: center;" fig-align="center" width="80%"}

## Quarto: Next gen R Markdown

![](https://media1.giphy.com/media/v1.Y2lkPTc5MGI3NjExZDY5N2Y5MzY0NGI2ZDNkMWM4ZjU0YzNlNWVmZDg1OTg2ZjIyMmMyMyZjdD1n/XgE4LlECZjw6k/giphy.gif){style="text-align: center;" fig-align="center;" width="20%"}

#### Quarto *unifies* and *extends* the R Markdown ecosystem {.centered}

## {auto-animate=true}

Quarto is a new, open-source, scientific and technical publishing system 

![](https://cdn.myportfolio.com/45214904-6a61-4e23-98d6-b140f8654a40/c2ef45f1-4a68-4c7a-a43f-bdcf0f90e104.png?h=57404b88e9bf43eea2d2b57c71b13303)

## {auto-animate=true}

Quarto is a new, open-source, scientific and technical publishing system

![](https://cdn.myportfolio.com/45214904-6a61-4e23-98d6-b140f8654a40/c2ef45f1-4a68-4c7a-a43f-bdcf0f90e104.png?h=57404b88e9bf43eea2d2b57c71b13303)

Quarto is a software (command line interface) that renders plain text formats such as `.qmd`, `.rmd`, `.md` into static PDF/Word/HTML reports, books, websites, presentations and more

## Quarto CLI orchestrates each step of rendering

![](https://cdn.myportfolio.com/45214904-6a61-4e23-98d6-b140f8654a40/b5217f2a-f129-4bf9-90dc-c5b9783d0ea8_rw_1920.png?h=0d8c9fc177975359270821bcba83986c)

## Quarto basics

This is a Quarto file -- a plain text file that has the extension `.qmd`:

```{r echo = FALSE, comment = ""}
cat(readr::read_file("diamond-sizes.qmd"))
```

## Quarto basics

It contains three important types of content:

::: incremental
1.  An (optional) **YAML header** surrounded by `---`s.
2.  **Chunks** of R code surrounded by ```` ``` ````.
3.  Text mixed with simple text formatting like `# heading` and `_italics_`.
:::

## Quarto basics

```{r echo = FALSE, comment = ""}
cat(readr::read_file("diamond-sizes.qmd"))
```


##

For example, **Quarto** powers [Computo](https://computo.sfds.asso.fr/)

<br/>

[![A journal of the French Statistical Society SFdS - ISSN 2824-7795](https://computo.sfds.asso.fr/assets/img/logo_text_vertical.svg){width="30%" fig-align="center"}](https://computo.sfds.asso.fr/)


# Quarto VS Rmarkdown

## Decoupling from R

::: incremental
-   Quarto is multi-core and multi-engine
-   Dedicated CLI
-   Unlike Rmd / Jupyter notebooks (Python), Quarto is not tied to a language ([You can use Python in Rmd within Rstudio and R in Jupyter notebooks but few people do]{.small})
-   Compatible with your editor (Jupyter Lab, Neovim, VS Code, RStudio, etc ...), *with many visual edition modes available*
-   Makes collaboration easier
:::


# Quarto highlights

##

<br/>

::: incremental
-   Consistent implementation of features across outputs: (tabsets, code-folding, syntax highlighting)
-   More accessible defaults, better support for accessibility
-   Guardrails, particularly helpful for new learners: (YAML completion, informative syntax errors)
-   Support for other languages like Python, Julia, Observable, ...
:::

## Citations / cross-references

::: incremental
-   citations: bibliography files (bibtex), bibliography style (csl)

::: fragment
``` yaml
---
title: "My Document"
bibliography: references.bib
csl: nature.csl
---

She said "[...] but you can't stop the future" [@Sp231992].
```
:::

-   cross-references for figures (`fig-`), tables (`tbl-`), sections (`sec-`), equations (`eq-`), (`thm-`), etc

::: fragment
``` yaml
## Introduction {#sec-introduction}

See @sec-introduction for additional context.
```
:::
:::


## Extensions

::: incremental
-   [`include-code-files`](https://github.com/quarto-ext/include-code-files) : code from source files
-   [`fontawesome`](https://github.com/quarto-ext/fontawesome), [`academicons`](https://github.com/schochastics/academicons), ... : Use icons {{< fa thumbs-up >}} {{< fa folder >}} {{< fa chess-pawn >}} {{< ai open-access }} {{< ai dataverse >}} {{< ai moodle >}} {{< ai sci-hub >}}
-   [`collapse-social-embeds`](https://github.com/sellorm/quarto-social-embeds) : include social items.
-   [Journal Articles Template](https://quarto.org/docs/extensions/listing-journals.html)
-   [`quarto-inrae-extension`](https://github.com/davidcarayon/quarto-inrae-extension) : INRAE formats for HTML, PDF, Docx, Revealjs, and Beamer, thanks to [\@david_carayon](https://twitter.com/david_carayon)
-   ... [Quarto Extensions](https://quarto.org/docs/extensions/)
:::

## Moving between formats is straightforward {.centered}

::: columns
::: {.column width="33%"}
::: fragment
Document HTML

::: {.code-file .sourceCode .cell-code}
{{< fa file >}} lesson-1.qmd
:::

``` yaml
title: "Lesson 1"
format: html
```
:::

::: fragment
Document PDF

::: {.code-file .sourceCode .cell-code}
{{< fa file >}} lesson-1.qmd
:::

``` yaml
title: "Lesson 1"
format: pdf
```
:::
:::

::: {.column width="33%"}
::: fragment
Presentation

::: {.code-file .sourceCode .cell-code}
{{< fa file >}} lesson-1.qmd
:::

``` yaml
title: "Lesson 1"
format: revealjs
```
:::

::: fragment
Book

::: {.code-file .sourceCode .cell-code}
{{< fa file >}} \_quarto.yml
:::

``` yaml
project:
  type: book
  output-dir: _book
```
:::
:::

::: {.column width="33%"}
::: fragment
Website

::: {.code-file .sourceCode .cell-code}
{{< fa file >}} \_quarto.yml
:::

``` yaml
project:
  type: website
website: 
  navbar: 
    left:
      - lesson-1.qmd
```
:::
:::
:::

::: aside
And more in the [Gallery](https://quarto.org/docs/gallery/) ...
:::

## RStudio integration

![](https://quarto.org/docs/get-started/hello/images/rstudio-hello.png)

# Presentations

## Easy presentations

::: {layout="[1, 20]"}
![](https://quarto.org/docs/presentations/revealjs/demo/images/presentation-menu.png){width="41"}

Toggle the slide menu with the menu button to go to other slides and access presentation tools. Some other tools like **PDF Export** in this settings.
:::

. . .

::: {layout="[1, 20]"}
![](https://quarto.org/docs/presentations/revealjs/demo/images/presentation-chalkboard.png){width="41"}

Use the chalkboard button to toggle the chalkboard.
:::

. . .

::: {layout="[1, 20]"}
![](https://quarto.org/docs/presentations/revealjs/demo/images/presentation-notes-canvas.png){width="41"}

Use the notes canvas button to toggle drawing on top of the current slide.
:::

## Callout-blocks

``` yaml
::: {.callout-note}
Five types of callouts: `note`, `warning`, 
`important`, `tip`, and `caution`.
:::
```

<br/><br/>

::: callout-note
Five types of callouts: **`note`**, `warning`, `important`, `tip` and `caution`.
:::

::: callout-tip
Five types of callouts: `note`, `warning`, `important`, **`tip`** and `caution`.
:::

## Diagrams

````         
```{{mermaid}}
flowchart LR
  A[Hard edge] --> B(Round edge)
  B --> C{Decision}
  C --> D[Result one]
  C --> E[Result two]
```
````

<br/><br/>

```{mermaid}
flowchart LR
  A[Hard edge] --> B(Round edge)
  B --> C{Decision}
  C --> D[Result one]
  C --> E[Result two]
```

## Videos

``` {.default shortcodes="false"}
{{< video https://www.youtube.com/watch?v=KPXFs2YU3F4>}}
```


[{{< video https://www.youtube.com/watch?v=KPXFs2YU3F4 width="700" height="500" title="Future Maore Reefs" start="423">}}]{.center}

## Widgets

Native support for [JupyterWidgets](https://quarto.org/docs/interactive/widgets/jupyter.html) (Jupyter) and [htmlwidgets](https://quarto.org/docs/interactive/widgets/htmlwidgets.html) (R/knitr)

::: {style="font-size: 0.9em"}
```{r}
#| echo: fenced
#| output-location: column-fragment
library(leaflet)
leaflet(width = "480px") %>%
  addTiles() %>%
  addMarkers(
    lat=43.61270525357229, 
    lng=3.8733237524215443, 
    popup="We are here!"
  )
```
:::

## Transitions {.smaller}

Use `. . .` to indicate a break at an arbitrary location

. . .

::: {style="font-size: 0.9em"}
````         
Let's have a look at `iris`

. . . 

```{{r}}
head(iris) |> knitr::kable()
```
````
:::

. . .

Let's have a look at `iris`

. . .

```{r}
head(iris) |> knitr::kable()
```

## Fragments

::: columns
::: {.column width="60%"}
::: {style="font-size: 0.75em"}
```         

::: {.fragment}
Fade in
:::

::: {.fragment .fade-out}
Fade out
:::

::: {.fragment .strike}
Strike text
:::

::: {.fragment .fade-in-then-out}
Fade in, then out
:::

::: {.fragment .fade-up}
Slide up while fading in
:::
```
:::
:::

::: {.column width="40%"}
::: fragment
Fade in
:::

::: {.fragment .fade-out}
Fade out
:::

::: {.fragment .strike}
Strike text
:::

::: {.fragment .fade-in-then-out}
Fade in, then out
:::

::: {.fragment .fade-up}
Slide up while fading in
:::
:::
:::

## Column output

::: {style="font-size: 0.8em"}
```{r}
#| echo: fenced
#| code-line-numbers: "|3"
#| output-location: column

library(ggplot2)

ggplot(mtcars, aes(hp, mpg)) +
  geom_point() +
  geom_smooth(formula = y ~ x, method = "loess")
```
:::

. . .

::: {style="font-size: 0.8em"}
```{r}
#| echo: fenced
#| code-line-numbers: "|3"
#| output-location: column-fragment
ggplot(mtcars, aes(hp, mpg)) +
  geom_point() +
  geom_smooth(formula = y ~ x, method = "loess")
```
:::

## Tabset output {.smaller}

::: panel-tabset
### Code

```{r}
#| echo: fenced
p <- ggplot(mtcars, aes(hp, mpg)) +
  geom_point() +
  geom_smooth(formula = y ~ x, method = "loess")
```

### Plot

```{r}
p
```

### Under the hood

::: {style="font-size: 0.8em"}
````         
::: {.panel-tabset}

### Plot code

```{{r}}
#| echo: fenced
p <- ggplot(mtcars, aes(hp, mpg)) +
  geom_point() +
  geom_smooth(formula = y ~ x, method = "loess")
```

### Plot

```{{r}}
p
```

:::
````
:::
:::

## Easy layouts  {.smaller}

::: panel-tabset
### Code

-   Use negative values for white space

::: {style="font-size: 0.8em"}
```{r}
#| echo: fenced
#| eval: false
#| fig-subcap: 
#|   - "boring 🥱"
#|   - "boooring 🥱🥱"
#|   - "boooriiing 🥱🥱🥱"
#| fig-height: 2
#| layout: [[40,-20,40], [100]]
p
p
p
```
:::

### Plot

```{r}
#| fig-subcap: 
#|   - "boring 🥱"
#|   - "boooring 🥱🥱"
#|   - "boooriiing 🥱🥱🥱"
#| fig-height: 2
#| layout: [[40,-20,40], [100]]
p
p
p
```
:::


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

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

## How to move to Quarto {.smaller}

::: incremental
1.  [Install Quarto](https://quarto.org/docs/get-started/)
2.  Start a Quarto Project
3.  Convert your Rmarkdown Documents
    -   Change your `output:` to the corresponding `format:` in your YAML
    -   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
6.  Publish
:::

## Take Home Messages




::: incremental
-   Quarto is a new, open-source, scientific and technical publishing system
-   Quarto supports multiple languages / IDEs
-   Quarto standardizes a lot of outputs
-   Does a better job of one document, many outputs than Rmd
-   Lots of publishing features (references, figures, etc.)
-   Very well documented
:::

# Ressources

## Ressources

<br/><br/>

- [Quarto documentation](https://quarto.org/)
- [Hadley's intro to Quarto](https://r4ds.hadley.nz/quarto)
- [Awesome Quarto](https://github.com/mcanouil/awesome-quarto)
- [La présentation originale de Cédric Midoux](https://cedric.midoux.pages.mia.inra.fr/slides/posts/2023-04-13_quarto)