---
title: Stub (Row Labels)
jupyter: python3
html-table-processing: none
---

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**).

## Row names

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`:

```{python}
from great_tables import GT, md, html
from great_tables.data import islands

islands_mini = islands.head(10)

GT(islands_mini).tab_stub(rowname_col="name")
```

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 `~~GT.tab_stubhead()` method:

```{python}
(
    GT(islands_mini)
    .tab_stub(rowname_col="name")
    .tab_stubhead(label="landmass")
)
```

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`.

## Row groups

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.

```{python}
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")
)
```

## GT convenience arguments

Rather than using the `~~GT.tab_stub()` method, the `GT(rowname_col=..., groupname_col=...)` arguments
provide a quick way to specify row names and groups.


```{python}
GT(island_groups, rowname_col="name", groupname_col="group")
```
