Column Labels

The table’s Column Labels part contains, at a minimum, columns and their column labels. The last example had a single column: size. Just as in the Stub, we can create groupings called spanner labels that encompass one or more columns.

To better demonstrate how Column Labels work and are displayed, let’s use an input data table with more columns. In this case, that input table will be airquality. It has the following columns:

Ozone: mean ground-level ozone in parts per billion by volume (ppbV), measured between 13:00 and 15:00
Solar_R: solar radiation in Langley units (cal/m²), measured between 08:00 and noon
Wind: mean wind speed in miles per hour (mph)
Temp: maximum daily air temperature in degrees Fahrenheit (°F)
Month, Day: the numeric month and day of month for the record

We know that all measurements took place in 1973, so a year column will be added to the dataset before it is passed to the GT() class.

from great_tables import GT, html
from great_tables.data import airquality

airquality_mini = airquality.head(10).assign(Year = 1973)

airquality_mini

	Ozone	Solar_R	Wind	Temp	Month	Day	Year
0	41.0	190.0	7.4	67	5	1	1973
1	36.0	118.0	8.0	72	5	2	1973
2	12.0	149.0	12.6	74	5	3	1973
3	18.0	313.0	11.5	62	5	4	1973
4	NaN	NaN	14.3	56	5	5	1973
5	28.0	NaN	14.9	66	5	6	1973
6	23.0	299.0	8.6	65	5	7	1973
7	19.0	99.0	13.8	59	5	8	1973
8	8.0	19.0	20.1	61	5	9	1973
9	NaN	194.0	8.6	69	5	10	1973

Adding Column Spanners

Let’s organize the time information under a Time spanner label, and put the other columns under a Measurement spanner label. We can do this with the tab_spanner() method.

gt_airquality = (
    GT(airquality_mini)
    .tab_header(
        title="New York Air Quality Measurements",
        subtitle="Daily measurements in New York City (May 1-10, 1973)"
    )
    .tab_spanner(
        label="Time",
        columns=["Year", "Month", "Day"]
    )
    .tab_spanner(
        label="Measurement",
        columns=["Ozone", "Solar_R", "Wind", "Temp"]
    )
)

gt_airquality

Measurement				Time
New York Air Quality Measurements
Daily measurements in New York City (May 1-10, 1973)
Ozone	Solar_R	Wind	Temp	Year	Month	Day
41.0	190.0	7.4	67	1973	5	1
36.0	118.0	8.0	72	1973	5	2
12.0	149.0	12.6	74	1973	5	3
18.0	313.0	11.5	62	1973	5	4
		14.3	56	1973	5	5
28.0		14.9	66	1973	5	6
23.0	299.0	8.6	65	1973	5	7
19.0	99.0	13.8	59	1973	5	8
8.0	19.0	20.1	61	1973	5	9
	194.0	8.6	69	1973	5	10

Moving and Relabeling Columns

We can do two more things to make this presentable:

move the Time columns to the beginning of the series (using cols_move_to_start())
customize the column labels so that they are more descriptive (using cols_label())

Let’s do both of these things in the next example:

(
    gt_airquality
    .cols_move_to_start(columns=["Year", "Month", "Day"])
    .cols_label(
        Ozone=html("Ozone,<br>ppbV"),
        Solar_R=html("Solar R.,<br>cal/m<sup>2</sup>"),
        Wind=html("Wind,<br>mph"),
        Temp=html("Temp,<br>&deg;F")
    )
)

Time			Measurement
New York Air Quality Measurements
Daily measurements in New York City (May 1-10, 1973)
Year	Month	Day	Ozone, ppbV	Solar R., cal/m²	Wind, mph	Temp, °F
1973	5	1	41.0	190.0	7.4	67
1973	5	2	36.0	118.0	8.0	72
1973	5	3	12.0	149.0	12.6	74
1973	5	4	18.0	313.0	11.5	62
1973	5	5			14.3	56
1973	5	6	28.0		14.9	66
1973	5	7	23.0	299.0	8.6	65
1973	5	8	19.0	99.0	13.8	59
1973	5	9	8.0	19.0	20.1	61
1973	5	10		194.0	8.6	69

Note that even though columns were moved using cols_move_to_start(), the spanner column labels still spanned above the correct column labels. There are a number of methods on GT to move columns, including cols_move(), cols_move_to_end(); there’s even a method to hide columns: cols_hide().

Multiple columns can be renamed in a single use of cols_label(). Further to this, the helper functions md() and html() can be used to create column labels with additional styling. In the above example, we provided column labels as HTML so that we can insert linebreaks with <br>, insert a superscripted 2 (with <sup>2</sup>), and insert a degree symbol as an HTML entity (°).

Targeting Columns for `columns=`

In the above examples, we selected columns to span or move using a list of column names (as strings). However, Great Tables supports a wide range of ways to select columns.

For example, you can use a lambda function:

(
    GT(airquality_mini)
    .cols_move_to_start(columns=lambda colname: colname.endswith("R"))
)

Solar_R	Ozone	Wind	Temp	Month	Day	Year
190.0	41.0	7.4	67	5	1	1973
118.0	36.0	8.0	72	5	2	1973
149.0	12.0	12.6	74	5	3	1973
313.0	18.0	11.5	62	5	4	1973
		14.3	56	5	5	1973
	28.0	14.9	66	5	6	1973
299.0	23.0	8.6	65	5	7	1973
99.0	19.0	13.8	59	5	8	1973
19.0	8.0	20.1	61	5	9	1973
194.0		8.6	69	5	10	1973

Inputs like strings, integers, and polars selectors are also supported. For more information, see Column Selection.

Adding Column Spanners

Moving and Relabeling Columns

Targeting Columns for columns=

Targeting Columns for `columns=`