Tables And Figures

---
name: tables-and-figures
description: Use when generating a LaTeX results table, creating a figure for a paper, formatting descriptive statistics, preparing regression output for publication, or producing vector-quality graphics. Enforces booktabs, threeparttable, vector PDFs, and script-generated output.
---

# Tables and Figures

## Overview

This skill produces publication-quality tables and figures that are regenerated by scripts, not hand-edited. Tables use `booktabs` for professional rules and `threeparttable` for integrated notes. Figures are vector PDFs — PNG and JPG are forbidden in the final paper. Every table and figure comes from a script under `code/` and is included in the paper via `\input{}` or `\includegraphics{}`.

## When to Use

- "Make a table of descriptive statistics"
- "Format the regression results for the paper"
- "Create a figure showing X over time"
- "Generate the event-study plot"
- Preparing final outputs for submission
- Re-running the analysis after data changes

## Mandatory Steps

1. **Generate every table and figure from a script** in `code/` that reads from `data/processed/` and writes to `output/tables/` or `output/figures/`. Never hand-edit the output file.

2. **Use booktabs rules in tables.** `\toprule`, `\midrule`, `\bottomrule`. Never `\hline`. Never vertical bars.

3. **Wrap every table in `threeparttable`** with a notes block documenting: standard error type, significance convention, sample, data source.

4. **Save figures as vector PDF.** Use ggplot2 with `ggsave(..., device = cairo_pdf)` in R, or `matplotlib.pyplot.savefig(..., format='pdf')` in Python. Raster formats (PNG, JPG) are forbidden in the final paper.

5. **Include in the paper with `\input{}` or `\includegraphics{}`.** Never paste numbers or copy images.

6. **Use the naming convention:**
   - Tables: `tab_<purpose>.tex` — `tab_descriptives.tex`, `tab_main_results.tex`, `tab_robustness.tex`
   - Figures: `fig_<purpose>.pdf` — `fig_event_study.pdf`, `fig_trends.pdf`

7. **Table notes and figure captions follow the user's paper language.** The file names and script comments stay in English; the user-facing text in the notes and captions follows the paper's language setting.

8. **No table may overflow the text width.** After generating a table, verify it fits within `\linewidth`. If it overflows:
   - First, reduce column padding with `@{}` column separators or `\setlength{\tabcolsep}{3pt}`.
   - Second, abbreviate column headers or use multi-row headers.
   - Third, use `\resizebox{\linewidth}{!}{...}` — but only if font remains readable.
   - Last resort: switch the table page to landscape using the `pdflscape` package (`\begin{landscape}...\end{landscape}`). Add `\usepackage{pdflscape}` to the preamble.
   Never let a table bleed into the margin. After compilation, check for `Overfull \hbox` warnings on table lines and fix them.

## Table Template

Standard regression results table:

```latex
\begin{table}[htbp]
\centering
\begin{threeparttable}
\caption{Main Results}
\label{tab:main}
\begin{tabular}{lcc}
\toprule
 & (1) & (2) \\
 & OLS & FE \\
\midrule
Treatment & 0.123*** & 0.098** \\
          & (0.034)  & (0.041) \\
\midrule
N         & 10{,}234 & 10{,}234 \\
R$^2$     & 0.42     & 0.58     \\
\bottomrule
\end{tabular}
\begin{tablenotes}[flushleft]
\footnotesize
\item \textit{Notes:} Standard errors clustered at the state level in parentheses. * p$<$0.10, ** p$<$0.05, *** p$<$0.01. Sample covers 2010--2020. Data: IBGE PNADC.
\end{tablenotes}
\end{threeparttable}
\end{table}
```

Required packages in paper preamble:

```latex
\usepackage{booktabs}
\usepackage{threeparttable}
```

## Significance Convention

**Default:** `* p<0.10, ** p<0.05, *** p<0.01` (economics and finance convention).

**Alternative:** `* p<0.05, ** p<0.01, *** p<0.001` (common in psychology and medicine).

Detect the convention by reading `CLAUDE.superpapers.md` from the current working directory, or walking up parent directories until found, and using the `significance_convention` field. If the file is absent or the field is unset, ask the user — do not silently default. Always document the convention in the table note; do not assume the reader knows which convention is used.

## Figure Standards

- **Format:** Vector PDF only. No PNG, JPG, or other raster formats in the final paper.
- **Generator:** ggplot2 in R (preferred) or matplotlib/seaborn in Python, or native LaTeX via tikz/pgfplots.
- **Theme:** `theme_minimal()` or `theme_classic()` in ggplot2, with adjustments for print. Avoid grey backgrounds from ggplot2's default theme.
- **Colors:** Colorblind-safe palettes (`viridis`, `RColorBrewer` Dark2 or Set1). For B&W print compatibility, use dash patterns or shapes rather than relying on color alone.
- **Titles:** Do not embed plot titles in the figure. The title goes in the LaTeX caption.
- **Axis labels:** Clear, with units (`Unemployment rate (%)`, `Year`, `Real GDP (log)`).
- **Legend:** Minimal. Remove if only one series.
- **Saving:** `ggsave("output/figures/fig_name.pdf", width = W, height = H, device = cairo_pdf)`.

Example figure code (R/ggplot2):

```r
library(ggplot2)

p <- ggplot(data, aes(x = year, y = unemployment, color = region)) +
  geom_line(linewidth = 0.8) +
  scale_color_viridis_d(option = "D") +
  labs(x = "Year", y = "Unemployment rate (%)", color = NULL) +
  theme_minimal(base_size = 11) +
  theme(
    legend.position = "bottom",
    panel.grid.minor = element_blank()
  )

ggsave(
  "output/figures/fig_unemployment.pdf",
  plot = p,
  width = 6.5, height = 4,
  device = cairo_pdf
)
```

## Anti-Patterns

- Tables using `\hline` instead of booktabs rules
- Tables with vertical bars (`|`)
- Tables without a notes block
- Figures saved as PNG or JPG in the final paper
- Hand-edited `.tex` table files
- Significance convention undocumented in the note
- Figures with embedded titles clashing with LaTeX captions
- Missing sample description in the table note
- Using ggplot2's default grey background theme in published figures
- Color-only differentiation in figures intended for B&W print
- Tables that overflow into the page margin without correction
- Using `\resizebox` as a first resort instead of redesigning column layout or reducing padding
- Wide tables left in portrait when landscape would preserve readability

## Verification Before Completion

- [ ] Every table and figure generated by a script in `code/`
- [ ] Outputs in `output/tables/` or `output/figures/`
- [ ] Tables use `booktabs` and `threeparttable`
- [ ] Significance convention documented in every results table note
- [ ] Figures are vector PDFs
- [ ] No titles embedded in figures
- [ ] Axis labels and units specified
- [ ] Colors colorblind-safe where feasible
- [ ] Table notes and figure captions in the user's paper language
- [ ] No table overflows the text width or bleeds into margins
- [ ] Wide tables use landscape orientation or column optimization to remain readable