Skip to content

DAAF-Contribution-Community/daaf / .claude/skills/quarto

quarto

Verified

Quarto document system for R: .qmd format with knitr engine, YAML frontmatter, code chunks with execution options, rendering to HTML/PDF. DAAF's R notebook format — Stage 9 literally archives executed R scripts in globally and per-chunk non-evaluating chunks paired with real execution logs. Optional display-only content may preview existing Parquet data or show already-created figures, but may not analyze data or generate figures. Use when execution language is R. Python equivalent: marimo.

FileKindSize
SKILL.mdskill md15.9 KB
references/chunks.mdmarkdown7.8 KB
references/daaf-notebook.mdmarkdown14.0 KB
references/figures.mdmarkdown6.3 KB
references/format.mdmarkdown9.6 KB
references/gotchas.mdmarkdown16.9 KB
references/quickstart.mdmarkdown6.5 KB
references/rendering.mdmarkdown7.6 KB
references/tables.mdmarkdown9.2 KB

references/tables.md

View on GitHub
# Tables

## Table Output Methods

Three approaches for tables in Quarto documents, from simplest to most powerful:

| Method | Package | Best For |
|--------|---------|----------|
| `knitr::kable()` | knitr (built-in) | Simple tables, quick output |
| `kableExtra` | kableExtra | Styled tables with formatting |
| `gt::gt()` | gt | Publication-quality tables |

## knitr::kable()

The simplest table output. No additional packages needed:

````markdown
```{r}
#| label: tbl-basic
#| tbl-cap: "Summary of enrollment data"

df |>
  head(10) |>
  knitr::kable()
```
````

### kable Options

```r
knitr::kable(
  df,
  digits = 2,           # Decimal places
  col.names = c("Year", "Count", "Mean"),  # Column headers
  align = c("l", "r", "r"),               # l=left, c=center, r=right
  format.args = list(big.mark = ",")       # Thousands separator
)
```

| Argument | Purpose | Example |
|----------|---------|---------|
| `digits` | Decimal places | `2` |
| `col.names` | Custom column names | `c("A", "B")` |
| `align` | Column alignment | `c("l", "r")` |
| `caption` | Table caption (prefer `tbl-cap` chunk option) | `"My table"` |
| `format.args` | Formatting options | `list(big.mark = ",")` |

### kable with Pipe

```r
df |>
  group_by(year) |>
  summarize(
    n = n(),
    mean_value = mean(value, na.rm = TRUE)
  ) |>
  knitr::kable(digits = 1, col.names = c("Year", "N", "Mean"))
```

## kableExtra

Enhanced styling on top of kable. Load the package:

```r
library(kableExtra)
```

### Basic Styled Table

```r
df |>
  knitr::kable() |>
  kable_styling(
    bootstrap_options = c("striped", "hover", "condensed"),
    full_width = FALSE,
    position = "center"
  )
```

### Bootstrap Options (HTML)

| Option | Effect |
|--------|--------|
| `"striped"` | Alternating row colors |
| `"hover"` | Highlight on mouse hover |
| `"condensed"` | Reduced padding |
| `"bordered"` | Cell borders |
| `"responsive"` | Horizontal scroll on overflow |

### Column Formatting

```r
df |>
  knitr::kable() |>
  kable_styling() |>
  column_spec(1, bold = TRUE) |>
  column_spec(3, color = "red", width = "3cm")
```

### Row Formatting

```r
df |>
  knitr::kable() |>
  kable_styling() |>
  row_spec(0, bold = TRUE, color = "white", background = "#4472C4") |>
  row_spec(c(3, 5), background = "#FFFFCC")
```

Row 0 is the header row.

### Grouped Rows

```r
df |>
  knitr::kable() |>
  kable_styling() |>
  pack_rows("Group A", 1, 3) |>
  pack_rows("Group B", 4, 6)
```

### Footnotes

```r
df |>
  knitr::kable() |>
  kable_styling() |>
  footnote(
    general = "Source: CCD 2022",
    number = c("Enrollment in thousands", "Missing data excluded")
  )
```

### kableExtra in LaTeX PDF

kableExtra renders in a LaTeX PDF (`format: pdf`), including `booktabs` and
`latex_options`. For a numbered, cross-referenceable table, put the label and
caption on the chunk and leave `caption =` out of `kbl()`:

````markdown
```{r}
#| label: tbl-cars
#| tbl-cap: "Fuel economy by car"
#| echo: false

library(kableExtra)
kbl(head(mtcars[, 1:4]), booktabs = TRUE) |>
  kable_styling(latex_options = c("striped", "hold_position"))
```

See @tbl-cars.
````

Leave `format =` out of `kbl()` in a Quarto chunk, so knitr picks the format of
the output being rendered. A hard-coded `kbl(format = "html")` stops a LaTeX
PDF render (exit 1, no PDF written) with:

```
Error: Functions that produce HTML output found in document targeting pdf output.
```

The `prefer-html: true` option that Quarto suggests next is no fix: the same
message says "the HTML output will not be visible in non-HTML formats".

Rendered with Quarto 1.10.18, this prints no warning, captions the table
"Table 1: Fuel economy by car" and resolves `@tbl-cars` to "Table 1". The two
other forms both print Quarto's warning:

```
WARNING (.../main.lua:18332) Raw LaTeX table found with non-tbl label: tab:tbl-cars
Won't be able to cross-reference this table using Quarto's native crossref system.
```

- `caption =` in `kbl()` with a `tbl-` label: the table renders, but the numbers
  disagree: in a one-table document its caption reads "Table 2" while
  `@tbl-cars` reads "Table 1".
- `caption =` in `kbl()` with no label: the table renders with its caption
  (the warning names `tab:unnamed-chunk-1`), and it cannot be cross-referenced.

kableExtra does not work in a Typst PDF: its HTML output stops the render, and
a LaTeX-format table is silently left out (see "Choosing a Table Method").

## gt Tables

The gt package produces publication-quality tables with a grammar-of-tables
approach. Most powerful but most verbose:

```r
library(gt)
```

### Basic gt Table

````markdown
```{r}
#| label: tbl-gt-basic
#| tbl-cap: "Enrollment by state"

df |>
  group_by(state) |>
  summarize(
    schools = n(),
    total_enrollment = sum(enrollment)
  ) |>
  gt()
```
````

### Formatted gt Table

```r
df |>
  gt() |>
  tab_header(
    title = "School Enrollment Summary",
    subtitle = "Academic Year 2023-24"
  ) |>
  fmt_number(
    columns = enrollment,
    decimals = 0,
    use_seps = TRUE
  ) |>
  fmt_percent(
    columns = pct_change,
    decimals = 1
  ) |>
  cols_label(
    state = "State",
    enrollment = "Total Enrollment",
    pct_change = "% Change"
  )
```

### gt Formatting Functions

| Function | Purpose | Example |
|----------|---------|---------|
| `fmt_number()` | Number formatting | Thousands separators, decimals |
| `fmt_percent()` | Percentage formatting | 0.15 -> 15.0% |
| `fmt_currency()` | Currency formatting | 1234 -> $1,234 |
| `fmt_date()` | Date formatting | ISO to readable |
| `sub_missing()` | Missing value display | NA -> "---" (`fmt_missing()` is deprecated since gt 0.6.0) |

### gt Styling

```r
df |>
  gt() |>
  tab_style(
    style = cell_fill(color = "#F0F0F0"),
    locations = cells_body(rows = seq(1, nrow(df), 2))
  ) |>
  tab_style(
    style = cell_text(weight = "bold"),
    locations = cells_column_labels()
  )
```

### gt Source Notes

```r
df |>
  gt() |>
  tab_source_note("Source: Common Core of Data, 2022") |>
  tab_source_note("Note: Enrollment figures rounded to nearest hundred")
```

### gt Spanners (Column Groups)

```r
df |>
  gt() |>
  tab_spanner(
    label = "Demographics",
    columns = c(white, black, hispanic)
  ) |>
  tab_spanner(
    label = "Outcomes",
    columns = c(grad_rate, dropout_rate)
  )
```

## Cross-Referencing Tables

To create a cross-referenceable table:
1. Use a `tbl-` prefixed label
2. Add a `tbl-cap`
3. Reference with `@tbl-label`

````markdown
```{r}
#| label: tbl-demographics
#| tbl-cap: "School demographics by district type"

df |>
  group_by(district_type) |>
  summarize(across(white:hispanic, mean)) |>
  knitr::kable(digits = 1)
```

As shown in @tbl-demographics, urban districts have higher diversity.
````

Requirements:
- Label MUST start with `tbl-`
- Caption (`tbl-cap`) MUST be present
- Reference uses `@` prefix

The reference renders as "Table 1" (or appropriate number).

## Multiple Tables

### Side-by-Side Tables

````markdown
```{r}
#| label: tbl-comparison
#| tbl-cap: "Comparison tables"
#| tbl-subcap:
#|   - "Public schools"
#|   - "Private schools"
#| layout-ncol: 2

public_df |> head(5) |> knitr::kable()
private_df |> head(5) |> knitr::kable()
```
````

### Panel Tables (gt)

gt supports grouped/panel layouts natively:

```r
df |>
  gt(groupname_col = "category") |>
  tab_header(title = "Results by Category")
```

## Choosing a Table Method

| Need | Use |
|------|-----|
| Quick data display | `knitr::kable()` |
| Styled HTML tables | `kableExtra` |
| Publication-quality | `gt` |
| LaTeX PDF (`format: pdf`) | Any method (`gt` renders in both PDF paths). kableExtra renders without a label; for a clean caption and cross-reference give it a `tbl-` label and `tbl-cap` with no `caption =` and no `format =` in `kbl()` (see "kableExtra in LaTeX PDF") |
| Typst PDF (`format: typst`) | `gt`, or `knitr::kable()` with no `format =`. Not kableExtra: `kbl()` and its styling functions produce HTML there, which stops a Typst render with "Functions that produce HTML output found in document targeting typst output". A table hard-coded to `format = "latex"` (from `kbl()` or `knitr::kable()`) is worse: the render exits 0 with the caption in the PDF but the table silently dropped, with no warning (Quarto 1.10.18) |
| Cross-referenced | Any method + `tbl-` label + `tbl-cap` |

For DAAF Stage 9 notebooks, do not add a `knitr::kable()` table. The canonical
data preview is exactly `arrow::read_parquet()` + `dplyr::glimpse()` +
`head()` in its permitted preview chunk. Formatted tables belong in already-
executed Stage 8 scripts and may be referenced as existing outputs rather than
created in the notebook.

## Tips

1. **Always use `tbl-cap`** for any table you want to cross-reference
2. **Use `tbl-` prefix on labels** -- cross-references require it
3. **Use the canonical Stage 9 preview unchanged** -- `arrow::read_parquet()` + `dplyr::glimpse()` + `head()`; do not add `kable()`, `gt()`, or formatting code there
4. **Use gt for reports or executed Stage 8 outputs** -- its formatting capabilities justify the verbosity
5. **Test PDF output** if targeting PDF -- kableExtra renders in a LaTeX PDF (`format: pdf`) but not in a Typst PDF (see "Choosing a Table Method")
6. **Format numbers consistently** -- use `digits` in kable or `fmt_number` in gt outside Stage 9 preview chunks
deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall