great_tables
  • Get Started
  • Examples
  • Reference
  • Blog

On this page

  • Parameters
  • Returns
  • Examples

GT.fmt_flag

GT.fmt_flag(
    self,
    columns=None,
    rows=None,
    height='1em',
    sep=' ',
    use_title=True,
)

Generate flag icons for countries from their country codes.

While it is fairly straightforward to insert images into body cells (using fmt_image() is one way to it), there is often the need to incorporate specialized types of graphics within a table. One such group of graphics involves iconography representing different countries, and the fmt_flag() method helps with inserting a flag icon (or multiple) in body cells. To make this work seamlessly, the input cells need to contain some reference to a country, and this can be in the form of a 2- or 3-letter ISO 3166-1 country code (e.g., Egypt has the "EG" country code). This method will parse the targeted body cells for those codes and insert the appropriate flag graphics.

Multiple flags can be included per cell by separating country codes with commas (e.g., "GB,TT"). The sep= argument allows for a common separator to be applied between flag icons.

Parameters

columns : SelectExpr = None

The columns to target. Can either be a single column name or a series of column names provided in a list.

rows : int | list[int] | None = None

In conjunction with columns=, we can specify which of their rows should undergo formatting. The default is all rows, resulting in all rows in targeted columns being formatted. Alternatively, we can supply a list of row indices.

height : str | int | float | None = '1em'

The height of the flag icons. The default value is "1em". If given as a number, it is assumed to be in pixels.

sep : str = ' '

In the output of multiple flag icons within a body cell, sep= provides the separator between each of the flag icons.

use_title : bool = True

The option to include a title attribute with the country name when hovering over the flag icon. The default is True.

Returns

: GT

The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.

Examples

Let’s use the countrypops dataset to create a new table with flag icons. We will only include a few columns and rows from that table. The country_code_2 column has 2-letter country codes in the format required for fmt_flag() and using that method transforms the codes to circular flag icons.

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

countrypops_mini = (
    pl.from_pandas(countrypops)
    .filter(pl.col("year") == 2021)
    .filter(pl.col("country_name").str.starts_with("S"))
    .sort("country_name")
    .head(10)
    .drop(["year", "country_code_3"])
)

(
    GT(countrypops_mini)
    .fmt_integer(columns="population")
    .fmt_flag(columns="country_code_2")
    .cols_label(
        country_code_2="",
        country_name="Country",
        population="Population (2021)"
    )
    .cols_move_to_start(columns="country_code_2")
)
Country Population (2021)
Samoa Samoa 218,764
San Marino San Marino 33,745
Sao Tome and Principe Sao Tome and Principe 223,107
Saudi Arabia Saudi Arabia 35,950,396
Senegal Senegal 16,876,720
Serbia Serbia 6,834,326
Seychelles Seychelles 99,258
Sierra Leone Sierra Leone 8,420,641
Singapore Singapore 5,453,566
Sint Maarten (Dutch part) Sint Maarten (Dutch part) 42,846

Here’s another example (again using countrypops) where we generate a table providing populations every five years for the Benelux countries ("BEL", "NLD", and "LUX"). After some filtering and a pivot, the fmt_flag() method is used to obtain flag icons from 3-letter country codes present in the country_code_3 column.

import polars.selectors as cs

countrypops_mini = (
    pl.from_pandas(countrypops)
    .filter(pl.col("country_code_3").is_in(["BEL", "NLD", "LUX"]))
    .filter((pl.col("year") % 10 == 0) & (pl.col("year") >= 1960))
    .pivot("year", index = ["country_code_3", "country_name"], values="population")
)

(
    GT(countrypops_mini)
    .tab_header(title="Populations of the Benelux Countries")
    .tab_spanner(label="Year", columns=cs.numeric())
    .fmt_integer(columns=cs.numeric())
    .fmt_flag(columns="country_code_3")
    .cols_label(
        country_code_3="",
        country_name="Country"
    )
)
Populations of the Benelux Countries
Country Year
1960 1970 1980 1990 2000 2010 2020
Belgium Belgium 9,153,489 9,655,549 9,859,242 9,967,379 10,251,250 10,895,586 11,538,604
Luxembourg Luxembourg 313,970 339,171 364,150 381,850 436,300 506,953 630,419
Netherlands Netherlands 11,486,631 13,038,526 14,149,800 14,951,510 15,925,513 16,615,394 17,441,500