GT.cols_label_with

GT.cols_label_with(self, columns=None, fn=None)

Relabel one or more columns using a function.

The cols_label_with() function allows for modification of column labels through a supplied function. By default, the function will be invoked on all column labels but this can be limited to a subset via the columns parameter.

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.

fn : Callable[[str], str] | None = None

A function that accepts a column name as input and returns a label as output.

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

Let’s use a subset of the sp500 dataset to create a gt table.

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

gt = GT(sp500.head())
gt
date open high low close volume adj_close
2015-12-31 2060.5901 2062.54 2043.62 2043.9399 2655330000.0 2043.9399
2015-12-30 2077.3401 2077.3401 2061.97 2063.3601 2367430000.0 2063.3601
2015-12-29 2060.54 2081.5601 2060.54 2078.3601 2542000000.0 2078.3601
2015-12-28 2057.77 2057.77 2044.2 2056.5 2492510000.0 2056.5
2015-12-24 2063.52 2067.3601 2058.73 2060.99 1411860000.0 2060.99

We can pass str.upper to the fn parameter to convert all column labels to uppercase.

gt.cols_label_with(fn=str.upper)
DATE OPEN HIGH LOW CLOSE VOLUME ADJ_CLOSE
2015-12-31 2060.5901 2062.54 2043.62 2043.9399 2655330000.0 2043.9399
2015-12-30 2077.3401 2077.3401 2061.97 2063.3601 2367430000.0 2063.3601
2015-12-29 2060.54 2081.5601 2060.54 2078.3601 2542000000.0 2078.3601
2015-12-28 2057.77 2057.77 2044.2 2056.5 2492510000.0 2056.5
2015-12-24 2063.52 2067.3601 2058.73 2060.99 1411860000.0 2060.99

One useful use case is using md(), provided by Great Tables, to format column labels. For example, the following code demonstrates how to make the date and adj_close column labels bold using markdown syntax.

gt.cols_label_with(["date", "adj_close"], lambda x: md(f"**{x}**"))
date open high low close volume adj_close
2015-12-31 2060.5901 2062.54 2043.62 2043.9399 2655330000.0 2043.9399
2015-12-30 2077.3401 2077.3401 2061.97 2063.3601 2367430000.0 2063.3601
2015-12-29 2060.54 2081.5601 2060.54 2078.3601 2542000000.0 2078.3601
2015-12-28 2057.77 2057.77 2044.2 2056.5 2492510000.0 2056.5
2015-12-24 2063.52 2067.3601 2058.73 2060.99 1411860000.0 2060.99