---
title: "13.1 R Markdown: Chunks and Tables"
---

```{r}
#| label: setup
#| include: false
knitr::opts_chunk$set(
  echo = TRUE,
  message = FALSE,
  warning = FALSE,
  fig.width = 6,
  fig.height = 3.6,
  fig.align = "center",
  dpi = 120,
  error = TRUE,
  fig.path = "_figs/rmd-chunks-tables/"
)
library(tidyverse)
library(palmerpenguins)
```

Label chunks, set options, kable() a table, and include a child document.

## 1. Label every chunk

Note 1.4 covered Render, YAML, and `echo` / `eval` / `include`. This note is the next layer: names, defaults, tables, child files.

Give each chunk a unique **label**. Letters, digits, and hyphens are fine. The older fence `{r bill-summary}` is the same idea.

```{r}
#| label: bill-summary

penguins |> summarize(n = n())
```


2. Options that hide or skip work



Option
What it hides or skips




`eval`
If `false`, R does not run the chunk. The reader can still see the code.


`echo`
If `false`, the reader does not see the code. Results still appear.


`include`
If `false`, nothing from the chunk is printed. The code still runs if `eval` is true.


`warning`
If `false`, warnings are hidden.


`message`
If `false`, messages are hidden (`library()` chatter, `read_csv()` types).


`cache`
If `true`, knitr stores the result and skips a rerun when the chunk has not changed.



`include: false` is the usual setup chunk: load packages, read data. Later chunks need those objects. The reader does not need that boilerplate.

`cache: true` is a speed trick. Turn it off for a final Render so you are not looking at a stale object.

---

## 3. Defaults in a setup chunk

Set the usual rules once with `knitr::opts_chunk$set()`. A later chunk can override one option.

```{r}
#| label: setup-doc-2
#| include: false

knitr::opts_chunk$set(
  echo = TRUE,
  message = FALSE,
  warning = FALSE
)
```

Quarto's YAML `execute:` block (note 1.4) does the same job. Either is fine. This week we use `opts_chunk$set()` so the habit works in an old `.Rmd` as well as a `.qmd`.

---

## 4. Tables with `kable()`

`print()` of a tibble is readable in the console. In a report, pass the table to `knitr::kable()` and give it a caption.

```{r}
#| label: chunk-1
penguins |>
  group_by(species) |>
  summarize(
    mean_bill = mean(bill_length_mm, na.rm = TRUE),
    n = n(),
    .groups = "drop"
  ) |>
  knitr::kable(caption = "Mean bill length (mm) by species.", digits = 1)
```

`digits` rounds numbers. `{kableExtra}` can style rows; we do not need it this week.

---

## 5. Folding code in the YAML

R Markdown:

output:
  html_document:
    code_folding: hide

Quarto:

format:
  html:
    code-fold: true

`hide` / `true` starts with the chunks collapsed. The reader can open one.

---

## 6. Child documents

A long report can pull in another file with a chunk option such as `child = "helper.qmd"` (R Markdown) or `#| child: helper.qmd` (Quarto). That helper file is not knit as its own document here — it is only an example of the syntax.

The child's YAML is **ignored**. Title, author, and `format:` live only in the parent. The child is just Markdown plus chunks, run in the parent's session.

Labels must stay unique across parent and child. If a helper also has a chunk named `setup`, rename one of them.

---

## 7. Load a package only if it is missing

When a child (or a chunk you rerun) would call `library(tidyverse)` a second time, skip it:

```{r}
#| label: load-if-missing
#| eval: false

library(tidyverse)
```

`.packages()` is the character vector of attached packages. The `!` flips the test: evaluate the chunk only when tidyverse is **not** already loaded.

The same idea for data: `eval = !exists("penguins")`.

---

## 8. Practice

1. List four chunk options and say what each one hides (or skips).
2. Write a setup chunk that sets `echo = TRUE` and `message = FALSE` for the whole document.