DAAF-Contribution-Community/daaf / .claude/skills/quarto
quarto
VerifiedQuarto 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 15.9 KB |
| references/chunks.md | markdown | 7.8 KB |
| references/daaf-notebook.md | markdown | 14.0 KB |
| references/figures.md | markdown | 6.3 KB |
| references/format.md | markdown | 9.6 KB |
| references/gotchas.md | markdown | 16.9 KB |
| references/quickstart.md | markdown | 6.5 KB |
| references/rendering.md | markdown | 7.6 KB |
| references/tables.md | markdown | 9.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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 119k | Updated | Claude CodeCodex | Verified | Install |
| 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: 119k | Updated | Claude CodeCodex | Verified | Install |
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |