Documents: Figures/Tables + Code

Intro Quarto @ Cascadia R Conf

Charlotte Wickham

Posit, PBC

Tables

Markdown tables (aka Pipe Tables)

Markdown:

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

Output:

Right	Left	Default	Center
12	12	12	12
123	123	123	123
1	1	1	1

Grid tables

Markdown:

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

: Sample grid table.

Grid tables

Output:

Sample grid table.

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

Grid tables: Authoring

• Tables are awkward to write with a plain text editor.
• Use the Visual Editor!

Tables from code

The knitr package can turn data frames into tables with knitr::kable():

library(knitr)
library(palmerpenguins)

head(penguins) |> 
  kable()

species	island	bill_length_mm	bill_depth_mm	flipper_length_mm	body_mass_g	sex	year
Adelie	Torgersen	39.1	18.7	181	3750	male	2007
Adelie	Torgersen	39.5	17.4	186	3800	female	2007
Adelie	Torgersen	40.3	18.0	195	3250	female	2007
Adelie	Torgersen	NA	NA	NA	NA	NA	2007
Adelie	Torgersen	36.7	19.3	193	3450	female	2007
Adelie	Torgersen	39.3	20.6	190	3650	male	2007

Tables from code

If you want fancier tables, try the gt package and all that it offers!

library(gt)
library(palmerpenguins)

head(penguins) |> 
  gt() |>
  tab_style(
    style = list(
      cell_fill(color = "pink"),
      cell_text(style = "italic")
      ),
    locations = cells_body(
      columns = bill_length_mm,
      rows = bill_length_mm > 40
    )
  )

species	island	bill_length_mm	bill_depth_mm	flipper_length_mm	body_mass_g	sex	year
Adelie	Torgersen	39.1	18.7	181	3750	male	2007
Adelie	Torgersen	39.5	17.4	186	3800	female	2007
Adelie	Torgersen	40.3	18.0	195	3250	female	2007
Adelie	Torgersen	NA	NA	NA	NA	NA	2007
Adelie	Torgersen	36.7	19.3	193	3450	female	2007
Adelie	Torgersen	39.3	20.6	190	3650	male	2007

Cross references

Cross references

• Help readers to navigate your document with numbered references and hyperlinks to entities like figures and tables.

• Cross referencing steps:

  • Add a caption to your figure or table.
  • Give an id to your figure or table, starting with fig- or tbl-.
  • Refer to it with @fig-... or @tbl-....

A figure example

The presence of the caption (Blue penguin) and label (#fig-blue-penguin) make this figure referenceable:

Markdown:

See @fig-blue-penguin for a cute blue penguin.
![Blue penguin](images/blue-penguin.png){#fig-blue-penguin}

Output:

See Figure 1 for a cute blue penguin.

Figure 1: Blue Penguin

Figure cross references

Figure from a file:

![Caption](image.png){#fig-my-label}

Figure from code:

```{r}
#| label: fig-my-label
#| fig-cap: Caption

# ...
```

Table cross references

Markdown Table:

| Right | Left |
|------:|:-----|
|   12  |  12  |
|  123  |  123 |

: Caption {#tbl-my-label}

Table from code:

```{r}
#| label: tbl-my-label
#| tbl-cap: Caption

# ...
```

Your turn

• Open tables-figures.qmd.
• Follow the instructions in the document.
• Exchange one new thing you’ve learned with your neighbor.

08:00

Quarto Elements

Example: Callout Blocks

Use case: highlight content for the reader in multiple formats.

Markdown

:::{.callout-note}
Look - a squirrel!
:::

:::{.callout-important}
Look - a squirrel!
:::

:::{.callout-tip}
Look - a squirrel!
:::

HTML output

Note

Look - a squirrel!

Important

Look - a squirrel!

Tip

Look - a squirrel!

Callout Blocks

Highlight content for the reader in multiple formats.

Markdown

:::{.callout-note}
Look - a squirrel!
:::

:::{.callout-important}
Look - a squirrel!
:::

:::{.callout-tip}
Look - a squirrel!
:::

pdf output

Callout Blocks

Highlight content for the reader in multiple formats.

Markdown

:::{.callout-note}
Look - a squirrel!
:::

:::{.callout-important}
Look - a squirrel!
:::

:::{.callout-tip}
Look - a squirrel!
:::

docx output

Callouts are an example of a Fenced Div

One way Quarto extends the types of thing you can add to a document

Your turn

• Open callout-boxes.qmd and render the document.
• Change the type of the first callout box and then re-render. Also try adding attributes inside { } to learn what they do.
  • icon=true or icon=false.
  • appearance="simple" (can also try "minimal" and "default").
• Make the second callout box collapsible.
• Change the format to PDF and re-render.

05:00

Code

Quarto’s Code Cell

```{language}
#| echo: false

code
```

• Executable code flagged by {}
• Support R, Python, Julia
• Also support mermaid and dot diagram languages¹
• Cell options live inside the cell after #| (the hash pipe!)²

1. See https://quarto.org/docs/authoring/diagrams.html.

2. The hash pipe is available in the R Markdown too.

Compare to R Markdown’s Code Chunk

```{r, echo=FALSE}
rnorm(3)
```

• Only R (python chunks get executed in R)
• Options are set inside {}
• Option values are R, e.g. FALSE

Execution Options

Control how the code is executed with options.

Option	Description
eval	Evaluate the code chunk (if false, just echos the code into the output).
echo	Include the source code in output
output	Include the results of executing the code in the output (true, false, or asis to indicate that the output is raw markdown and should not have any of Quarto’s standard enclosing markdown).
warning	Include warnings in the output.
error	Include errors in the output.
include	Catch all for preventing any output (code or results) from being included (e.g. include: false suppresses all output from the code block).

Don’t forget to use ctrl-space to see the available options!

From Cell Option to YAML

---
title: My Doc
format: html
---

```{r}
#| echo: true

pi + 1
```

From Cell Option to YAML

---
title: My Doc
format: html
echo: true
---

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

• Options can be moved into YAML to apply to all chunks. Exceptions to that option can be set cell-by-cell.

From Cell Option to YAML

---
title: My Doc
format: html
echo: true
knitr:
  opts_chunk: 
    collapse: true
---

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

• Options can be moved into YAML to apply to all chunks. Exceptions to that option can be set cell-by-cell.

• You can also pass options via YAML to knitr through the knitr key¹.

1. No more ```{r setup}!

From Cell Option to YAML

---
title: My Doc
format: html
echo: true
knitr:
  opts_chunk: 
    collapse: true
    R.options:
      digits: 2
---

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

• • Options can be moved into YAML to apply to all chunks. Exceptions to that option can be set cell-by-cell.

• You can also pass options via YAML to knitr through the knitr key¹.

• You can use knitr to pass options that control your R session.

1. No more ```{r setup}!

Example: Figures from Code

```{r}
library(palmerpenguins)
library(ggplot2)

ggplot(penguins, aes(x = bill_length_mm,
                     y = bill_depth_mm,
                     col = island)) +
  geom_point()
```

Example: Figures from Code

```{r}
#| fig-width: 5
#| fig-height: 3

library(palmerpenguins)
library(ggplot2)

ggplot(penguins, aes(x = bill_length_mm,
                     y = bill_depth_mm,
                     col = island)) +
  geom_point()
```

Example: Figures from Code

```{r}
#| fig-width: 5
#| fig-height: 3
#| fig-cap: Size of penguins on three islands in the Palmer Archipelago.
#| fig-alt: Scatterplot showing the bill sizes of penguins across three islands.

library(palmerpenguins)
library(ggplot2)

ggplot(penguins, aes(x = bill_length_mm,
                     y = bill_depth_mm,
                     col = island)) +
  geom_point()
```

Size of penguins on three islands in the Palmer Archipelago.

Save time/code by moving figure sizing defaults up to the YAML.

Your turn

• Open code-cells.qmd and render the document.
• Add echo: false to the code cell and re-render.
• Add more cell options by using Ctrl + Space after the #| or consult the Quarto Reference.
• Add a second code cell (you can copy + paste the first), move your cell options to the YAML, and re-render.

07:00