great-tables

When selecting rows for the table body, you can use one of the following three approaches:

• A list of integers representing row indices.
• A Polars expression.
• A callable (function) that accepts a DataFrame and returns a boolean Series.

When defining a pattern for ColMergeInfo, you can use <<...>> to create conditional sections. If any column referenced within the <<...>> block is None (missing), the entire contents of that block will be omitted from the resulting string.

This is useful for avoiding trailing separators or empty parentheses when data is missing.

>>> info = ColMergeInfo(vars=["a", "b"], rows=[0], type="merge", pattern="{0}<< ({1})>>")
>>> info.merge("John", None)
'John'

The GT.save() method is deprecated and will be removed in mid-2027. It relies on Selenium and Pillow, which are heavier dependencies.

Action: Use GT.gtsave() instead, which uses the lightweight nokap package and does not require Selenium or Pillow.

Enhance table data using formatting methods:

• .fmt_number(): Formats numeric columns. Use scale_by to adjust values (e.g., converting large numbers to millions) and decimals to set precision.
• .fmt_image(): Renders images in a column. Specify the column name and the path where the image files are located.

(
    GT(res, rowname_col="Rank")
    .fmt_number(["Total Earnings", "Off-the-Field Earnings"], scale_by = 1/1_000_000, decimals=1)
    .fmt_image("icon", path="./")
)

To retain and render HTML elements within a table header, pass the desired HTML string to the html() helper function inside the tab_header() method.

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

gtcars_mini = gtcars[['mfr', 'model', 'msrp']].head(5)

( 
    GT(gtcars_mini)
    .tab_header(
        title=md("Data listing <strong>gtcars</strong>"),
        subtitle=html("From <span style='color:red;'>gtcars</span>")
    )
)

Customize how data appears in your table using .fmt_number() to scale values (e.g., converting large numbers to millions) and .cols_label() to rename columns for display.

(
    GT(res, rowname_col="Rank")
    .cols_label(**{
        "Total Earnings": "Total $M",
        "Off-the-Field Earnings": "Off field $M",
        "Off-the-Field Earnings Perc": "Off field %"
    })
    .fmt_number(["Total Earnings", "Off-the-Field Earnings"], scale_by = 1/1_000_000, decimals=1)
)

Use the GT class to build a table. You can add a title using .tab_header(), group columns using .tab_spanner(), and add a footer/source note using .tab_source_note(). For the source note, use the md() function to allow Markdown and HTML styling.

(
    GT(res, rowname_col="Rank")
    .tab_header("Highest Paid Athletes in 2023")
    .tab_spanner("Earnings", cs.contains("Earnings"))
    .tab_source_note(
        md(
            '<br><div style="text-align: center;">'
            "Original table: [@LisaHornung_](https://twitter.com/LisaHornung_/status/1752981867769266231)"
            " | Sports icons: [Firza Alamsyah](https://thenounproject.com/browse/collection-icon/sports-96427)"
            " | Data: Forbes"
            "</div>"
            "<br>"
        )
    )
)

Use GT() to initialize a table and chain methods to add structural elements:

• .tab_header(): Adds a title and subtitle to the table.
• .tab_spanner(): Groups columns under a common header using a selector.
• .cols_label(): Renames columns for display using a dictionary mapping current names to new labels.

(
    GT(res, rowname_col="Rank")
    .tab_header("Highest Paid Athletes in 2023")
    .tab_spanner("Earnings", cs.contains("Earnings"))
    .cols_label(**{
        "Total Earnings": "Total $M",
        "Off-the-Field Earnings": "Off field $M",
        "Off-the-Field Earnings Perc": "Off field %"
    })
)