|
| 1 | +--- |
| 2 | +title: "Great Tables `v0.15.0`: Flags, Icons, and Other Formatting Goodies" |
| 3 | +html-table-processing: none |
| 4 | +author: Rich Iannone |
| 5 | +date: 2024-12-19 |
| 6 | +freeze: true |
| 7 | +jupyter: python3 |
| 8 | +--- |
| 9 | + |
| 10 | +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: |
| 11 | + |
| 12 | +- adding flag icons with the new `fmt_flag()` method |
| 13 | +- peppering your table cells with Font Awesome icons via `fmt_icon()` |
| 14 | +- support for displaying accounting notation with four number-based formatting methods |
| 15 | + |
| 16 | +Let's look at each of these in turn! |
| 17 | + |
| 18 | +### Using `fmt_flag()` to incorporate country flag icons |
| 19 | + |
| 20 | +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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) or [three-letter country codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) in a column. |
| 21 | + |
| 22 | +Here's an example where country flags, shown as simplified circular icons, can be added to a table with `fmt_flag()`: |
| 23 | + |
| 24 | +```{python} |
| 25 | +from great_tables import GT |
| 26 | +from great_tables.data import peeps |
| 27 | +import polars as pl |
| 28 | +
|
| 29 | +peeps_mini = ( |
| 30 | + pl.from_pandas(peeps) |
| 31 | + .filter(pl.col("dob").str.slice(offset=0, length=4) == "1988") |
| 32 | + .with_columns(name=pl.col("name_given") + " " + pl.col("name_family")) |
| 33 | + .fill_null(value="") |
| 34 | + .select(["country", "name", "address", "city", "state_prov", "postcode"]) |
| 35 | +) |
| 36 | +
|
| 37 | +( |
| 38 | + GT(peeps_mini) |
| 39 | + .tab_header(title="Our Contacts (Born in 1988)") |
| 40 | + .fmt_flag(columns="country") |
| 41 | + .opt_vertical_padding(scale=0.5) |
| 42 | + .cols_label( |
| 43 | + country="", |
| 44 | + name="Name", |
| 45 | + address="Address", |
| 46 | + city="City", |
| 47 | + state_prov="State/Prov.", |
| 48 | + postcode="Zip/Postcode", |
| 49 | + ) |
| 50 | +) |
| 51 | +``` |
| 52 | + |
| 53 | +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! |
| 54 | + |
| 55 | +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: |
| 56 | + |
| 57 | +```{python} |
| 58 | +from great_tables import GT, google_font |
| 59 | +from great_tables.data import films |
| 60 | +import polars as pl |
| 61 | +
|
| 62 | +films_mini = ( |
| 63 | + pl.from_pandas(films) |
| 64 | + .filter(pl.col("director") == "Michael Haneke") |
| 65 | + .with_columns(title=pl.col("title") + " (" + pl.col("year").cast(pl.String) + ")") |
| 66 | + .select(["title", "run_time", "countries_of_origin"]) |
| 67 | +) |
| 68 | +
|
| 69 | +( |
| 70 | + GT(films_mini) |
| 71 | + .fmt_flag(columns="countries_of_origin") |
| 72 | + .tab_header(title="In Competition Films by the Michael Haneke") |
| 73 | + .opt_stylize() |
| 74 | + .tab_options(column_labels_hidden=True) |
| 75 | + .opt_table_font(font=google_font("PT Sans")) |
| 76 | +) |
| 77 | +``` |
| 78 | + |
| 79 | +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. |
| 80 | + |
| 81 | +### Using `fmt_icon()` to include Font Awesome icons |
| 82 | + |
| 83 | +The new `fmt_icon()` method gives you the ability to easily include FontAwesome 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: |
| 84 | + |
| 85 | +```{python} |
| 86 | +from great_tables import GT |
| 87 | +from great_tables.data import metro |
| 88 | +import polars as pl |
| 89 | +
|
| 90 | +metro_mini = ( |
| 91 | + pl.from_pandas(metro).tail(10) |
| 92 | + .with_columns( |
| 93 | + services = ( |
| 94 | + pl.when(pl.col("connect_tramway").is_not_null()) |
| 95 | + .then(pl.lit("train, train-tram")) |
| 96 | + .otherwise(pl.lit("train")) |
| 97 | + ) |
| 98 | + ) |
| 99 | + .select(["name", "services", "location"]) |
| 100 | +) |
| 101 | +
|
| 102 | +( |
| 103 | + GT(metro_mini) |
| 104 | + .tab_header("Services Available at Select Stations") |
| 105 | + .fmt_icon(columns="services", sep=" / ") |
| 106 | + .tab_options(column_labels_hidden=True) |
| 107 | + .opt_stylize(color="green") |
| 108 | + .opt_horizontal_padding(scale=3) |
| 109 | + .opt_align_table_header(align="left") |
| 110 | +) |
| 111 | +``` |
| 112 | + |
| 113 | +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). |
| 114 | + |
| 115 | +For a list of available icons, their names, and what they look like, check out [this listing on the FontAwesome website](https://fontawesome.com/search?m=free&o=r). 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](https://pypi.org/project/faicons/) so that this can be done entirely offline (directly using the SVG icons stored within faicons). |
| 116 | + |
| 117 | +### Accounting notation in select numeric formatting methods |
| 118 | + |
| 119 | +For certain types of tables, it may be preferable to use accounting notation for certain 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: |
| 120 | + |
| 121 | +- `fmt_number()` |
| 122 | +- `fmt_integer()` |
| 123 | +- `fmt_currency()` |
| 124 | +- `fmt_percent()` |
| 125 | + |
| 126 | +Here's a comprehensive example table that demonstrates how this type of formatting looks. |
| 127 | + |
| 128 | +```{python} |
| 129 | +# | code-fold: true |
| 130 | +# | code-summary: "Show the code" |
| 131 | +
|
| 132 | +from great_tables import GT |
| 133 | +import polars as pl |
| 134 | +
|
| 135 | +df = pl.DataFrame({ |
| 136 | + "number_type": ["negative", "postive"], |
| 137 | + "number": [-1.2, 23.6], |
| 138 | + "integer": [-2323, 23213], |
| 139 | + "currency": [-24334.23, 7323.253], |
| 140 | + "percent": [-0.0523, 0.363] |
| 141 | + } |
| 142 | +).with_columns( |
| 143 | + number_acc = pl.col("number"), |
| 144 | + integer_acc = pl.col("integer"), |
| 145 | + currency_acc = pl.col("currency"), |
| 146 | + percent_acc = pl.col("percent") |
| 147 | +) |
| 148 | +
|
| 149 | +( |
| 150 | + GT(df, rowname_col="number_type") |
| 151 | + .fmt_number(columns="number") |
| 152 | + .fmt_percent(columns="percent") |
| 153 | + .fmt_integer(columns="integer") |
| 154 | + .fmt_currency(columns="currency") |
| 155 | + .fmt_number(columns="number_acc", accounting=True) |
| 156 | + .fmt_percent(columns="percent_acc", accounting=True) |
| 157 | + .fmt_integer(columns="integer_acc", accounting=True) |
| 158 | + .fmt_currency(columns="currency_acc", accounting=True) |
| 159 | + .tab_spanner(label="default formatting", columns=[1, 2, 3, 4]) |
| 160 | + .tab_spanner(label="with accounting notation", columns=[5, 6, 7, 8]) |
| 161 | + .cols_label( |
| 162 | + number_acc="number", |
| 163 | + integer_acc="integer", |
| 164 | + currency_acc="currency", |
| 165 | + percent_acc="percent" |
| 166 | + ) |
| 167 | +) |
| 168 | +``` |
| 169 | + |
| 170 | +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). |
| 171 | + |
| 172 | +### Acknowledgements and how to contact us |
| 173 | + |
| 174 | +We are *very* grateful for the work that [Jerry Wu](https://github.com/jrycw) has done during this release, some of which includes: |
| 175 | + |
| 176 | +- enhancing the `fmt_image()` to support `http`/`https` schema in the `columns=` parameter, and writing an [incredible blog post](https://posit-dev.github.io/great-tables/blog/rendering-images/) about incorporating images in your tables |
| 177 | +- improving the `save()` method, giving it the ability to perform intermediate saves (since the method returns itself) |
| 178 | +- adding the `pipe()` method, which operates similarly to that of the Pandas and Polars APIs |
| 179 | +- all sorts of little QoL fixes |
| 180 | + |
| 181 | +We extend our gratitude also to [Alessandro Molina](https://github.com/amol-) for adding experimental support for `pyarrow.Table` inputs in this release. |
| 182 | + |
| 183 | +Finally, we thank [Luke Manley](https://github.com/lukemanley) and [Guillaume Lemaitre](https://github.com/glemaitre) for their first contributions to the project! |
| 184 | + |
| 185 | +We're always happy to get feedback. There are three good ways to talk to us: |
| 186 | + |
| 187 | +1. [GitHub Issues](https://github.com/posit-dev/great-tables/issues) |
| 188 | +2. [GitHub Discussions](https://github.com/posit-dev/great-tables/discussions) |
| 189 | +3. [Discord](https://discord.com/invite/Ux7nrcXHVV) |
| 190 | + |
| 191 | +Don't be shy. We love talking tables (and how we can make them better)! |
0 commit comments