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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

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",
    )
)

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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

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"))
)

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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

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")
)

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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

from great_tables import GT
import polars as pl

df = pl.DataFrame({
    "number_type": ["negative", "positive"],
    "number": [-1.2, 23.6],
    "integer": [-2323, 23213],
    "currency": [-24334.23, 7323.253],
    "percent": [-0.0523, 0.363]
    }
).with_columns(
    number_acc = pl.col("number"),
    integer_acc = pl.col("integer"),
    currency_acc = pl.col("currency"),
    percent_acc = pl.col("percent")
)

(
    GT(df, rowname_col="number_type")
    .fmt_number(columns="number")
    .fmt_percent(columns="percent")
    .fmt_integer(columns="integer")
    .fmt_currency(columns="currency")
    .fmt_number(columns="number_acc", accounting=True)
    .fmt_percent(columns="percent_acc", accounting=True)
    .fmt_integer(columns="integer_acc", accounting=True)
    .fmt_currency(columns="currency_acc", accounting=True)
    .tab_spanner(label="default formatting", columns=[1, 2, 3, 4])
    .tab_spanner(label="with accounting notation", columns=[5, 6, 7, 8])
    .cols_label(
        number_acc="number",
        integer_acc="integer",
        currency_acc="currency",
        percent_acc="percent"
    )
)

For the formatting in the final four columns, we use accounting=True to get the values into accounting notation. This is only apparent for the negative values (first row) as the positive values won’t change their appearance, looking the same as they do when accounting=False (the default).

Acknowledgements and how to contact us#

We are very grateful for the work that Jerry Wu has done during this release, some of which includes:

• enhancing the fmt_image() to support http/https schema in the columns= parameter, and writing an incredible blog post about incorporating images in your tables
• improving the save() method, giving it the ability to perform intermediate saves (since the method returns itself)
• adding the pipe() method, which operates similarly to that of the Pandas and Polars APIs
• all sorts of little QoL fixes

We extend our gratitude also to Alessandro Molina for adding experimental support for pyarrow.Table inputs in this release.

Finally, we thank Luke Manley and Guillaume Lemaitre for their first contributions to the project!

We’re always happy to get feedback. There are three good ways to talk to us:

1. GitHub Issues
2. GitHub Discussions
3. Discord

Don’t be shy. We love talking tables (and how we can make them better)!