brycewang-stanford/tables-and-figures

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:

\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:

\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):

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