great_tables

Recreating Septa Transit Timetables in Python

Michael Chow and Rich Iannone — Thu, 12 Mar 2026 00:00:00 GMT

Recently, Rich and I were poking around transit data, and we were struck by the amount of structuring that goes into transit timetables.

For example, consider this weekend rail schedule table from SEPTA, Philadelphia’s transit agency.

Notice these big pieces:

The vertical text on the left indicating trains are traveling “TO CENTER CITY”.
The blue header, and spanner columns (“Services” and “Train Number”) grouping related columns.
The striped background for easier reading. Also the black background indicating stations in Center City (the urban core).

Tables like this often have to be created in tools like Illustrator, and updated by hand. At the same time, when agencies automate table creation, they often sacrifice a lot of the assistive features and helpful affordances of the table.

We set out to recreate this table in Great Tables (and by we I mean 99% Rich). In this post, I’ll walk quickly through how we recreated it, and share some other examples of transit timetables in the wild. For the theory behind why tables like this are useful, see The Design Philosophy of Great Tables.

The final result

Here’s a look at our quick version in Great Tables. In this post we’ll walk through quickly how we created it, but wanted to treat you to the final result up front! Note that the table is fully in HTML for accessibility.

Code

Great Tables v0.18.0: Easy Column Spanners and More!

Rich Iannone — Fri, 18 Jul 2025 00:00:00 GMT

The development of Great Tables continues! We’re excited to announce the release of v0.18.0, which brings several powerful new features. These features make it even easier to create beautiful, informative tables. The key additions in this release include new methods (and a tweak to an existing one):

.tab_spanner_delim(): quick spanner creation
.fmt_tf(): easy boolean value formatting
.cols_label_rotate(): enables column label rotation
.fmt_datetime(): added format_str= parameter for extra customization

Let’s explore each of these interesting new features!

Quick spanner creation with `tab_spanner_delim()`

Working with data that has hierarchical column names can be tedious when manually creating spanners. The new .tab_spanner_delim() method automates this process by intelligently splitting column names based on a delimiter and creating the appropriate spanner structure.

Here’s a practical example using the towny dataset, which contains population data for a collection of municipalities across multiple census years. Let’s start by looking at the most populated cities and examining their column structure:

from great_tables import GT
from great_tables.data import towny
import polars as pl
import polars.selectors as cs

# Create a smaller version of the `towny` dataset
towny_mini = (
    pl.from_pandas(towny)
    .filter(pl.col("csd_type") == "city")
    .sort("population_2021", descending=True)
    .select(
        "name",
        cs.starts_with("population_"),
        cs.starts_with("density_")
    )
    .head(5)
)

# Let's look at the column names
print(towny_mini.columns)

['name', 'population_1996', 'population_2001', 'population_2006', 'population_2011', 'population_2016', 'population_2021', 'density_1996', 'density_2001', 'density_2006', 'density_2011', 'density_2016', 'density_2021']

Notice how the column names have a clear hierarchical structure with underscores as delimiters. Let’s now create a table that takes advantage of this structure:

(
    GT(towny_mini, rowname_col="name")
    .tab_spanner_delim(delim="_")
    .fmt_integer(columns=cs.contains("population"))
    .fmt_number(columns=cs.contains("density"), decimals=1)
    .tab_header(title="Population and Density Trends from Census Data")
    .opt_align_table_header(align="left")
)

	population						density
Population and Density Trends from Census Data
	1996	2001	2006	2011	2016	2021	1996	2001	2006	2011	2016	2021
Toronto	2,385,421	2,481,494	2,503,281	2,615,060	2,731,571	2,794,356	3,779.8	3,932.0	3,966.5	4,143.6	4,328.3	4,427.8
Ottawa	721,136	774,072	812,129	883,391	934,243	1,017,449	258.6	277.6	291.3	316.8	335.1	364.9
Mississauga	544,382	612,925	668,599	713,443	721,599	717,961	1,859.6	2,093.8	2,283.9	2,437.1	2,465.0	2,452.6
Brampton	268,251	325,428	433,806	523,906	593,638	656,480	1,008.9	1,223.9	1,631.5	1,970.4	2,232.7	2,469.0
Hamilton	467,799	490,268	504,559	519,949	536,917	569,353	418.3	438.4	451.2	464.9	480.1	509.1

The .tab_spanner_delim() method recognizes the underscore delimiter and creates a hierarchical structure: "population" and "density" become top-level spanners, with the years (1996, 2001, 2021) as the final column labels. This creates a clean, organized appearance that clearly groups related metrics together. And, this one method can be used instead of a combination of .cols_label() and .tab_spanner() (which requires a separate invocation per spanner added).

Beautiful boolean formatting with `fmt_tf()`

Boolean data is common in analytical tables, but raw True/False values can look unprofessional. The new .fmt_tf() method provides elegant ways to display boolean data using symbols, words, or custom formatting.

Here’s a simple example showing different tf_style= options:

from great_tables import GT
import polars as pl

# Create a simple DF with boolean data
bool_df = pl.DataFrame({
    "feature": ["Premium Sound", "Leather Seats", "Sunroof", "Navigation"],
    "model_a": [True, False, True, True],
    "model_b": [True, True, False, True],
    "model_c": [False, True, True, False]
})

(
    GT(bool_df, rowname_col="feature")
    .fmt_tf(tf_style="check-mark", colors=["green", "red"])
    .tab_header(title="Car Features Comparison", subtitle="Using check-mark style")
)

	model_a	model_b	model_c
Car Features Comparison
Using check-mark style
Premium Sound	✔	✔	✘
Leather Seats	✘	✔	✔
Sunroof	✔	✘	✔
Navigation	✔	✔	✘

You can also use different symbols and colors for a more distinctive look:

(
    GT(bool_df, rowname_col="feature")
    .fmt_tf(tf_style="circles", colors=["#4CAF50", "#F44336"])
    .tab_header(title="Car Features Comparison", subtitle="Using circles style")
)

	model_a	model_b	model_c
Car Features Comparison
Using circles style
Premium Sound	●	●	⭘
Leather Seats	⭘	●	●
Sunroof	●	⭘	●
Navigation	●	●	⭘

The .fmt_tf() method transforms boolean values into visually appealing symbols that make it easy to quickly scan and compare data across rows and columns.

Rotating column labels with `cols_label_rotate()`

When dealing with many columns or long column names, horizontal space becomes precious. The .cols_label_rotate() method solves this by rotating column labels vertically, allowing for more compact table layouts.

Here’s an example where we use the gtcars dataset to create a table which communicates a feature matrix:

from great_tables import GT, style, loc
from great_tables.data import gtcars
import polars as pl
import polars.selectors as cs

# Manipulate dataset to create a feature comparison table
gtcars_mini = (
    pl.from_pandas(gtcars)
    .filter(pl.col("year") == 2017)
    .filter(pl.col("ctry_origin").is_in(["Germany", "Italy", "United Kingdom"]))
    .with_columns([
        (pl.col("hp") > 500).alias("High Power"),
        (pl.col("mpg_h") > 25).alias("Fuel Efficient"),
        (pl.col("drivetrain") == "awd").alias("All Wheel Drive"),
        (pl.col("msrp") > 100000).alias("Premium Price"),
        (pl.col("trsmn").str.contains("manual")).alias("Manual Transmission")
    ])
    .select([
        "mfr", "model", "trim",
        "High Power",
        "Fuel Efficient",
        "All Wheel Drive",
        "Premium Price",
        "Manual Transmission"
    ])
    .head(10)
)

(
    GT(gtcars_mini)
    .fmt_tf(
        columns=cs.by_dtype(pl.Boolean),
        tf_style="check-mark",
        colors=["#2E8B57", "#DC143C"]
    )
    .cols_label_rotate(
        columns=cs.by_dtype(pl.Boolean),
        dir="sideways-lr"
    )
    .tab_header(
        title="European Luxury Cars Feature Matrix",
        subtitle="2017 Models with Performance & Luxury Features"
    )
    .opt_stylize(style=1)
    .tab_style(
        style=style.text(size="11px"),
        locations=loc.body()
    )
)

mfr	model	trim	High Power	Fuel Efficient	All Wheel Drive	Premium Price	Manual Transmission
European Luxury Cars Feature Matrix
2017 Models with Performance & Luxury Features
Ferrari	GTC4Lusso	Base Coupe	✔	✘	✔	✔	✘
Aston Martin	DB11	Base Coupe	✔	✘	✘	✔	✘
Lotus	Evora	2+2 Coupe	✘	✘	✘	✘	✘
Porsche	718 Boxster	Base Convertible	✘	✔	✘	✘	✘
Porsche	718 Cayman	Base Coupe	✘	✔	✘	✘	✘

This example demonstrates how both the .fmt_tf() and .cols_label_rotate() methods can work well together. The boolean columns use checkmarks (✓/✗) with custom colors=, while the rotated labels save horizontal space in this dense feature matrix. The combination allows you to put more information into a compact and still readable format.

Enhanced datetime formatting with `fmt_datetime()`

The .fmt_datetime() method now supports custom format strings through the new format_str= parameter, giving you complete control over how datetime values appear in your tables.

Here’s an example using the included gibraltar weather dataset:

from great_tables import GT
from great_tables.data import gibraltar
import polars as pl

# Prepare the meteorological data
gibraltar_mini = (
    pl.from_pandas(gibraltar)
    .with_columns(
        [
            pl.concat_str([pl.col("date"), pl.lit(" "), pl.col("time")])
            .str.strptime(pl.Datetime, format="%Y-%m-%d %H:%M")
            .alias("datetime")
        ]
    )
    .filter(pl.col("datetime").dt.hour().is_in([6, 12, 18]))
    .select(["datetime", "temp", "humidity", "condition"])
    .sort("datetime")
    .head(10)
)

(
    GT(gibraltar_mini)
    .fmt_datetime(
        columns="datetime",
        format_str="%b %d %Y (%a) - %I:%M %p",
    )
    .fmt_number(columns="temp", decimals=1, pattern="{x}°C")
    .fmt_percent(columns="humidity", scale_values=False, decimals=0)
    .cols_label(
        datetime="Time",
        temp="Temperature",
        humidity="Humidity",
        condition="Conditions",
    )
    .tab_header(
        title="Gibraltar Temperature and Humidity Conditions",
        subtitle="Morning, Noon, and Evening Readings"
    )
    .opt_stylize(style=1, color="cyan")
)

Time	Temperature	Humidity	Conditions
Gibraltar Temperature and Humidity Conditions
Morning, Noon, and Evening Readings
May 01 2023 (Mon) - 06:50 AM	17.2°C	1%	Fair
May 01 2023 (Mon) - 12:20 PM	22.2°C	1%	Fair
May 01 2023 (Mon) - 12:50 PM	22.2°C	1%	Fair
May 01 2023 (Mon) - 06:20 PM	20.0°C	1%	Fair
May 01 2023 (Mon) - 06:50 PM	20.0°C	1%	Fair
May 02 2023 (Tue) - 06:50 AM	17.8°C	1%	Mostly Cloudy
May 02 2023 (Tue) - 12:20 PM	18.9°C	1%	Mostly Cloudy
May 02 2023 (Tue) - 12:50 PM	20.0°C	1%	Mostly Cloudy
May 02 2023 (Tue) - 06:20 PM	22.2°C	1%	Fair
May 02 2023 (Tue) - 06:50 PM	22.2°C	1%	Fair

The custom datetime formatting string in format_str="%b %d %Y (%a) - %I:%M %p" creates a readable datetime format that’s perfect for weather reporting, showing the day of week, month, day, year, and the time in 12-hour format.

Acknowledgements and what’s next

We’re grateful to all the contributors who made this release possible. These new features represent significant improvements for creating space-efficient tables while also maximizing visual appeal.

The combination of these features lets you now create complex, professional tables with hierarchical column structures, boolean indicators, space-saving labels, and nicely formatted datetime displays.

We’re always happy to get feedback and hear about how you’re using Great Tables:

Keep building those beautiful tables!

Adding Plots to Great Tables

Jules Walzer-Goldfeld and Michael Chow — 2025-07-03T14:49:24.228128

While working on gt-extras, I’ve been exploring how to add small plots to Great Tables. These can go by many names, like spark lines, nanoplots, and so on. In this post, I’ll look at three approaches I tried: adding plots with plotnine, svg.py, or adding HTML directly. In the first two cases, the plots are SVGs, while the latter entails a collection of composed HTML div elements.

Here are the pieces I’ll cover:

svg.py: creating your own tiny chart directly for a row.
direct HTML: adding HTML divs directly.
plotnine: adding a full, stripped-down chart to a row.

In the end, it’s often simplest to use svg.py, since you can create basic charts with minimal overhead. Building elements with HTML has even less overhead, but it is also slightly less user-friendly. At the other end of the spectrum, as your charts become more complex, using existing packages like the more exhaustive plotnine is a good alternative.

Animal	Legs	Plot
Ostrich	2	2
Spider	8	8
Lion	4	4

Here is the final result:

Code

Great Tables + marimo = Interactive Tables

Rich Iannone and Jerry Wu — Tue, 24 Jun 2025 00:00:00 GMT

Jerry Wu’s recent post demonstrates how Great Tables can be made reactive in a marimo notebook. The post showcases a really nice integration where marimo’s reactive widgets can be embedded directly into Great Tables using the html() helper function. This effectively creates an interactive table that updates in real-time whenever users interact with the controls.

Interactive Table Demo

Here’s a screencast (based on the aforementioned post) showing Jerry’s GT table in marimo. It demonstrates how the embedded marimo widgets create reactive effects, allowing you to directly modify the table in real-time.

Interactive Great Tables with marimo widgets

The marimo reactive widgets can be embedded into a GT table through the html() helper function. In Jerry’s example, the table responds to widget changes in the opt_stylize() method call, where the .value attributes for all of the widgets are passed in as arguments.

gt.opt_stylize(
    style=style_widget.value,
    color=color_widget.value,
    add_row_striping=row_striping_widget.value,
)

marimo Showcases the Integration

The marimo team must have seen that post and liked what they saw! They recently released a video showcasing how marimo widgets work with Great Tables to create reactive tables.

For more details on marimo’s widget system, check out their UI elements documentation and reactivity guide.

marimo + Quarto Integration

For those interested in embedding marimo notebooks directly in Quarto documents, the marimo team has also created a quarto-marimo plugin. This extension allows you to run marimo code blocks natively within Quarto documents, making it easy to create interactive content that combines the best of both tools. It’s a very exciting development since we use Quarto extensively (our docs and this very blog post were authored through Quarto!). And naturally there’s a video for this as well.

Wrapping Up

We’re excited by how the marimo team is committed to creating seamless integrations with popular tools like Great Tables and Quarto. We’re also excited to see what new features and integrations they’ll develop next!

Be sure to check out the marimo YouTube channel as they consistently produce high-quality videos that demonstrate the power of reactive notebooks in action.

Great Tables: Becoming the Polars .style Property

Michael Chow — Wed, 16 Apr 2025 00:00:00 GMT

Roughly a year ago, the DataFrame library Polars made its v1.0.0 release. One neat feature included in the release was a DataFrame.style property—which returns a Great Tables object, so you can add things like titles, column labels, and highlighting for reporting.

When talking about the Polars integration, people are often surprised to hear it happened when Great Tables was only 8 months old. Moreover, the whole process of how open source maintainers chat and discuss teaming up can feel shrouded in mystery.

In this post, I want to take some time to discuss how folks in the Polars and Great Tables communities got to DataFrame.style. There are three big pieces:

How we got there: the magic of the Polars discord.
Making .style work: enabling Great Tables to work as a property.
What’s next?

How we got there

First contact: Polars discord

Roughly a year ago, Rich Iannone and I (Michael Chow) started working together on Great Tables—a Python library for creating display tables. Initially, Great Tables only supported Pandas, but this made a few things difficult. For example, selecting columns and applying conditional styles took a surprising amount of code.

As an experiment, we added support for Polars, and wrote a post called Great Tables: The Polars DataFrame Styler of Your Dreams.

Curious in what folks thought, we dropped it in the Polars discord, and got some Great Feedback:

But Ritchie Vink, the creator of Polars, knew we were harboring a shameful Pandas dependency secret:

It’s true, we had baked Pandas in as a dependency. We were just kids back then when starting Great Tables. We didn’t realize that the world was moving to DataFrame agnostic support 😓.

But the more we used Polars with Great Tables, the happier we were. So we made some architectural tweaks to make Great Tables BYODF (Bring Your Own DataFrame). With these changes, Polars users could install and use Great Tables without pulling in an unnecessary dependency on another DataFrame library (Pandas).

These interactions were critical early on for co-designing Great Tables with Polars in mind. But the real magic for us was when Polars users started opening PRs on Great Tables, to make sure we got things right. Chief among them, Jerry Wu!

Jerry Wu: power contributor

Luckily, members of the Polars community, like Jerry Wu (jrycw), showed up to make sure we wired up to Polars correctly, and to weigh in on how Polars should be used.

For example, Jerry’s first PR was ensuring we handled a Polars deprecation correctly.

I really can’t overstate how much we appreciate his help, and how critical it has been in ensuring we get the details right.

In addition to his PRs, Jerry has done really Great Work sharing about table display. The most interesting example of this to me is that he discovered that Polars, Great Tables, and FastHTML work well together.

Rich and I had no idea that was possible, and the FastHTML folks ended up adapting his example into an entry on their gallery. Jerry is constantly teaching us about what Great Tables can do.

Growing up: making the case for `.style`

With so much joy coming out of the Polars integration, and support from folks in the Polars community, we started to wonder: how could Great Tables make Polars a first-class citizen?

This ultimately boiled down to asking: what would it take for the polars.DataFrame.style property to return a Great Tables object?

After some discussion on discord, the big pieces folks needed were some sense that Great Tables used a reasonable approach to table styling, carried few dependencies, and was engineered such that it could be returned from a DataFrame.style property. Ultimately, the next few months were spent getting Great Tables up to snuff, and the Polars PR merged.

Making `.style` work

The PR to implement .style in Polars went super quick, from advice on discord April to merged by June. A huge force behind the PR was Marco Gorelli, who encouraged us through the process!

In this section I’ll look at how we addressed the 3 big requirements behind making a strong case for .DataFrame.style returning a Great Tables object:

Design Credibility: It’s clear Great Tables is reasonably thought out.
Working with Polars selectors: It integrates well with pieces like Polars selectors.
Technical: Great Tables can be returned from a DataFrame.style property.

Design credibility

Our biggest hurdle was that the Great Tables library was less than a year old. However, this youthful appearance is a bit misleading, because Great Tables builds on decades of table design and tooling. For example, Rich’s version of Great Tables in R, called gt, has been around since 2019 (see his rstudio::conf() talk).

My favorite aspect of gt is that the community ran table contests every year. The contests don’t even require the use of gt or Great Tables, just a zest for the art of table styling. The 2024 Table Contest had around 60 submissions, and is something we often draw on for inspiration.

For more on the long history of table design, see The Design Philosophy of Great Tables, or this Fred Hutch better tables workshop.

Working with Polars selectors

One important task was sorting out how we use Polars selectors, to ensure they didn’t break down the road.

For example, Great Tables allows Polars selectors to set styles on specific columns data. However, one challenge we ran into was figuring out what Polars considers an expression versus a selector. Essentially, selectors choose columns, but expressions represent operations on the data itself.

The code below shows cases where the .exclude() results in expressions or selectors.

import polars as pl
import polars.selectors as cs

# selector: all columns except "a"
cs.exclude("a")

# expression: same columns as above ¯\_(ツ)_/¯
cs.all().exclude("a")

After discussing with Polars folks in this Polars issue, we landed on 4 rules for selectors:

rule	description	example
`cs` functions	top-level `cs` selection functions -> selector	`cs.starts_with("a")`
infix selectors	infix operators over all selectors -> selector	`cs.starts_with("a") - cs.by_name("abc")`
infix expressions	infix operators over any non-selectors -> expression	`cs.starts_with("a") - "abc"`
method expressions	method calls off selectors -> expression	`cs.all().exclude("a")`

Clarifying this was critical in Great Tables, because in some place we only accept selectors, so we needed to be able to articulate to users how to produce them.

Technical wiring work

The last hurdle was tweaking the great_tables.GT class to fit the flow of DataFrame.style. For example, here is what creating a GT() object looked like before and after .style:

Before: GT(my_data, id="my-table")
After: my_data.style.with_id("my-table")

Notice that before, the GT(id=...) argument could set the html id for a table. However, DataFrame.style is a property that can’t take arguments, so we needed methods like with_id() to set these kinds of options.

Here’s a full code example, in case you want to see it in action.

import polars as pl
from great_tables import GT
from great_tables import exibble

# create a GT object ----
GT(exibble, id="my-table")

# create GT object via .style property ----
pl.DataFrame(exibble).style

num	char	fctr	date	time	datetime	currency	row	group
0.1111	apricot	one	2015-01-15	13:35	2018-01-01 02:22	49.95	row_1	grp_a
2.222	banana	two	2015-02-15	14:40	2018-02-02 14:33	17.95	row_2	grp_a
33.33	coconut	three	2015-03-15	15:45	2018-03-03 03:44	1.39	row_3	grp_a
444.4	durian	four	2015-04-15	16:50	2018-04-04 15:55	65100.0	row_4	grp_a
5550.0	None	five	2015-05-15	17:55	2018-05-05 04:00	1325.81	row_5	grp_b
None	fig	six	2015-06-15	None	2018-06-06 16:11	13.255	row_6	grp_b
777000.0	grapefruit	seven	None	19:10	2018-07-07 05:22	None	row_7	grp_b
8880000.0	honeydew	eight	2015-08-15	20:20	None	0.44	row_8	grp_b

The DataFrame.style property is special, in that you don’t pass any parameters to it. The motivation for this in Polars is that it matches the Pandas pandas.DataFrame.style approach, so provides a familiar interface for users coming from that package. It also matches the DataFrame.plot flow of both packages.

As it turns out, allowing every options settable in the GT() constructor to be set somewhere else was not something anticipated in the design of Great Tables. But after some light architectural wrestling, we introduced .tab_stub(), .with_id(), and .with_locale() to capture arguments you might pass to GT().

What’s next?

Currently, we’re really excited about using Great Tables in different ways!

Pointblank: validate your DataFrames and database tables. Pointblank is quick to fire up and produces delightfully styled reports (using Great Tables 😎).
reactable: create interactive tables. We want to use reactable to render a Great Tables object interactively.

We’re also focused on keeping bug fixes and features cooking in Great Tables. If there’s anything in particular you’re looking for, definitely reach out on the Great Tables discussion page.

In conclusion

This post looked at how interacting with the Polars community discord shaped Great Tables development early on, and how community members like Jerry ended up ensuring Great Tables and Polars played well together. We ended up putting a ring on it, and ensuring Great Tables design, dependencies, and architecture worked well enough to justify returning via polars.DataFrame.style. (Though this is still marked unstable in Polars!)

We’re excited to look at different use cases for Great Tables (and table styling in general) over the next year!

How We Used Great Tables to Supercharge Reporting in Pointblank

Rich Iannone — Tue, 11 Feb 2025 00:00:00 GMT

The Great Tables package allows you to make tables, and they’re really great when part of a report, a book, or a web page. The API is meant to be easy to work with so DataFrames could be made into publication-quality tables without a lot of hassle. And having nice-looking tables in the mix elevates the quality of the medium you’re working in.

We were inspired by this and decided to explore what it could mean to introduce a package where reporting is largely in the form of beautiful tables. To this end, we started work on a new Python package that generates tables (c/o Great Tables) as reporting objects. This package is called Pointblank, its focus is that of data validation, and the reporting tables it can produce informs users on the results of a data validation workflow. In this post we’ll go through how Pointblank:

enables you to validate many types of DataFrames and SQL databases
provides easy-to-understand validation result tables and thorough drilldowns
gives you nice previews of data tables across a range of backends

Validating data with Pointblank

Just like Great Tables, Pointblank’s primary input is a table and the goal of that library is to perform checks of the tabular data. Other libraries in this domain include Great Expectations, pandera, Soda, and PyDeequ.

Below is the main validation report table that users are likely to see quite often. Each row is a validation step, with columns reporting details about each step and their results.

Show the code

Style Table Body with mask= in loc.body()

Jerry Wu — Fri, 24 Jan 2025 00:00:00 GMT

In Great Tables 0.16.0, we introduced the mask= parameter in loc.body(), enabling users to apply conditional styling to rows on a per-column basis more efficiently when working with a Polars DataFrame. This post will demonstrate how it works and compare it with the “old-fashioned” approach:

Leveraging the mask= parameter in loc.body(): Use Polars expressions for streamlined styling.
Utilizing the locations= parameter in GT.tab_style(): Pass a list of loc.body() objects.

Let’s dive in.

Preparations

We’ll use the built-in dataset gtcars to create a Polars DataFrame. Next, we’ll select the columns mfr, drivetrain, year, and hp to create a small pivoted table named df_mini. Finally, we’ll pass df_mini to the GT object to create a table named gt, using drivetrain as the rowname_col= and mfr as the groupname_col=, as shown below:

Show the Code

Great Tables v0.15.0: Flags, Icons, and Other Formatting Goodies

Rich Iannone — Thu, 19 Dec 2024 00:00:00 GMT

The development of Great Tables is really moving along these days. We just released version 0.15.0 and it adds quite a few nice things to the package. The features we’ll highlight in this post are:

adding flag icons with the new fmt_flag() method
peppering your table cells with Font Awesome icons via fmt_icon()
support for displaying accounting notation with four number-based formatting methods

Let’s look at each of these in turn!

Using `fmt_flag()` to incorporate country flag icons

When tables contain country-level data, having a more visual representation for a country can help the reader more quickly parse the table contents. The new fmt_flag() method makes this easy to accomplish. You just need to have either two-letter country codes or three-letter country codes in a column.

Here’s an example where country flags, shown as simplified circular icons, can be added to a table with fmt_flag():

from great_tables import GT
from great_tables.data import peeps
import polars as pl

peeps_mini = (
    pl.from_pandas(peeps)
    .filter(pl.col("dob").str.slice(offset=0, length=4) == "1988")
    .with_columns(name=pl.col("name_given") + " " + pl.col("name_family"))
    .fill_null(value="")
    .select(["country", "name", "address", "city", "state_prov", "postcode"])
)

(
    GT(peeps_mini)
    .tab_header(title="Our Contacts (Born in 1988)")
    .fmt_flag(columns="country")
    .opt_vertical_padding(scale=0.5)
    .cols_label(
        country="",
        name="Name",
        address="Address",
        city="City",
        state_prov="State/Prov.",
        postcode="Zip/Postcode",
    )
)

	Name	Address	City	State/Prov.	Zip/Postcode
Our Contacts (Born in 1988)
	Martin Bartůněk	1850 Valley Lane	Austin	TX	78744
	Feride Šijan	Tavcarjeva 58	Sodražica		1317
	Vejsil Crevar	Gosposka ulica 60	Novo mesto		8501
	Matilda Bates	582 Islington Ave	Toronto	ON	M8V 3B6

This slice of the peeps dataset has country codes in their 3-letter form (i.e., "USA", "SVN", and "CAN") within the country column. So long as they are correct, fmt_flag() will perform the conversion to flag icons. Also, there’s a little bit of interactivity here: when hovering over a flag, the country name will appear as a tooltip!

We have the power to display multiple flag icons within a single cell. To make this happen, the country codes need to be combined in a single string where each code is separated by a comma (e.g., "US,DE,GB"). Here’s an example that uses a portion of the films dataset:

from great_tables import GT, google_font
from great_tables.data import films
import polars as pl

films_mini = (
    pl.from_pandas(films)
    .filter(pl.col("director") == "Michael Haneke")
    .with_columns(title=pl.col("title") + " (" + pl.col("year").cast(pl.String) + ")")
    .select(["title", "run_time", "countries_of_origin"])
)

(
    GT(films_mini)
    .fmt_flag(columns="countries_of_origin")
    .tab_header(title="In Competition Films by Michael Haneke")
    .opt_stylize()
    .tab_options(column_labels_hidden=True)
    .opt_table_font(font=google_font("PT Sans"))
)

In Competition Films by Michael Haneke
Funny Games (1997)	1h 48m
Code Unknown (2000)	1h 58m
The Piano Teacher (2001)	2h 11m
Caché (2005)	1h 57m
The White Ribbon (2009)	2h 24m
Amour (2012)	2h 7m
Happy End (2017)	1h 47m

The column countries_of_origin has these combined strings for each of the co-production films, where countries are arranged by decreasing level of contribution (e.g., "FR,AT,RO,DE" in the second row). The fmt_flag() method parses these strings into a sequence of flag icons that are displayed in the order provided. Each of the flags is separated by a space character but you can always change that default separator with the sep= argument.

Using `fmt_icon()` to include Font Awesome icons

The new fmt_icon() method gives you the ability to easily include Font Awesome icons in a table. It uses a similar input/output scheme as with fmt_flag(): provide the short icon name (e.g., "table", "music", "globe", etc.) or a comma-separated list of them, and fmt_icon() will provide the Font Awesome icon in place. Let’s see it in action with an example that uses the metro dataset:

from great_tables import GT
from great_tables.data import metro
import polars as pl

metro_mini = (
    pl.from_pandas(metro).tail(10)
    .with_columns(
        services = (
            pl.when(pl.col("connect_tramway").is_not_null())
            .then(pl.lit("train, train-tram"))
            .otherwise(pl.lit("train"))
        )
    )
    .select(["name", "services", "location"])
)

(
    GT(metro_mini)
    .tab_header("Services Available at Select Stations")
    .fmt_icon(columns="services", sep=" / ")
    .tab_options(column_labels_hidden=True)
    .opt_stylize(color="green")
    .opt_horizontal_padding(scale=3)
    .opt_align_table_header(align="left")
)

Services Available at Select Stations
Porte de Vanves	/	Paris 14th
Saint-Denis—Porte de Paris	/	Saint-Denis
Saint-Denis—Université	/	Saint-Denis
Saint-François-Xavier		Paris 7th
Varenne		Paris 7th
Bibliothèque François Mitterrand	/	Paris 13th
Cour Saint-Émilion		Paris 12th
Olympiades		Paris 13th
Pont Cardinet		Paris 17th
Saint-Ouen		Clichy, Saint-Ouen-sur-Seine

In the code, we added in the icon names "train" and "train-tram" to the services column, and there could either be just the train icon or the pair that includes the tramway service. We wanted a little separation between the icons in the latter case, so sep=" / " was used to place a slash with spacing between any pair of icons. The icons appear here with a black fill color, but that can be changed with the fill_color= argument (and there are several other arguments for controlling style attributes).

For a list of available icons, their names, and what they look like, check out this listing on the Font Awesome website. The icons draw from the Font Awesome ‘free’ set (2000+ icons in total) but are not obtained via the web. Rather, we use the faicons library so that this can be done entirely offline (directly using the SVG icons stored within faicons).

Accounting notation in select numeric formatting methods

For certain types of tables, it may be preferable to use accounting notation for numerical figures. This type of notation renders negative values in parentheses while omitting the minus sign. This is often seen for monetary and percentage figures but it’s also sensible for plain numbers in the right context. We’ve added support for accounting notation in four formatting methods:

fmt_number()
fmt_integer()
fmt_currency()
fmt_percent()

Here’s a comprehensive example table that demonstrates how this type of formatting looks.

Show the code

Contributing to Public Transit Data Analysis and Tooling

Michael Chow — Thu, 19 Dec 2024 00:00:00 GMT

Hello! Michael Chow here. In 2025, I’ll be focusing on contributing to open source data standards and tooling for public transit. If you work on analytics at a public transit agency, please reach out on linkedin or bluesky—I would love to hear about your work, and how I could be useful!

(I will also be at the TRB Annual Meeting 2025 in Washington D.C.)

At this point, you might be wondering three things:

why focus on open source in public transit?
why is this on the Great Tables blog?
what are you hoping to contribute?

Why focus on open source in public transit?

People doing analytics in public transit are active in developing open data standards (like GTFS, GTFS-RT, and TIDES). These open data sources are complex—they cover schedules that change from week to week, buses moving in realtime, and passenger events. As people like me work more and more on open source tools, we start to lose touch with data analysis in realistic, complex settings. Working on open source transit data is an opportunity for me to ensure my open source tooling work helps people solve real, complex problems.

An inspiration for this angle is the book R for Data Science, which uses realistic datasets—like NYC flights data—to teach data analysis using an ecosystem of packages called the Tidyverse. The Tidyverse packages have dozens of example datasets, and I think this focus on working through examples is part of what made their design so great.

A few years ago, I worked with the Cal-ITP project to build out a warehouse for their GTFS schedule and realtime data. This left a profound impression on me: transit data is perfect for educating on data analyses in R and Python, as well as analytics engineering with tools like dbt or sqlmesh. Many analysts in public transit are querying warehouses, which opens up interesting use-cases with tools like dbplyr (in R) and ibis (in Python).

(I’m also inspired by tools like tidytransit, and other communities like pharmaverse.org.)

Here are some relevant talks:

Why is this on the Great Tables blog?

It gives me the opportunity to show off a lot of interesting, transit related tables!

Great Tables data: Paris metro lines

If you’ve seen the Great Tables documentation for GT.fmt_image(), then you’ve basked in this beautiful example from our Paris metro dataset.

Code

Rendering images anywhere in Great Tables

Jerry Wu — Fri, 13 Dec 2024 00:00:00 GMT

Rendering images in Great Tables is straightforward with GT.fmt_image() and vals.fmt_image(). In this post, we’ll explore three key topics:

Four examples demonstrating how to render images within the body using GT.fmt_image().
How to render images anywhere using vals.fmt_image() and html().
How to manually render images anywhere using html().

Rendering Images in the Body

GT.fmt_image() is the go-to tool for rendering images within the body of a table. Below, we’ll present four examples corresponding to the cases outlined in the documentation:

Case 1: Local file paths.
Case 2: Full HTTP/HTTPS URLs.
Case 3: Image names with the path= argument.
Case 4: Image names using both the path= and file_pattern= arguments.

Finding the Right Case for Your Needs

Case 1 and Case 2 work best for data sourced directly from a database.
Case 3 is ideal for users dealing with image names relative to a base directory or URL (e.g., /path/to/images).
Case 4 is tailored for users working with patterned image names (e.g., metro_{}.svg).

Preparations

For this demonstration, we’ll use the first five rows of the built-in metro dataset, specifically the name and lines columns.

To ensure a smooth walkthrough, we’ll manipulate the data (a Python dictionary) directly. However, in real-world applications, such operations are more likely performed at the DataFrame level to leverage the benefits of vectorized operations.

Show the Code

Great Tables: Generating LaTeX Output for PDF

Rich Iannone — Wed, 13 Nov 2024 00:00:00 GMT

We’ve been doing quite a bit of work on getting Great Tables to produce LaTeX table code and v0.14.0 introduces the as_latex() method to make this possible. For those publishing workflows involving LaTeX documents, it’s useful to have a reproducible solution for generating data tables as native LaTeX tables.

In this post, we will go over the following:

generating LaTeX table code: how we handle the different parts of a table
rendering to PDF with Quarto: integrating LaTeX table code into PDFs
current limitations and roadmap: what has been implemented, and what is left

Generating a LaTeX table with Great Tables

We can use the GT.as_latex() method to generate LaTeX table code. This code includes important structural pieces like titles, spanners, and value formatting. For example, here’s a simple table output as LaTeX code:

Show the Code

Great Tables v0.13.0: Applying styles to all table locations

Rich Iannone and Michael Chow — Thu, 10 Oct 2024 00:00:00 GMT

We did something in Great Tables (0.13.0) that’ll make your tables that much more customizable: super fine-grained ways of setting styles throughout the table. Before you were largely constrained to styling through the following strategies:

use a limited set of styles (e.g., background color, font weight, etc.) to different table locations like the stub, the column labels, etc., through tab_options()
use tab_style() with a larger set of styling options for the table body cells (specified by loc.body())

In v0.13.0, we can target much more than just the table body! Here is the expanded set of loc.*() methods along with the locations that they can target.

This augmentation of the loc module to include all locations in the table means that there won’t be a spot in the table to which you can’t add styling. This is terrific because it gives you free rein to fully customize the look of your table.

Let’s make a table and see how this new feature could be used.

Starting things off with a big GT table

The table we’ll make uses the nuclides dataset (available in the great_tables.data module). Through use of the tab_*() methods, quite a few table components (hence locations) will be added. We have hidden the code here because it is quite lengthy but you’re encouraged to check it out to glean some interesting GT tricks.

Show the code

Great Tables v0.12.0: Google Fonts and zebra stripes

Rich Iannone — Mon, 30 Sep 2024 00:00:00 GMT

In Great Tables 0.12.0 we focused on adding options for customizing the appearance of a table. In this post, we’ll present two new features:

using typefaces from Google Fonts via tab_style() and opt_table_font()
adding table striping via tab_options() and opt_row_striping()

Let’s have a look at how these new features can be used!

Using fonts from Google Fonts

Google Fonts is a free service that allows use of hosted typefaces in your own websites. In Great Tables, we added the google_font() helper function to easily incorporate such fonts in your tables. There are two ways to go about this:

use google_font() with opt_table_font() to set a Google Font for the entire table
invoke google_font() within tab_style(styles=style.text(font=...)) to set the font within a location

Let’s start with this small table that uses the default set of fonts for the entire table.

Show the code

Great Tables for Scientific Publishing

Rich Iannone — Mon, 08 Jul 2024 00:00:00 GMT

Great Tables version 0.10.0 has be released today and it contains a host of new features to support tables meant for scientific publishing.

In this post, we’ll review the big pieces that scientific tables need:

Unit notation: rendering units and chemical formulas (e.g., °C or C₆H₆).
Scientific notation: formatting for very large and small numbers (e.g., 3.50 × 10⁻¹¹)
Nanoplots: compact visualizations for revealing trends.

We’ve added six new datasets, to help quickly show off scientific publishing! We’ll use the new reactions and gibraltar datasets to create examples in the fields of Atmospheric Chemistry and Meteorology, respectively.

Tip

Rich presented on this topic at SciPy 2024!

At SciPy 2024 (on July 11, 2024), Rich delivered a talk called Great Tables for Everyone and it presented some of the tables shown in this post. If you weren’t in attendance that’s okay, you can watch the recorded talk and the materials are available in GitHub.

Unit and scientific notation

We added the reactions dataset to serve as the basis for examples in the discipline of Atmospheric Chemistry. The dataset contains reaction rate constants for gas-phase reactions of 1,683 organic compounds. Each of these compounds can potentially undergo reaction with hydroxyl radicals (OH), nitrate radicals (NO₃), or chlorine atoms (Cl). These reaction rate constants are typically very small values in units of cm³ molecules^–1 s^–1. In the upcoming example, we’ll pare down this massive dataset to only 11 rows representing the class of organic compounds known as mercaptans.

To make this table work well in a scientific reporting context, we need three pieces:

way to represent units, like cm³
method for typesetting chemical formulae, as in CH₄
formatting for very small numbers in scientific notation.

Great Tables provides the necessary functionality for all three requirements. Here is a summary table that tabulates rate constants for mercaptan compounds undergoing reaction with OH, O₃, and Cl:

Show the Code

PyCon 2024: Making Beautiful, Publication Quality Tables is Possible in 2024

Michael Chow — Thu, 16 May 2024 00:00:00 GMT

The Great Tables crew is excited to share that we’ll be presenting on tables at PyCon 2024! If you’re around and want to meet, be sure to stop by the Posit Booth, or reach out on linkedin to Rich or Michael!

The talk, Making Beautiful, Publication Quality Tables is Possible in 2024 happened on May 17, 2024. You can watch the recording on YouTube.

In addition to the talk, there are two other events worth mentioning:

The 2024 Table Contest
Our upcoming table workshop at posit::conf 2024

What’s the presentation about?

Publication quality tables are a critical form of data visualization, that is easy to miss in favor of charts and graphs. We’re excited to focus on how…

tables are used in areas like sports and medicine.
Great Tables provides a systematic approach to structuring, styling, and formatting tables.
nanoplots combine the trend-emphasizing of graphs with the compactness of a table.

Throughout the presentation, we’ll focus on making this example from a fictitious coffee device shop (notebook):


Product	Revenue		Profit		Monthly Sales
Product	Amount	Percent	Amount	Percent	Monthly Sales
Grinder	$904K	3%	$568K	4%
Moka pot	$2.05M	7%	$181K	1%
Cold brew	$289K	1%	$242K	2%
Filter	$404K	1%	$70.0K	0%
Drip machine	$2.63M	9%	$1.37M	9%
AeroPress	$2.60M	9%	$1.29M	9%
Pour over	$846K	3%	$365K	2%
French press	$1.11M	4%	$748K	5%
Cezve	$2.51M	9%	$1.97M	13%
Chemex	$3.14M	11%	$818K	6%
Scale	$3.80M	13%	$2.91M	20%
Kettle	$756K	3%	$618K	4%
Espresso Machine	$8.41M	29%	$3.64M	25%
Total	$29.4M	100%	$14.8M	100%

Each row of this table is a product sold over the past year (with a total at the bottom).

Note three important pieces:

Icons help people quickly identify products of interest.
Background color distinguishes between revenue and profit measures.
The nanoplot on the right shows a tiny bargraph for monthly sales over the past year. This makes it easy to spot trends, and can be hovered over to get exact values.

Critically, the code for this table used the DataFrame library Polars, which makes it really easy to select rows and columns for styling.

What’s next?

The 2024 Table Contest

The world’s premier display table contest—the 4th annual Table Contest draws competitors from near and far, to showcase the latest and greatest examples in table presentation.

The contest was a great success! On July 1, 2024 we announced the 2024 winners and honorable mentions. Check ’em out!

posit::conf() workshop

We held a posit::conf() 2024 workshop, and you can find the materials at the Making Tables with gt and Great Tables repo.

If you’re curious about making beautiful, publication quality tables in Python or R, do have a look at the resources at that GitHub repository.

We covered the following table topics:

Create table components and put them together (e.g., header, footer, stub, etc.)
Format cell values (numeric/scientific, date/datetime, etc.)
Rearranging columns and handling column value alignments
Styling the table, either through data values or on a more granular level
Adding icons, plots, images, and incorporating your own HTML
and more!

Extra resources

Check out these resources to learn more about the wild and beautiful life of display tables:

Hope all your tables are great!

A huge thanks to all the people who have contributed to Great Tables over the past year. It’s been a really incredible journey!

Great Tables is now BYODF (Bring Your Own DataFrame)

Michael Chow — Wed, 24 Apr 2024 00:00:00 GMT

A few months ago, we released a blog post about how much we loved the combination of Polars and Great Tables. We found that Polars lazy expression system opened up convenient ways to conditionally format tables for presentation. However, excited as we were, we were harboring a shameful secret: Great Tables enabled Polars as an optional dependency, but had a hard dependency on the alternative DataFrame library Pandas.

We’re happy to share that Great Tables v0.5.0 makes Pandas an optional dependency. Using Pandas DataFrames as inputs is still fully supported. The optional dependency simply allows users of one DataFrame library to not have to install the other.

In this post, I’ll cover three important pieces:

Where we are today on dependencies
The challenge of removing hard dependencies
How we made Pandas optional

This may seem over the top, but many DataFrame implementations exist in the Python world. Enabling folks to BYODF (Bring Your Own DataFrame) is a tricky, rewarding challenge!

The state of Great Tables dependencies

Currently, Great Tables has two “sizes” of libraries it depends on:

Small: utility libraries for things like datetime localization.
Big: a lingering dependency on numpy in a few places (like nanoplots).

For small utilities, we depend on Babel, which makes it easier to say things like, “format this number as if I’m in Germany”.

For big dependencies, numpy should be fairly straightforward to remove (see this issue). We also still rely on Pandas for datasets in great_tables.data, but we will remove it soon (see this issue).

Removing dependencies like numpy and Pandas helps people who are in restricted computing environments, want a more lightweight install, or who are stuck depending on a much earlier version of a package. It also helps us keep a clean separation of concerns. Without clear boundaries, it’s too tempting to reach for things like pd.isna() in a pinch, or smear library specific versions of missingness across our code (e.g. pd.NA, np.nan, polars.NullType).

The challenge of removing hard dependencies

Removing hard dependencies on DataFrame libraries is worthwhile, but requires special handling for all DataFrame specific actions. To illustrate consider the Great Tables output below, which is produced from a Pandas DataFrame:

import pandas as pd
import polars as pl
from great_tables import GT

df_pandas = pd.DataFrame({"x": ["a", "b"], "y": [1.01, 2.0]})
df_polars = pl.from_pandas(df_pandas)

GT(df_pandas)

x	y
a	1.01
b	2.0

Producing this table includes two actions on the DataFrame:

Get column names: these are used for column labels (and other things).
Get column types: these are used for alignment (e.g. numeric column is right aligned).

While these actions may seem simple, they require different methods for different DataFrame implementations. In this post, we’ll focus specifically on the challenge of getting column names.

Getting column names

The code below shows the different methods required to get column names as a list from Pandas and Polars.

df_pandas.columns.tolist()  # pandas
df_polars.columns           # polars

['x', 'y']

Notice that the two lines of code aren’t too different—Pandas just requires an extra .tolist() piece. We could create a special function, that returns a list of names, depending on the type of the input DataFrame.

def get_column_names(data) -> list[str]:

    # pandas specific ----
    if isinstance(data, pd.DataFrame):
        return data.columns.tolist()

    # polars specific ----
    elif isinstance(data, pl.DataFrame):
        return data.columns

    raise TypeError(f"Unsupported type {type(data)}")

The function works great, in that we can call it on either DataFrame, but it lacks two things. The first is dependency inversion, since it requires importing both Pandas and Polars (creating a hard dependency). The second is separation of concerns, since Pandas and Polars code is mixed together. In this case adding more DataFrame implementations would create a hot stew of logic.

How we made Pandas optional

We were able to make Pandas optional in a sane manner through two moves:

databackend: perform isinstance checks without importing anything.
singledispatch: split out functions like get_column_names() into DataFrame specific versions.

Inverting dependency with databackend

Inverting dependency on DataFrame libraries means that we check whether something is a specific type of DataFrame, without using imports. This is done through the package databackend, which we copied into Great Tables.

It works by creating placeholder classes, which stand in for the DataFrames they’re detecting:

from great_tables._databackend import AbstractBackend


class PdDataFrame(AbstractBackend):
    _backends = [("pandas", "DataFrame")]


class PlDataFrame(AbstractBackend):
    _backends = [("polars", "DataFrame")]


if isinstance(df_pandas, PdDataFrame):
    print("I'm a pandas DataFrame!!!")

I'm a pandas DataFrame!!!

Note that the PdDataFrame above is able to detect a Pandas DataFrame without importing Pandas, by taking advantage of a bit of logic called a counterfactual:

assumption: if df_pandas is a Pandas DataFrame, then Pandas has been imported.
counterfactual: if Pandas has not been imported, then df_pandas is not a Pandas DataFrame.

This lets it quickly rule out a potential Pandas object by checking whether Pandas has been imported. Since this can be done by looking inside sys.modules, no imports are required. For more on this approach, see the databackend README.

Separating concerns with singledispatch

While databackend removes dependencies, the use of singledispatch from the built-in functools module separates out the logic for handling Polars DataFrames from the logic for Pandas DataFrames. This makes it easier to think one DataFrame at a time, and also gets us better type hinting.

Here’s a basic example, showing the get_column_names() function re-written using singledispatch:

from functools import singledispatch


# define the generic function ----
#
@singledispatch
def get_column_names(data) -> list[str]:
    raise TypeError(f"Unsupported type {type(data)}")


# register a pandas implementation on it ----
#
@get_column_names.register
def _(data: PdDataFrame):
    return data.columns.tolist()


# register a polars implementation on it ----
#
@get_column_names.register
def _(data: PlDataFrame):
    return data.columns

Note three important pieces:

The initial @singledispatch decorates def get_column_names(...). This creates a special “generic function”, which can define DataFrame specific implementations.
@get_column_names.register implements the Pandas DataFrame.
The use of PdDataFrame is what signifies “run this for Pandas DataFrames”.

With the get_column_names implementations defined, we can call it like a normal function:

get_column_names(df_pandas)  # pandas version
get_column_names(df_polars)  # polars version

['x', 'y']

For more on the benefits of singledispatch in data tooling, see the blog post Single Dispatch for Data Science Tools. For the nitty gritty on our DataFrame processing, see the Great Tables _tbl_data.py submodule.

See you in the Polarsverse

This was a long diversion into the strategy behind supporting both Pandas and Polars, but the results are worth it. Users are able to bring their DataFrame of choice without the collective baggage of every DataFrame option.

For more on the special things you can do with Polars expressions, see these resources:

Guide: basic styling using Polars expressions
Post: Great Tables, the Polars DataFrame Styler of Your Dreams
The narwhals library: a neat library for running Polars expressions on Pandas DataFrames.

Hope you make some stylish, publication ready tables!

The Design Philosophy of Great Tables

Rich Iannone and Michael Chow — Thu, 04 Apr 2024 00:00:00 GMT

We’ve spent a lot of time thinking about tables. Tables—like plots—are crucial as a last step toward presenting information. There is surprising sophistication and nuance in designing effective tables. Over the past 5,000 years, they’ve evolved from simple grids to highly structured displays of data. Although we argue that the mid-1900s served as a high point, the popularization and wider accessibility of computing seemingly brought us back to the simple, ancient times.

Okay, it’s not all that bad but the workers of data are today confronted with an all-too-familiar dilemma: copy your data into a tool like Excel to make the table, or, display an otherwise unpolished table. Through the exploration of the qualities that make tables shine, the backstory of tables as a display of data, and the issues faced today, it’s clear how we can solve the great table dilemma with Great Tables.

Tables made with computers (left to right): (1) a DataFrame printed at the console, (2) an Excel table, and (3) a Great Tables table.

What is a table, really?

Before getting to what makes tables shine we should first define what a table is. This is surprisingly hard! But I believe it can be boiled down to two basic rules:

the data is represented as columns and rows
the data is primarily text

Let’s look at an example of a simple table with actual data to tie this theory to practice.

Name	Address	City	Postcode	DOB	Height	Weight
Dustin B. Roach	1183 Columbia Road	Holly Oak, DE	19809	1970-09-16	5' 9"	202.5
Iwona Adamczyk	ul. Zabłudowska 133	Warszawa	04-788	1976-01-03	5' 5"	123.7
Geneviève Massé	1415 rue Principale	Amos, QC	J9T 1E4	1967-12-08	5' 3"	136.3
João Souza Lima	Rua Cosmorama, 538	São Paulo-SP	04648-080	2001-04-21	6' 2"	231.0
Maddison McCabe	149 Raymond Street	Strathern	Invercargill 9812	1982-03-05	5' 8"	146.1

A table of named individuals along with a select set of characteristics.

This table arranges records containing personal characteristics as columns and rows. Each person is a row, and each characteristic makes up a different column. The characteristics use different types of data, like dates, numbers, and text. This arrangement makes it easy to look up individual values or make comparisons across the different rows or columns.

Note that there are horizontal lines separating the rows. This aesthetic touch, while not strictly required for a table, serves as a visual reinforcement for separating the individual rows.

The order of the columns matters, and that we start with the Name column here is no accident. If that column were the last (i.e., furthest to the right), it would be slightly more confusing for the reader since the subject for the record isn’t immediate. In addition to order, column labels play an important role for indicating what data is in each column. They’re not always necessary but in most cases they remove the guesswork for what type of data is contained within each column.

We’ll go into some detail later about how Great Tables provides affordances for structuring information for better legibility and how the package can be used to adorn the table with other structural elements. For now, our conception of a table can be summarized in this schematic.

A simple table has: (1) cells containing data, (2) an arrangement of columns and rows, and (3) column labels to describe the type data in each column.

Now, let’s go back: way back. In examining where tables came from, we might better understand the great story of tables.

The early history of tables

Tables emerged from square grids. When grids are made like this, you invariably generate containers that may hold some sort of information. The earliest known examples of grids go very far back in human history. Twenty-five thousand year old representations of the grid are found on the walls of the Lascaux and Niaux caves in France¹.

Reproductions of early grids found on cave walls.

In the second century BC, the Greek astronomer Hipparchus used latitude and longitude to locate celestial and terrestrial positions². At around AD 150, Ptolmey published Geographia, which contains 25 geographical maps accompanied by methodologies for their construction using grids³. The Romans employed a grid system called centuriation, which can be described as land measurement (using surveyors’ instruments) to realize the formation of square grids using roads, canals, or agricultural plots⁴.

When agriculture became more widespread (ca. 10,000 years ago), there was the need to document and manage economic transactions to do with farming, livestock, and the division of labor. In the fourth millennium BC, Mesopotamian cities that traded with far way kingdoms needed to keep such records. Clay tablets recovered from the ancient Sumerian city of Uruk show early yet sophisticated tables. Here is a drawing of one of the recovered tablets, which contains an accounting of deliveries of barley and malt from two individuals for the production of beer⁵.

Drawing of clay tablet from Sumerian city of Uruk, circa 3200-3000 BC. Uruk III Tablet (MSVO 3, 51, Louvre Museum, Paris, France). Annotated with the meanings of the columns, rows, and cells.

Note that the recovered tablet is meant to be read from right to left. Inside each box is an ideogram (a symbol that represented a word or idea) and a numerical value representing a quantity.

Its structure is where things get super interesting:

Rows: there are roughly two rows, each corresponding to an individual.
Columns: the first two columns from the right contain counts of malt (rightmost column) and barley (second rightmost column).
Subtotals: the third column from the right sums barley and malt within each individual, and the left-most column displays the grand total.

As a bonus, the table has a footer, since the bottom row contains the name of the official in charge.

Zooming ahead about a thousand years, you start to see more systematically structured tables. Here’s a photo of a cuneiform tablet that was originally from Mesopotamia (from the Temple of Enlil at Nippur, ca. 1850 BC)⁶, containing sources of revenue and monthly disbursements for 50 temple personnel.

Cuneiform tablet, temple of Enlil at Nippur, (CBS 3323, University of Pennsylvania).

You can see right away that there is a more regular grid and, if you probe deeper, there are more similarities than differerences with the tables of today. While difficult to pick them out, the following table elements are present⁷:

column headings (month names) and row titles (names/professions of individuals).
cells with no information (look at the blank or smooth cells along rows)
numerical values in the cells
subtotals for each individual every six months
grand totals
annotations with explanatory notes

Later on, tables were less inscribed on clay and more on wax tablets, papyrus, and paper. The media have changed, writing technologies have changed, and the design and presentation of tables also went through changes.

Midcentury modern tables

Perhaps the best period for tables was around the middle of the 20th century. Technologies for table (and surrounding document) preparation included the offset printer, the typewriter, and varitype⁸ (my favorite). The technologies were sufficiently advanced as to allow the precise typesetting of table elements. While of course constrained by the limited space available on pages, tabular design at this point had many workable solutions for fitting tables into single pages or dispersing the tabular content across multiple pages. The combination of advanced printing technology with advanced knowledge of tabular design resulted in beautiful tables.

There’s no greater embodiment of that pairing of technology and design than the Manual of Tabular Presentation⁹, written and published by the United States Bureau of the Census. It is truly a remarkable work which goes into great detail on how the department imagines the ideal designs of information-rich tables. The work articulates the different parts of a table (and each part is given a descriptive name), sparing no detail when describing those different table parts in rigorous detail. Throughout its hundreds of pages, the authors make strong recommendations on what to do (and what not to do) for many tabulation scenarios. When poring over the tables visually depicted in the book, you can’t help but see that tables can both look really good and contain a density of information. The promise and the result is a balance of form and function.

We at Great Tables borrow liberally from this work because many of its tabular design principles are just as good now as they were back then (and we’ll talk about what we took from that work in the next section). We’ll end this brief section with a visual montage of snippets from the Census Manual, which provides a glimpse of the sound advice on offer.

Little nuggets of wisdom from the Census Manual. This may very well be the ultimate book on tabular design.

The late history of tables

With computing technologies becoming more accessible by the 1970s and 1980s, people were able to generate tables in both electronic and print form. The democratization of computational tables arguably began with VisiCalc in 1979, a massive success that initiated the computing category of spreadsheeting software. There’s an undeniable advantage to having data analyzed and transformed in computing environments, but, this comes at a cost. This is what it looked like:

This is a table in VisiCalc (earliest example of a table in a spreadsheet application). It’s pretty crude compared to the tables in print but the advantage here is that you can calculate values quickly.

The grid cells couldn’t be styled with borders for presentation purposes, the values couldn’t be formatted, and the tables couldn’t even be printed. I mean, try it out and you’ll see that this is quite limited in more than a few ways.

Over time, and this took about 10-15 years, tables-within-spreadsheets got a little easier on the eyes. By the early 1990s, Excel could paint borders on your tables, better typographical support was available, and the formatting of values was fully-featured (though, wonky). Great! Problem solved, right? Not really.

While Excel tables from the last three decades looked much better than 1980s-spreadsheet-borne tables, they could never hold a candle to what was shown in the Census Manual (no matter how much of an Excel expert you became). Further to this, data analysis started to became a thing accomplished outside of Excel. One example of that is Python and its use inside Jupyter notebooks. We now have a bag of problematic scenarios

all Python: analyze data and generate tables all in Python (bad tables)
all Excel: analyze data and make tables in Excel (less flexible analysis)
split-brained: analyze data in Python, copy over to Excel to make tables (not reproducible)

All of these are suboptimal solutions. We propose that it is far better to do everything in Python: the data ingestion, the data analysis, and the data visualization. The visualization step is what’s done for plots and other types of graphics composed from data, it shouldn’t be any different when it comes to generating summary tables.

Approach to tables taken by Great Tables

Great Tables restores the elegance of midcentury tables with the power of a coding interface. With Great Tables anyone can make beautiful tables in Python. Our framework expresses a table as a combination of six independent components. With this framework, you can structure the table, format the values, and style the table. We firmly believe that the methods offered in the package enable people to construct a wide variety of useful tables that work across many disciplines.

You build with Great Tables iteratively, starting off with your table body from code, adding styling, formatting and other components. Here is a schematic that outlines our terminology and depicts how the different table components are related to each other:

A schematic with the complete set of table components that can be utilized in Great Tables.

Note the following six component pieces:

Table Header: a place for a title and subtitle, where you can succinctly describe the table content
Column Labels: the column labels define the content of each column, and spanners are headings over groups of columns
Stub Head: the ‘top-left’ location, where a label could be used in a variety of ways
Row Stub: for row information, including row grouping labels
Table Body: contains cells and so it’s where the data lives
Table Footer: a place for additional information pertaining to the table content

Here’s a table that takes advantage of the different components available in Great Tables. It contains the names and addresses of people.

Show the code

Great Tables v0.4.0: Nanoplots and More

Rich Iannone — Tue, 19 Mar 2024 00:00:00 GMT

The recent v0.4.0 release of Great Tables contains nanoplots as a major new feature. So, in this post I’ll concentrate on showing you all the things you can do with nanoplots. What are nanoplots? Well, with nanoplots you can do this:

Show the code

Great Tables v0.3.0: So Many Style Options!

Rich Iannone — Fri, 16 Feb 2024 00:00:00 GMT

As our work on Great Tables continues, we want you to be able to produce increasingly sophisticated tables. The look of an HTML table really matters and we believe aesthetics can elevate the presentation of tabular data. In the v0.3.0 release, we’ve implemented features that are concerned with modifying the visual aspects of a table. Let’s get down to what’s new in this version.

Modifying the widths of columns

Before v0.3.0, you could not alter the widths of individual columns. This meant that to great extent your content decided the width of individual columns. Even though browsers do an adequate job in sizing the widths of table columns, it doesn’t always result in a pleasing-to-look-at table. What if you want more space? Maybe you want consistently-sized columns? There’s many reasons to want to have a choice in the matter and the new cols_width() method now makes this possible.

Here’s an example where the widths of all columns are set with our preferred length values (in px).

import warnings
from great_tables import GT, exibble

warnings.filterwarnings("ignore")
exibble_mini = exibble[["num", "char", "date", "datetime", "row"]].head(5)

(
    GT(exibble_mini).cols_width(
        cases={
            "num": "30px",
            "char": "100px",
            "date": "150px",
            "datetime": "200px",
            "row": "50px"
        }
    )
)

num	char	date	datetime	row
0.1111	apricot	2015-01-15	2018-01-01 02:22	row_1
2.222	banana	2015-02-15	2018-02-02 14:33	row_2
33.33	coconut	2015-03-15	2018-03-03 03:44	row_3
444.4	durian	2015-04-15	2018-04-04 15:55	row_4
5550.0		2015-05-15	2018-05-05 04:00	row_5

You don’t have to define widths for all columns with cols_width(), and you’re free to use either px or % values when defining widths. See the reference page for more information and relevant examples.

Setting options across the entire table with `tab_options()`

The new tab_options() method gives you the freedom to specify any of dozens of global style and layout options for the table. Want a font that’s used across all cells? Use the table_font_names= option. Do you need to make the text smaller, but only in the stub? Use stub_font_size= for that. The number of options is perhaps overwhelming at first but we think you’ll enjoy having them around nonetheless. It makes styling the table (and developing your own table themes) a relatively simple task.

Here’s an example that creates a table with a few common components and then uses tab_options() to set up a collection of fonts for the table with the (also new) system_fonts() function:

from great_tables import md, system_fonts

gt_tbl = (
    GT(
        exibble[["num", "char", "currency", "row", "group"]],
        rowname_col="row",
        groupname_col="group",
    )
    .tab_header(
        title=md("Data listing from **exibble**"),
        subtitle=md("`exibble` is a **Great Tables** dataset."),
    )
    .fmt_number(columns="num")
    .fmt_currency(columns="currency")
    .tab_source_note(source_note="This is only a subset of the dataset.")
)

gt_tbl.tab_options(table_font_names=system_fonts(name="industrial"))

	num	char	currency
Data listing from exibble
`exibble` is a Great Tables dataset.
grp_a
row_1	0.11	apricot	$49.95
row_2	2.22	banana	$17.95
row_3	33.33	coconut	$1.39
row_4	444.40	durian	$65,100.00
grp_b
row_5	5,550.00		$1,325.81
row_6		fig	$13.26
row_7	777,000.00	grapefruit
row_8	8,880,000.00	honeydew	$0.44
This is only a subset of the dataset.

Note that table_font_names= accepts a list of fonts that operate as fallbacks for users across different systems (i.e., they may not have the font you have). And the system_fonts() helper function in Great Tables makes this easy by providing you with themed, local font stacks that are meant to work across different computing platforms.

Here’s another example where we set the width of the table to span across the entire page (or containing element).

gt_tbl.tab_options(table_width="100%")

	num	char	currency
Data listing from exibble
`exibble` is a Great Tables dataset.
grp_a
row_1	0.11	apricot	$49.95
row_2	2.22	banana	$17.95
row_3	33.33	coconut	$1.39
row_4	444.40	durian	$65,100.00
grp_b
row_5	5,550.00		$1,325.81
row_6		fig	$13.26
row_7	777,000.00	grapefruit
row_8	8,880,000.00	honeydew	$0.44
This is only a subset of the dataset.

One more where the background color of the table is set to "lightcyan":

gt_tbl.tab_options(table_background_color="lightcyan")

	num	char	currency
Data listing from exibble
`exibble` is a Great Tables dataset.
grp_a
row_1	0.11	apricot	$49.95
row_2	2.22	banana	$17.95
row_3	33.33	coconut	$1.39
row_4	444.40	durian	$65,100.00
grp_b
row_5	5,550.00		$1,325.81
row_6		fig	$13.26
row_7	777,000.00	grapefruit
row_8	8,880,000.00	honeydew	$0.44
This is only a subset of the dataset.

There are many more options available in tab_options(), so have a look at its reference page for more information and useful examples.

Using the new `opt_*()` methods to do more complex tasks with table options

While tab_options() is a great method for setting global table options, sometimes you want to set a number of them at once for a combined effect. For that type of operation, we have the opt_*() series of methods. A common thing you might do is align the content in the table header, we can make that an easy thing with opt_align_table_header():

gt_tbl.opt_align_table_header(align="left")

	num	char	currency
Data listing from exibble
`exibble` is a Great Tables dataset.
grp_a
row_1	0.11	apricot	$49.95
row_2	2.22	banana	$17.95
row_3	33.33	coconut	$1.39
row_4	444.40	durian	$65,100.00
grp_b
row_5	5,550.00		$1,325.81
row_6		fig	$13.26
row_7	777,000.00	grapefruit
row_8	8,880,000.00	honeydew	$0.44
This is only a subset of the dataset.

With that, you don’t have to hunt through the myriad options within tab_options() to find the two args you need to get the job done.

The opt_all_caps() method transforms the text within the column labels, the stub, and in all row groups so that we get an all-capitalized (yet somewhat sized down) look that better differentiates the labels from the data. It’s rather easy to use, just do this:

gt_tbl.opt_all_caps()

	num	char	currency
Data listing from exibble
`exibble` is a Great Tables dataset.
grp_a
row_1	0.11	apricot	$49.95
row_2	2.22	banana	$17.95
row_3	33.33	coconut	$1.39
row_4	444.40	durian	$65,100.00
grp_b
row_5	5,550.00		$1,325.81
row_6		fig	$13.26
row_7	777,000.00	grapefruit
row_8	8,880,000.00	honeydew	$0.44
This is only a subset of the dataset.

This sets nine options you’d otherwise set in tab_options() all at once, making life generally easier.

Here’s one last example, this time using opt_vertical_padding(). You’d use that if you’re dissatisfied with the level of top/bottom padding within cells of all locations (e.g., in the table body, in the column labels, etc.). You can either make a table taller or more ‘compressed’ with a single argument: scale=. Here’s an example where the amount of vertical padding is reduced, resulting in a table taking up less vertical space.

gt_tbl.opt_vertical_padding(scale=0.5)

	num	char	currency
Data listing from exibble
`exibble` is a Great Tables dataset.
grp_a
row_1	0.11	apricot	$49.95
row_2	2.22	banana	$17.95
row_3	33.33	coconut	$1.39
row_4	444.40	durian	$65,100.00
grp_b
row_5	5,550.00		$1,325.81
row_6		fig	$13.26
row_7	777,000.00	grapefruit
row_8	8,880,000.00	honeydew	$0.44
This is only a subset of the dataset.

We have the following methods available in the opt_*() family

and we plan to add more opt_*() methods in future releases.

A new formatting method: `fmt_image()`

Wouldn’t it be great to add graphics to your table? The fmt_image() method provides an easy way to add image files on disk into table body cells. The cells need to contain some reference to an image file. The path= and file_pattern= arguments give you some flexibility in defining exactly where the image files live.

Here’s an example using the metro dataset that’s included within Great Tables.

from great_tables.data import metro
from importlib_resources import files

img_paths = files("great_tables") / "data/metro_images"
metro_mini = metro[["name", "lines", "passengers"]].head(5)

(
    GT(metro_mini)
    .fmt_image(columns="lines", path=img_paths, file_pattern="metro_{}.svg")
    .fmt_integer(columns="passengers")
    .cols_label(
        name="Station",
        lines="Metro Lines",
        passengers="Passengers per Year (2021)"
    )
    .tab_options(table_width="700px")
)

Station	Metro Lines	Passengers per Year (2021)
Argentine		2,079,212
Bastille		8,069,243
Bérault		2,106,827
Champs-Élysées—Clemenceau		1,909,005
Charles de Gaulle—Étoile		4,291,663

Notice that path=img_paths specified the folder the images live in, and file_pattern="metro_{}.svg" provided a template for converting each value in the lines column to an SVG file name.

The fmt_image() method supports three kinds of files as inputs, either: (1) complete http/https or local paths to the files; (2) the file names, where a common path can be provided via the path= arg; or (3) a fragment of the file name, as shown in the example above.

The package has some graphics stored in the data/metro_images directory. They are SVGs and they look very nice in the example table!

See the fmt_image() reference page for more information on this new method.

Wrapping up

This v0.3.0 release has some great new methods that add value to most any table-making endeavor. We also fixed a few bugs along the way so that you’ll have a overall smoother experience when building beautiful tables. As ever, we’ll work toward more and more improvements to give you more creative possibilities!

Using Polars to Win at Super Bowl Squares

Michael Chow — Thu, 08 Feb 2024 00:00:00 GMT

The Super Bowl is upon us, and with it the glittering squares of chance. Maybe you’ve seen Super Bowl Squares at your work. Maybe you’ve played it with your pals. Or maybe you have no idea what it is.

Whether you’re a Squares-head or not, this post will help you win with data.

What is Super Bowl Squares?

Super Bowl Squares is a betting game, where you bet on the final digits of each team in a game.

For example, here are some scores with the final digit bolded:

Home team score: 14
Away team score: 7

So the final digits would be:

Home team digit: 4
Away team digit: 7

Let’s say you choose the digits above, and write this as 4/7—meaning a final digit of 4 for home and 7 for away. You would mark yourself on this square:

Code

great_tables

Recreating Septa Transit Timetables in Python

The final result

Great Tables v0.18.0: Easy Column Spanners and More!

Quick spanner creation with tab_spanner_delim()

Beautiful boolean formatting with fmt_tf()

Rotating column labels with cols_label_rotate()

Enhanced datetime formatting with fmt_datetime()

Acknowledgements and what’s next

Adding Plots to Great Tables

Great Tables + marimo = Interactive Tables

Interactive Table Demo

marimo Showcases the Integration

marimo + Quarto Integration

Wrapping Up

Great Tables: Becoming the Polars .style Property

How we got there

First contact: Polars discord

Jerry Wu: power contributor

Growing up: making the case for .style

Making .style work

Design credibility

Working with Polars selectors

Technical wiring work

What’s next?

In conclusion

How We Used Great Tables to Supercharge Reporting in Pointblank

Validating data with Pointblank

Style Table Body with mask= in loc.body()

Preparations

Great Tables v0.15.0: Flags, Icons, and Other Formatting Goodies

Using fmt_flag() to incorporate country flag icons

Using fmt_icon() to include Font Awesome icons

Accounting notation in select numeric formatting methods

Contributing to Public Transit Data Analysis and Tooling

Why focus on open source in public transit?

Why is this on the Great Tables blog?

Great Tables data: Paris metro lines

Rendering images anywhere in Great Tables

Rendering Images in the Body

Preparations

Great Tables: Generating LaTeX Output for PDF

Generating a LaTeX table with Great Tables

Great Tables v0.13.0: Applying styles to all table locations

Starting things off with a big GT table

Great Tables v0.12.0: Google Fonts and zebra stripes

Using fonts from Google Fonts

Great Tables for Scientific Publishing

Unit and scientific notation

PyCon 2024: Making Beautiful, Publication Quality Tables is Possible in 2024

What’s the presentation about?

What’s next?

The 2024 Table Contest

posit::conf() workshop

Extra resources

Hope all your tables are great!

Great Tables is now BYODF (Bring Your Own DataFrame)

The state of Great Tables dependencies

The challenge of removing hard dependencies

Getting column names

How we made Pandas optional

Inverting dependency with databackend

Separating concerns with singledispatch

See you in the Polarsverse

The Design Philosophy of Great Tables

What is a table, really?

The early history of tables

Midcentury modern tables

The late history of tables

Approach to tables taken by Great Tables

Great Tables v0.4.0: Nanoplots and More

Great Tables v0.3.0: So Many Style Options!

Modifying the widths of columns

Setting options across the entire table with tab_options()

Using the new opt_*() methods to do more complex tasks with table options

A new formatting method: fmt_image()

Wrapping up

Using Polars to Win at Super Bowl Squares

What is Super Bowl Squares?

Quick spanner creation with `tab_spanner_delim()`

Beautiful boolean formatting with `fmt_tf()`

Rotating column labels with `cols_label_rotate()`

Enhanced datetime formatting with `fmt_datetime()`

Growing up: making the case for `.style`

Making `.style` work

Using `fmt_flag()` to incorporate country flag icons

Using `fmt_icon()` to include Font Awesome icons

Setting options across the entire table with `tab_options()`

Using the new `opt_*()` methods to do more complex tasks with table options

A new formatting method: `fmt_image()`