The Stub is a structural component that gives your table a left-hand column of row identifiers. Rather than treating row labels as just another data column, the stub elevates them to a distinct organizational role. This section covers how to create a stub, label it with a stubhead, and organize rows into logical groups.
The Stub component of a table is the area to the left that typically contains row labels and may also contain row group labels. Those subparts can be grouped in a sequence of row groups. The Stub Head provides a location for a label that describes the Stub (and could also be used to describe the column labels). The Stub is optional since there are cases where a Stub wouldn’t be useful (the display tables presented in the previous section looked just fine without a Stub).
An easy way to generate a Stub part is by specifying a stub column in the GT() class with the rowname_col= argument. This will signal to Great Tables that the named column should be used as the stub, using the contents of that column to make row labels. Let’s add a stub with our islands dataset by using rowname_col= in the call to GT:
from great_tables import GT
from great_tables.data import islands
islands_mini = islands.head(10)
GT(islands_mini).tab_stub(rowname_col="name")| size | |
|---|---|
| Africa | 11506 |
| Antarctica | 5500 |
| Asia | 16988 |
| Australia | 2968 |
| Axel Heiberg | 16 |
| Baffin | 184 |
| Banks | 23 |
| Borneo | 280 |
| Britain | 84 |
| Celebes | 73 |
Notice that the landmass names are now placed to the left? That’s the Stub. Notably, there is a prominent border to the right of it but there’s no label above the Stub. We can change this and apply what’s known as a stubhead label through use of the tab_stubhead() method:
| landmass | size |
|---|---|
| Africa | 11506 |
| Antarctica | 5500 |
| Asia | 16988 |
| Australia | 2968 |
| Axel Heiberg | 16 |
| Baffin | 184 |
| Banks | 23 |
| Borneo | 280 |
| Britain | 84 |
| Celebes | 73 |
A very important thing to note here is that the table now has one column. Before, when there was no Stub, two columns were present (with the Column Labels of "name" and "size") but now column number 1 (the only column remaining) is size.
Let’s incorporate row groups into the display table. This divides rows into groups, creating row groups, and results in a display of a row group labels right above the each group. This can be easily done with a table containing row labels and the key is to use the groupname_col= argument of the GT class. Here we will create three row groups (with row group labels "continent", "country", and "subregion") to have a grouping of rows.
island_groups = islands.head(10).assign(group = ["subregion"] * 2 + ["country"] * 2 + ["continent"] * 6)
(
GT(island_groups)
.tab_stub(rowname_col="name", groupname_col="group")
.tab_stubhead(label="landmass")
)| landmass | size |
|---|---|
| subregion | |
| Africa | 11506 |
| Antarctica | 5500 |
| country | |
| Asia | 16988 |
| Australia | 2968 |
| continent | |
| Axel Heiberg | 16 |
| Baffin | 184 |
| Banks | 23 |
| Borneo | 280 |
| Britain | 84 |
| Celebes | 73 |
The table now groups its rows by continent, country, and subregion, with labels appearing above each group. Row groups make it much easier for readers to scan and compare related entries.
Rather than using the tab_stub() method, the GT(rowname_col=..., groupname_col=...) arguments provide a quick way to specify row names and groups.
| size | |
|---|---|
| subregion | |
| Africa | 11506 |
| Antarctica | 5500 |
| country | |
| Asia | 16988 |
| Australia | 2968 |
| continent | |
| Axel Heiberg | 16 |
| Baffin | 184 |
| Banks | 23 |
| Borneo | 280 |
| Britain | 84 |
| Celebes | 73 |
The stub provides a clear organizational framework for your data by separating identifiers from values. Whether you simply need named rows or a fully grouped hierarchy, the combination of rowname_col=, groupname_col=, and tab_stubhead() gives you precise control over how readers navigate your table.