great-tables-python
Use for writing, reviewing, debugging, or testing publication-quality display tables in Python with Great Tables, including GT construction, stub and row groups, headers and spanners, labels, numeric/
SKILL.mdskills/great-tables-python/SKILL.md
GitHubGreat Tables Python
Build a display table as an output artifact. Transform and validate data before
GT; then use the table pipeline to communicate structure, formatting,
annotation, and emphasis without changing analytical values.
Boundary
Use this skill when a project imports great_tables or explicitly requests
Great Tables. Do not use a GT object as a dataframe, compute business metrics
inside presentation formatting, replace an interactive grid, or route a chart
request here. Preserve the required render boundary: notebook/browser, HTML
fragment/page, LaTeX, image, or PDF.
Know the objects
| Object | Meaning | Responsibility |
|---|---|---|
| Input dataframe | Analytical rows and columns | Own filtering, sorting, grouping calculations, joins, and typed values. |
GT |
Chainable display-table specification | Own visible structure, labels, formatting, annotation, styles, options, and export. |
| Stub / row group | Row-label and hierarchical row structure | Give records readable identity; not a hidden dataframe index. |
| Column label / spanner | Header hierarchy | Group contiguous related columns with stable IDs when later referenced. |
| Formatter | Converts stored values to displayed text | Currency, number, percent, date/time, missing text, locale; values remain analytical inputs. |
loc / selector |
Targets a structural region or subset | Scope styles/footnotes precisely. |
| Render/export method | Materializes host-specific output | HTML, LaTeX, browser/notebook display, raster/PDF with external renderer. |
Read the display-table model before choosing stub, groups, column order, spanners, or annotations.
Ordered workflow
- Recover the audience, output host, row grain, sort order, units, locale, significant digits, missing-value wording, and accessibility requirements.
- Prepare a small typed dataframe containing only display rows and fields. Compute totals, ranks, percentages, and flags upstream and test them there.
- Create
GT(data, ...); define stub and row groups only from stable columns. - Establish structure before decoration: title/subtitle, column order and labels, spanners, stubhead, group labels, source notes, and footnotes.
- Apply semantic formatting by column/row target. Do not convert numeric/date columns to strings upstream merely for commas or symbols.
- Apply minimal targeted styling after formatting. Derive emphasis from an explicit data condition, not hard-coded row positions when rows can reorder.
- Export through the method matching the artifact. Verify values and structure separately from the rendered appearance and environment prerequisites.
Intent to API family
| Intent | Use | Invariant |
|---|---|---|
| Title/subtitle | tab_header |
States subject and scope; does not repeat every column. |
| Human row identity | stub / rowname_col |
Labels remain unique within their declared group. |
| Row sections | groupname_col / row-group methods |
Input ordering and group membership are deliberate. |
| Group related columns | tab_spanner |
Selected columns are contiguous or movement from gather is explicitly accepted. |
| Rename visible columns | column-label methods | Source field names remain traceable. |
| Currency/number/percent/date | matching fmt_* method |
Units, locale, decimals/significant figures, and missing values are defined. |
| Conditional text/value transformation | substitution/format APIs or upstream derived field | Raw analytical meaning is preserved and tested. |
| Highlight cells | tab_style(style=..., locations=loc...) |
Target is structural/condition-based and styling has semantic purpose. |
| Explain a value | footnote targeted to label/body location | Marker and source remain unambiguous. |
| Embed in application/email | as_raw_html with appropriate fragment/page/CSS mode |
Raw HTML trust and host CSS policy are explicit. |
| Publication file | gtsave, LaTeX, or raw HTML boundary |
Required browser/render dependencies and output file are verified. |
Canonical anchor
from great_tables import GT, md
def revenue_table(data):
# variance_pct contains proportions: 0.125 means 12.5%.
return (
GT(data, rowname_col="region", locale="en")
.tab_header(
title="Regional revenue",
subtitle=md("Reported in **USD**"),
)
.tab_spanner(
label="Revenue",
columns=["actual", "budget"],
id="revenue",
)
.fmt_currency(columns=["actual", "budget"], currency="USD")
.fmt_percent(columns="variance_pct", decimals=1)
)
Return the GT object from builders. Do not call show() or write a file in a
pure table-construction function. fmt_percent scales proportional inputs by
100 by default. If the source already stores percentage points, declare that
contract and set the installed API's no-scaling option explicitly.
Formatting and styling rules
- Formatting controls representation; styling controls appearance. Do not use CSS color to encode the only copy of a value or status.
- Prefer semantic formatter methods to upstream string formatting so sorting, filtering, summaries, and formatter targeting retain typed values.
- Use an explicit locale at the table or formatter boundary when separators, symbols, dates, or language are contractual.
- Choose decimals or significant figures from measurement precision; never imply precision absent from the source.
- Give later-referenced spanners explicit stable IDs. A label containing markup is not a reliable identifier.
- Treat
html(...)as trusted raw markup. Do not pass untrusted data through it; use escaped/plain text or a sanitized policy.
Read formatting and styling.
Render boundary and verification
HTML fragments, full pages, email-inline CSS, LaTeX, and browser-captured
images have different requirements. Image/PDF export can require a browser and
optional renderer packages; successful GT construction does not prove export.
Read render and testing.
Inspect the installed version of Great Tables before using drift-sensitive formatter, selector, spanner, or export signatures. The package was absent from this foundry during authoring, so examples are official-source-grounded but not locally rendered.
Completion requires: input values/grain/order tested upstream; visible labels, units, locale, rounding, and missing text correct; spanner/stub/group structure matches the contract; styles target intended cells after reordering; raw HTML is trusted or avoided; the requested artifact exists and renders in its real host; and missing browser/font/export evidence is reported rather than assumed.