great_tables
  • Get Started
  • Examples
  • Reference
  • Blog
  1. Table Structure
  2. Column Labels
  • Intro
  • Overview
  • Table Structure
    • Header and Footer
    • Stub (Row Labels)
    • Column Labels
  • Format
    • Formatting Values
    • Nanoplots
  • Style
    • Styling the Table Body
    • Styling the whole table
    • Colorizing with Data
  • Theming
    • Table Theme Options
    • Premade Themes
  • Selecting table parts
    • Column Selection
    • Row Selection
    • Location selection
  • Extra
    • Contributing Guidelines

On this page

  • Adding Column Spanners
  • Moving and Relabeling Columns
  • Targeting Columns for columns=
  1. Table Structure
  2. Column Labels

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/m2), 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
New York Air Quality Measurements
Daily measurements in New York City (May 1-10, 1973)
Measurement Time
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")
    )
)
New York Air Quality Measurements
Daily measurements in New York City (May 1-10, 1973)
Time Measurement
Year Month Day Ozone,
ppbV
Solar R.,
cal/m2
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 (&deg;).

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.

Stub (Row Labels)
Formatting Values