GT.cols_label

GT.cols_label(self, **kwargs)

Relabel one or more columns.

There are three important pieces to labelling:

See define_units() for details on unit notation.

Parameters

Name Type Description Default
**kwargs str | Text New labels expressed as keyword arguments. Column names should be the keyword (left-hand side). Labels may use md() or html() helpers for formatting. {}

Returns

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

Notes

GT always selects columns using their name in the underlying data. This means that a column’s label is purely for final presentation.

Examples

The example below relabels columns from the countrypops data to start with uppercase.

from great_tables import GT
from great_tables.data import countrypops

countrypops_mini = countrypops.loc[countrypops["country_name"] == "Uganda"][
    ["country_name", "year", "population"]
].tail(5)

(
    GT(countrypops_mini)
    .cols_label(
        country_name="Country Name",
        year="Year",
        population="Population"
    )
)
Country Name Year Population
Uganda 2018 41515395
Uganda 2019 42949080
Uganda 2020 44404611
Uganda 2021 45853778
Uganda 2022 47249585

Note that we supplied the name of the column as the key, and the new label as the value.

We can also use Markdown formatting for the column labels. In this example, we’ll use md("*Population*") to make the label italicized.

from great_tables import GT, md
from great_tables.data import countrypops

(
    GT(countrypops_mini)
    .cols_label(
        country_name="Name",
        year="Year",
        population=md("*Population*")
    )
)
Name Year Population
Uganda 2018 41515395
Uganda 2019 42949080
Uganda 2020 44404611
Uganda 2021 45853778
Uganda 2022 47249585

We can also use unit notation to format the column labels. In this example, we’ll use {cm^3 molecules^-1 s^-1} for part of the label for the OH_k298 column.

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

reactions_mini = (
    pl.from_pandas(reactions)
    .filter(pl.col("cmpd_type") == "mercaptan")
    .select(["cmpd_name", "OH_k298"])
)

(
    GT(reactions_mini)
    .fmt_scientific("OH_k298")
    .sub_missing()
    .cols_label(
        cmpd_name="Compound Name",
        OH_k298="OH, {{cm^3 molecules^-1 s^-1}}",
    )
)
Compound Name OH, cm3 molecules−1 s−1
methanethiol 3.50 × 10−11
ethanethiol 4.50 × 10−11
propanethiol 5.30 × 10−11
2-propanethiol 3.90 × 10−11
1-butanethiol 5.60 × 10−11
2-methyl-1-propanethiol 4.60 × 10−11
2-butanethiol 3.80 × 10−11
t-butylsulfide 2.90 × 10−11
2-methylbutanethiol 5.20 × 10−11
n-pentanethiol —
1,2-ethanedithiol 3.80 × 10−11