## GT.cols_label()
Relabel one or more columns.
Usage
``` python
GT.cols_label(
cases=None,
**kwargs,
)
```
There are three important pieces to labelling:
- Each argument has the form: {name in data} = {new label}.
- Multiple columns may be given the same label.
- Labels may use curly braces to apply special formatting, called unit notation. For example, "area ({{ft^2}})" would appear as "area (ft²)".
See define_units() for details on unit notation.
## Parameters
`cases: dict[str, str | BaseText] | None = None`
A dictionary where the keys are column names and the values are the labels. Labels may use md() or html() helpers for formatting.
`**kwargs: str | BaseText`
Keyword arguments to specify column labels. Each keyword corresponds to a column name, with its value indicating the new label.
## Returns
`GT`
The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining.
## Notes
GT always selects columns using their name in the underlying data. This means that a column's label is purely for final presentation.
## Examples
The example below relabels columns from the [countrypops](data.countrypops.md#great_tables.data.countrypops) data to start with uppercase.
``` python
from great_tables import GT
from great_tables.data import countrypops
countrypops_mini = countrypops.loc[countrypops["country_name"] == "Uganda"][
["country_name", "year", "population"]
].tail(5)
(
GT(countrypops_mini)
.cols_label(
country_name="Country Name",
year="Year",
population="Population"
)
)
```
| Country Name | Year | Population |
|--------------|------|------------|
| Uganda | 2018 | 41515395 |
| Uganda | 2019 | 42949080 |
| Uganda | 2020 | 44404611 |
| Uganda | 2021 | 45853778 |
| Uganda | 2022 | 47249585 |
Note that we supplied the name of the column as the key, and the new label as the value.
We can also use Markdown formatting for the column labels. In this example, we'll use `md("*Population*")` to make the label italicized.
``` python
from great_tables import GT, md
from great_tables.data import countrypops
(
GT(countrypops_mini)
.cols_label(
country_name="Name",
year="Year",
population=md("*Population*")
)
)
```
| Name | Year | *Population* |
|--------|------|--------------|
| Uganda | 2018 | 41515395 |
| Uganda | 2019 | 42949080 |
| Uganda | 2020 | 44404611 |
| Uganda | 2021 | 45853778 |
| Uganda | 2022 | 47249585 |
We can also use unit notation to format the column labels. In this example, we'll use `{cm^3 molecules^-1 s^-1}` for part of the label for the `OH_k298` column.
``` python
from great_tables import GT
from great_tables.data import reactions
import polars as pl
reactions_mini = (
pl.from_pandas(reactions)
.filter(pl.col("cmpd_type") == "mercaptan")
.select(["cmpd_name", "OH_k298"])
)
(
GT(reactions_mini)
.fmt_scientific("OH_k298")
.sub_missing()
.cols_label(
cmpd_name="Compound Name",
OH_k298="OH, {{cm^3 molecules^-1 s^-1}}",
)
)
```
| Compound Name | OH, cm3 molecules−1 s−1 |
|----|----|
| methanethiol | 3.50 × 10−11 |
| ethanethiol | 4.50 × 10−11 |
| propanethiol | 5.30 × 10−11 |
| 2-propanethiol | 3.90 × 10−11 |
| 1-butanethiol | 5.60 × 10−11 |
| 2-methyl-1-propanethiol | 4.60 × 10−11 |
| 2-butanethiol | 3.80 × 10−11 |
| t-butylsulfide | 2.90 × 10−11 |
| 2-methylbutanethiol | 5.20 × 10−11 |
| n-pentanethiol | -- |
| 1,2-ethanedithiol | 3.80 × 10−11 |