GT.cols_label

GT.cols_label(self, cases=None, **kwargs)

Relabel one or more columns.

There are three important pieces to labelling:

• Each argument has the form: {name in data} = {new label}.
• Multiple columns may be given the same label.
• Labels may use curly braces to apply special formatting, called unit notation. For example, “area ({{ft^2}})” would appear as “area (ft²)”.

See define_units() for details on unit notation.

Parameters

cases : dict[str, str | BaseText] | None = None

A dictionary where the keys are column names and the values are the labels. Labels may use md() or html() helpers for formatting.

****kwargs** : str | BaseText = {}

Keyword arguments to specify column labels. Each keyword corresponds to a column name, with its value indicating the new label.

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.

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