# Column Labels
Column labels are the primary way readers identify what data each column contains. Beyond simple labels, **Great Tables** lets you group related columns together under spanner labels, reorder columns for clarity, and customize label text with rich formatting. This page walks through each of these capabilities.
# Working with Column Data
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](../reference/GT.md#great_tables.GT) class.
``` python
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 |
This ten-row subset of the New York air quality dataset has both measurement and time columns, making it a good candidate for organizing with column spanners.
# 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()](../reference/GT.tab_spanner.md#great_tables.GT.tab_spanner) method.
``` python
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()](../reference/GT.cols_move_to_start.md#great_tables.GT.cols_move_to_start))
- customize the column labels so that they are more descriptive (using [cols_label()](../reference/GT.cols_label.md#great_tables.GT.cols_label))
Let's do both of these things in the next example:
``` python
(
gt_airquality
.cols_move_to_start(columns=["Year", "Month", "Day"])
.cols_label(
Ozone=html("Ozone,
ppbV"),
Solar_R=html("Solar R.,
cal/m2"),
Wind=html("Wind,
mph"),
Temp=html("Temp,
°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()](../reference/GT.cols_move_to_start.md#great_tables.GT.cols_move_to_start), the *spanner column labels* still spanned above the correct *column labels*. There are a number of methods on [GT](../reference/GT.md#great_tables.GT) to move columns, including [cols_move()](../reference/GT.cols_move.md#great_tables.GT.cols_move), [cols_move_to_end()](../reference/GT.cols_move_to_end.md#great_tables.GT.cols_move_to_end); there's even a method to hide columns: [cols_hide()](../reference/GT.cols_hide.md#great_tables.GT.cols_hide).
Multiple columns can be renamed in a single use of [cols_label()](../reference/GT.cols_label.md#great_tables.GT.cols_label). Further to this, the helper functions [md()](../reference/md.md#great_tables.md) and [html()](../reference/html.md#great_tables.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 `
`, insert a superscripted `2` (with `2`), 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:
``` python
(
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](column-selection.md).
Between spanners, relabeling, and reordering, you have full control over how your column labels communicate the structure of your data. These tools let you transform raw DataFrame column names into polished, informative headers that guide readers through the table.