Quarto, anatomy

1. Metadata: YAML

2. Text: Markdown

3. Code: knitr or jupyter

Literate programming

Literate programming is writing out the program logic in a human language with included (separated by a primitive markup) code snippets and macros. - Wikipedia

---
title: "ggplot2 demo"
date: "5/22/2021"
format: html
---

## Air Quality

There is a relationship between temperature and the ozone level.

```{r}
#| label: fig-airquality
library(ggplot2)
ggplot(airquality, aes(Temp, Ozone)) + 
  geom_point() + 
  geom_smooth(method = "loess"
)
```

Metadata: YAML

“Yet Another Markup Language” or “YAML Ain’t Markup Language”

---
key: value
---

Output Options

---
format: something
---

---
format: html
---

---
format: pdf
---

---
format: revealjs
---

---
format: 
  html:
    toc: true
    code-fold: true
---

---
format: 
  html:
    option1: text
    option2: logical
---

YAML for format: html

YAML is sensitive

---
format:html # invalid, no space between
---

---
format: # invalid, read as missing
html
---

---
format: 
  html: # valid but needs next object
---

format: html # valid - there's a space

format:
  html # valid - there's 2x spaces on a new line and no trailing :

# valid - format = HTML with selections made
format: 
  html:
    toc: true

Why YAML?

To avoid manually typing out all the options, every time!

quarto render document.qmd --to html

quarto render document.qmd --to html -M code-fold:true

quarto render document.qmd --to html -M code-fold:true -P alpha:0.2 -P ratio:0.3

Quarto workflow

Executing the Quarto Render button in RStudio will call Quarto render in a background job - this will prevent Quarto rendering from cluttering up the R console, and gives you and easy way to stop.

Rendering

1. Render in RStudio, starts a background job and previews the output

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

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

Quarto linting

Lint, or a linter, is a static code analysis tool used to flag programming errors, bugs, stylistic errors and suspicious constructs. - Lint

Quarto YAML Intelligence

RStudio + VSCode provide rich tab-completion - start a word and tab to complete, or Ctrl + space to see all available options.

HTML options

quarto.org/docs/reference/formats/html

You can use the HTML reference if needed.

Text Formatting

*italics* and **bold**

superscript^2^ / subscript~2~

~~strikethrough~~

`verbatim code`

Headings

# Header 1

## Header 2

### Header 3

#### Header 4

##### Header 5

###### Header 6

Links

• There are several types of “links” or hyperlinks.

You can embed [named hyperlinks](https://quarto.org/),
direct urls like <https://quarto.org/>, and links to 
[other places](#quarto-anatomy) in 
the document. The syntax is similar for embedding an
inline image: ![Boston terrier](images/howard-gentleman.jpeg).

Tables

| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |

Grid tables

+---------------+---------------+--------------------+
| Fruit         | Price         | Advantages         |
+===============+===============+====================+
| Bananas       | $1.34         | - built-in wrapper |
|               |               | - bright color     |
+---------------+---------------+--------------------+
| Oranges       | $2.10         | - cures scurvy     |
|               |               | - tasty            |
+---------------+---------------+--------------------+

: Sample grid table.

Grid table, alignment

Alignments can be specified as with pipe tables, by putting colons at the boundaries of the separator line after the header:

+---------------+---------------+--------------------+
| Right         | Left          | Centered           |
+==============:+:==============+:==================:+
| Bananas       | $1.34         | built-in wrapper   |
+---------------+---------------+--------------------+

For headerless tables, the colons go on the top line instead:

+--------------:+:--------------+:------------------:+
| Right         | Left          | Centered           |
+---------------+---------------+--------------------+

Note that grid tables are quite awkward to write with a plain text editor (because unlike pipe tables, the column indicators must align). The RStudio IDE’s Quarto Visual Editor can assist in making these tables.

Tables from code

knitr itself can turn R dataframes into tables with knitr::kable()

A very simple table generator, and it is simple by design. It is not intended to replace any other R packages for making tables. . . .

head(mtcars) |> 
  knitr::kable()

Quotes

Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do. - Donald Knuth, Literate Programming ¹

> Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do. - Donald Knuth, Literate Programming

> I like dogs
> And I like cats

Anatomy of a code chunk

```{r}
#| label: car-stuff
#| echo: false
mtcars %>% 
  distinct(cyl)
```

Code

The way you treat code is very different for different contexts

Code

If you simply want code highlighting, you can use 3x backticks + the language ```r

```r
head(mtcars)
```

head(mtcars)

```{r}
#| echo: true
1 + 1
```

1 + 1

[1] 2

Code

In some scenarios you want to both execute the code and return the FULL code including backticks, like today where I’m teaching! echo: fenced is a great option for this.

```{r}
#| echo: fenced
1 + 1
```

```{r}
1 + 1
```

[1] 2

Code

If you want to, you may return purely decorative code which is not executed

````
```{{r}}
1 + 1
```
````

```{r}
1 + 1
```

Divs and Spans

Pandoc and therefore Quarto can parse “fenced Div blocks”

::: {.border}
This content can be styled with a border
:::

This is text with [special]{style="color:red;"} formatting.

::: {.unnumbered .unlisted}
Text
:::

<div style="font-size: 200px;">Text</div>

Callout Blocks

:::{.callout-note}
Note that there are five types of callouts, including: 
`note`, `tip`, `warning`, `caution`, and `important`.
:::

Callout markdown syntax

:::{.callout-note}
Note that there are five types of callouts, including:
`note`, `warning`, `important`, `tip`, and `caution`.
:::


:::{.callout-tip}
## Tip With Caption

This is an example of a callout with a caption.
:::

:::{.callout-caution collapse="true"}
## Expand To Learn About Collapse

This is an example of a 'folded' caution callout that can be expanded by the user. You can use `collapse="true"` to collapse it by default or `collapse="false"` to make a collapsible callout that is expanded by default.
:::

Figures

Basic markdown syntax:

![Boston Terrier](images/boston-terrier.png)

Boston Terrier

Figures w/ code

```{r}
#| fig-width: 4
#| fig-align: right

knitr::include_graphics("images/howard-gentleman.jpeg")
```

Fragments/spans

![Boston terrier](images/boston-terrier.png){fig-align="left"}

![](images/boston-terrier.png){fig-align="right" fig-alt="A photo a Boston Terrier."}

Subfigures fenced div class

::: {#fig-bostons layout-ncol=2}

![Excited](images/boston-terrier.png){#fig-boston width="250px"}

![Sleeping](images/boston-sleep.png){#fig-sleep width="250px"}

Two states of Howard

:::

Subfigures

Subfigures

Paths

Quarto documents reference from their existing folder/directory.

Absolute vs Relative:

In places like markdown, YAML, or the command line/shell/terminal you’ll need to use absolute or relative file paths:

list.files("/Users/thomasmock/get-started-quarto")

 [1] "_extensions"              "_freeze"                 
 [3] "_quarto.yml"              "404.html"                
 [5] "404.qmd"                  "docs"                    
 [7] "index.html"               "index.qmd"               
 [9] "LICENSE.md"               "materials"               
[11] "preview-image-build.R"    "preview.jpeg"            
[13] "preview.png"              "README.md"               
[15] "schedule.qmd"             "site_libs"               
[17] "workshop-conf-2022.Rproj" "workshop-materials.qmd"  

Relative file paths

Better, HTML style relative paths: "../ = up one directory - ../../ = up two directories and so forth

• /.. or / = start from root directory of your current computer

list.files("../")

 [1] "_extensions"              "_freeze"                 
 [3] "_quarto.yml"              "404.html"                
 [5] "404.qmd"                  "docs"                    
 [7] "index.html"               "index.qmd"               
 [9] "LICENSE.md"               "materials"               
[11] "preview-image-build.R"    "preview.jpeg"            
[13] "preview.png"              "README.md"               
[15] "schedule.qmd"             "site_libs"               
[17] "workshop-conf-2022.Rproj" "workshop-materials.qmd"  

list.files("~/get-started-quarto/")

 [1] "_extensions"              "_freeze"                 
 [3] "_quarto.yml"              "404.html"                
 [5] "404.qmd"                  "docs"                    
 [7] "index.html"               "index.qmd"               
 [9] "LICENSE.md"               "materials"               
[11] "preview-image-build.R"    "preview.jpeg"            
[13] "preview.png"              "README.md"               
[15] "schedule.qmd"             "site_libs"               
[17] "workshop-conf-2022.Rproj" "workshop-materials.qmd"  

Mental Model

Working left to right (parent to child)

list.files("~/get-started-quarto/materials")

 [1] "01-intro-quarto_files"      "01-intro-quarto.html"      
 [3] "01-intro-quarto.qmd"        "02-authoring.qmd"          
 [5] "02-authoring.rmarkdown"     "03-computation-editors.qmd"
 [7] "04-static-documents.qmd"    "05-presentations.qmd"      
 [9] "06-websites.qmd"            "07-plots-tables.qmd"       
[11] "08-advanced-knitr.qmd"      "images"                    
[13] "palmer-penguins.csv"        "resources_files"           
[15] "static"                     "test-layout.qmd"           
[17] "theme"                      "workshop"                  

list.files("../materials")

 [1] "01-intro-quarto_files"      "01-intro-quarto.html"      
 [3] "01-intro-quarto.qmd"        "02-authoring.qmd"          
 [5] "02-authoring.rmarkdown"     "03-computation-editors.qmd"
 [7] "04-static-documents.qmd"    "05-presentations.qmd"      
 [9] "06-websites.qmd"            "07-plots-tables.qmd"       
[11] "08-advanced-knitr.qmd"      "images"                    
[13] "palmer-penguins.csv"        "resources_files"           
[15] "static"                     "test-layout.qmd"           
[17] "theme"                      "workshop"                  

Referencing paths in R code

In code you can use here::here():

The goal of the here package is to enable easy file referencing in project-oriented workflows

list.files(here::here())

 [1] "_extensions"              "_freeze"                 
 [3] "_quarto.yml"              "404.html"                
 [5] "404.qmd"                  "docs"                    
 [7] "index.html"               "index.qmd"               
 [9] "LICENSE.md"               "materials"               
[11] "preview-image-build.R"    "preview.jpeg"            
[13] "preview.png"              "README.md"               
[15] "schedule.qmd"             "site_libs"               
[17] "workshop-conf-2022.Rproj" "workshop-materials.qmd"  

here() always starts at the top-level directory of a .RProj

here::here()

here::here()

[1] "/Users/thomasmock/get-started-quarto"

list.files(here::here())

 [1] "_extensions"              "_freeze"                 
 [3] "_quarto.yml"              "404.html"                
 [5] "404.qmd"                  "docs"                    
 [7] "index.html"               "index.qmd"               
 [9] "LICENSE.md"               "materials"               
[11] "preview-image-build.R"    "preview.jpeg"            
[13] "preview.png"              "README.md"               
[15] "schedule.qmd"             "site_libs"               
[17] "workshop-conf-2022.Rproj" "workshop-materials.qmd"  

here::here()

fs::file_info("preview.jpeg") |>  select(1:3)

# A tibble: 1 × 3
  path         type         size
  <fs::path>   <fct> <fs::bytes>
1 preview.jpeg <NA>           NA

fs::file_info(here::here("preview.jpeg")) |>  select(1:3)

# A tibble: 1 × 3
  path                                              type         size
  <fs::path>                                        <fct> <fs::bytes>
1 /Users/thomasmock/get-started-quarto/preview.jpeg file        3.08M

fs::file_info(here::here("materials/images/howard-gentleman.jpeg")) |>  select(1:3)

# A tibble: 1 × 3
  path                                                               type   size
  <fs::path>                                                         <fct> <fs:>
1 …masmock/get-started-quarto/materials/images/howard-gentleman.jpeg file   306K

# this also works
fs::file_info(here::here("materials", "images", "howard-gentleman.jpeg")) |>  select(1:3)

# A tibble: 1 × 3
  path                                                               type   size
  <fs::path>                                                         <fct> <fs:>
1 …masmock/get-started-quarto/materials/images/howard-gentleman.jpeg file   306K

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

Subfigures

::: {#fig-bostons layout-nrow=2}

![Excited](images/boston-terrier.png){#fig-boston width="250px"}

![Sleeping](images/boston-sleep.png){#fig-sleep width="250px"}

![Still Excited](images/boston-terrier.png){#fig-boston width="250px"}

![Still sleeping](images/boston-sleep.png){#fig-sleep width="250px"}

:::

Subfigures

Two states of Howard, twice

Subfigures

::: {layout-ncol="2"}
![Excited](images/boston-terrier.png){width="250px"}

![Sleeping](images/boston-sleep.png){width="250px"}

![Still Excited](images/boston-terrier.png){width="250px"}

![Still sleeping](images/boston-sleep.png){width="250px"}

Two states of Howard, twice
:::

Figure Divs

Note that the last paragraph in the div block is used as the figure caption.

::: {#fig-dog}

<iframe width="560" height="315" src="https://www.youtube.com/embed/U-WQ277UZtY"></iframe>

Funny boston terrier videos
:::

Figure Divs

Footnotes

Pandoc supports numbering and formatting footnotes.

Inline footnotes

Here is an inline note.^[Inlines notes are easier to write,
since you don't have to pick an identifier and move down to
type the note.]

Here is an inline note.¹

Inline footnotes

Here is an footnore reference[^1]

[^1]: This can be easy in some situations when you have a really long note or
don't want to inline complex outputs.

Cross References

Cross-references make it easier for readers to navigate your document by providing numbered references and hyperlinks to various entities like figures and tables.

![Elephant](elephant.png){#fig-elephant}

See @fig-elephant for an illustration.

Diagrams w/ mermaid

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