GT.cols_label()

Relabel one or more columns.

Usage

Source

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

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