Introducing Great Tables for Python v0.1.0

A Basic Table

Let’s get right to making a table with the package. We’ll start by making use of the very small, but useful, exibble dataset (which is available in the package). After importing the GT class and that dataset, we’ll feed that Pandas table to GT(). This serves as the main entry point into the Great Tables API.

from great_tables import GT, exibble

# Create a display table showing the table tailor-made for examples: exibble
gt_tbl = GT(exibble)

# Now, show the gt table
gt_tbl

That doesn’t look too bad at all! Sure, it’s basic, but we really didn’t really ask for much. What we got was a proper table with column labels along with all of the cell data. Oftentimes, however, you’ll want a bit more, so we’ll endeavor to include some additional table components and flourishes in the upcoming examples.

Some More Complex Tables

Let’s take things a bit further and make a deluxe table with the included gtcars dataset. Great Tables is all about having a smörgasbord of methods that allow you to refine the presentation until you are fully satisfied. This revamped display table will have a handy Stub component that emphasizes the row labels. Groupings of rows will be generated via categorical values in a column. We’ll add a table title (and subtitle!) with tab_header(). The numerical values will be formatted with fmt_integer() and fmt_currency(). Column labels will be enhanced via cols_label(), and a source note will be included through the use of the tab_source_note() method.

from great_tables.data import gtcars
from great_tables import md, html

gtcars_mini = gtcars[["mfr", "model", "year", "hp", "trq", "msrp"]].tail(10)

(
    GT(gtcars_mini, rowname_col="model", groupname_col="mfr")
    .tab_spanner(label=md("*Performance*"), columns=["hp", "trq"])
    .tab_header(
        title=html("Data listing from <strong>gtcars</strong>"),
        subtitle=html("A <span style='font-size:12px;'>small selection</span> of great cars."),
    )
    .cols_label(year="Year Produced", hp="HP", trq="Torque", msrp="Price (USD)")
    .fmt_integer(columns=["year", "hp", "trq"], use_seps=False)
    .fmt_currency(columns="msrp")
    .tab_source_note(source_note="Source: the gtcars dataset within the Great Tables package.")
)

With the six different methods applied, the table looks really very presentable! The rendering you’re seeing here has been done through a Quarto document. This is basically to say that the Great Tables package is ready to rock inside your Quarto doc.

Let’s keep going and get to deluxe example #2. For this one, we’ll use the airquality dataset (also included in the package, within the data submodule). With this table, two spanner labels will be added with tab_spanner(). It’s an easy-to-use method where you only need to provide the spanner label text and the columns for that label to span across. Columns can be freely moved around with cols_move_to_start() (there are also the cols_move_to_end() and the general cols_move() methods), which makes structuring the table much easier.

from great_tables.data import airquality

airquality_mini = airquality.head(10).assign(Year=1973)

(
    GT(airquality_mini)
    .tab_header(
        title="New York Air Quality Measurements",
        subtitle="Daily measurements in New York City (May 1-10, 1973)",
    )
    .cols_label(
        Ozone=html("Ozone,<br>ppbV"),
        Solar_R=html("Solar R.,<br>cal/m<sup>2</sup>"),
        Wind=html("Wind,<br>mph"),
        Temp=html("Temp,<br>&deg;F"),
    )
    .tab_spanner(label="Date", columns=["Year", "Month", "Day"])
    .tab_spanner(label="Measurement", columns=["Ozone", "Solar.R", "Wind", "Temp"])
    .cols_move_to_start(columns=["Year", "Month", "Day"])
)

That table is looking good! And the great thing about all these methods is that they can be used in virtually any order.

Formatting Table Cells

We didn’t want to skimp on formatting methods for table cells with this early release. There are 11 fmt_*() methods available right now:

• fmt_number(): format numeric values
• fmt_integer(): format values as integers
• fmt_percent(): format values as percentages
• fmt_scientific(): format values to scientific notation
• fmt_currency(): format values as currencies
• fmt_bytes(): format values as bytes
• fmt_roman(): format values as Roman numerals
• fmt_date(): format values as dates
• fmt_time(): format values as times
• fmt_markdown(): format Markdown text
• fmt(): set a column format with a formatting function

The basic idea behind the formatting implementation was to make formatting an easy task but also to provide the user with a lot of power via mixing and matching several options. Most of these methods have a locale argument, which allows for numbers, dates, and times to be easily displayed in locale-specific ways. We did all this to make the formatting task broadly useful to as many users as possible. Let’s take a look at an example of this with a smaller version of the exibble dataset:

exibble_smaller = exibble[["date", "time"]].head(4)

(
    GT(exibble_smaller)
    .fmt_date(columns="date", date_style="wday_month_day_year")
    .fmt_date(columns="date", rows=[2, 3], date_style="day_month_year", locale="de-CH")
    .fmt_time(columns="time", time_style="h_m_s_p")
)

We support hundreds of locales, from af to zu! While there are more formatting methods yet to be added, the ones that are available all work exceedingly well.

The Documentation Site

The documentation site was built using quartodoc. It’s designed to look easy on the eyes while also providing a ton of useful information.

Check out these handy sections of the docs to learn more about how to create your own Great Tables:

• Get Started
• Examples
• API Reference

Since we care a lot about documentation, we’ll continue working toward making this documentation site the best it can be.

We Are on the Path to Table Success

While we’re only getting started on this package, we feel things are coming along nicely! But it’s nothing without you, our users, so we’d really like to hear from you (we welcome any and all feedback). There are quite a few ways to do this; here are all the options:

• you can file an issue or participate in a discussion at GitHub
• the gt package has an X/Twitter account at @gt_package, so check it out for package news and announcements
• there’s a fun Discord server that lets you more casually ask questions and generally just talk about table things

Thanks for reading! For our part, we’ll keep working on making Great Tables live up to its name.