# Text Transforms
Sometimes the final step in preparing a table involves modifying the text content of cells after all formatting has been applied. The `text_*()` methods operate on the already-rendered text in cells, giving you a post-processing layer for tasks like replacing abbreviations, applying conditional labels, or inserting custom HTML. These methods complement the `fmt_*()` methods, which work on raw data values.
# Setting Up the Example Data
``` python
import polars as pl
from great_tables import GT, loc, md
status_df = pl.DataFrame({
"task": ["Data collection", "Analysis", "Report writing", "Peer review"],
"status": ["DONE", "IN_PROGRESS", "NOT_STARTED", "DONE"],
"priority": ["high", "high", "medium", "low"],
"progress": [100, 65, 0, 100],
})
gt_tbl = GT(status_df, rowname_col="task")
gt_tbl
```
| | status | priority | progress |
|-----------------|-------------|----------|----------|
| Data collection | DONE | high | 100 |
| Analysis | IN_PROGRESS | high | 65 |
| Report writing | NOT_STARTED | medium | 0 |
| Peer review | DONE | low | 100 |
This produces a basic table with coded status values and numeric progress, which we will transform using the text methods below.
# Custom Text Transformations
The [text_transform()](../reference/GT.text_transform.md#great_tables.GT.text_transform) method is the most flexible of the text methods. It takes a location specifier and a function that receives a cell's text content as a string and returns the transformed string. The transformation runs after all `fmt_*()` methods have been applied.
``` python
(
gt_tbl
.text_transform(
locations=loc.body(columns="status"),
fn=lambda text: text.replace("_", " ").title()
)
)
```
| | status | priority | progress |
|-----------------|-------------|----------|----------|
| Data collection | Done | high | 100 |
| Analysis | In Progress | high | 65 |
| Report writing | Not Started | medium | 0 |
| Peer review | Done | low | 100 |
The underscores in status values are replaced with spaces and the text is converted to title case. This is useful when your data contains coded values that need to be made more readable.
You can also return HTML from the transform function to add visual elements to cells.
``` python
def add_progress_indicator(text):
value = int(text)
color = "green" if value == 100 else "orange" if value > 0 else "gray"
bar = f''
return f'{text}%
{bar}'
(
gt_tbl
.text_transform(
locations=loc.body(columns="progress"),
fn=add_progress_indicator
)
)
```
|
status |
priority |
progress |
| Data collection |
DONE |
high |
100%
|
| Analysis |
IN_PROGRESS |
high |
65%
|
| Report writing |
NOT_STARTED |
medium |
0%
|
| Peer review |
DONE |
low |
100%
|
Each progress cell now displays both the numeric percentage and a colored bar beneath it. Returning raw HTML from the function lets you embed rich visual elements directly in table cells.
# Text Replacement with Regex
The [text_replace()](../reference/GT.text_replace.md#great_tables.GT.text_replace) method performs regex-based find-and-replace on cell content. It is a simpler alternative to [text_transform()](../reference/GT.text_transform.md#great_tables.GT.text_transform) when you just need pattern matching.
``` python
(
gt_tbl
.text_replace(
pattern=r"_",
replacement=" ",
locations=loc.body(columns="status")
)
)
```
| | status | priority | progress |
|-----------------|-------------|----------|----------|
| Data collection | DONE | high | 100 |
| Analysis | IN PROGRESS | high | 65 |
| Report writing | NOT STARTED | medium | 0 |
| Peer review | DONE | low | 100 |
All underscores in the `status` column are replaced with spaces. The `pattern=` argument accepts full Python regex syntax, so you can use capture groups and backreferences in the `replacement=` string.
``` python
(
gt_tbl
.text_replace(
pattern=r"(\w+)_(\w+)",
replacement=r"\1 \2",
locations=loc.body(columns="status")
)
)
```
| | status | priority | progress |
|-----------------|-------------|----------|----------|
| Data collection | DONE | high | 100 |
| Analysis | IN PROGRESS | high | 65 |
| Report writing | NOT STARTED | medium | 0 |
| Peer review | DONE | low | 100 |
The regex captures the two words separated by an underscore and reconstructs them with a space in between. This technique is especially handy when your data has structured codes with consistent delimiters.
# Case Matching
The [text_case_match()](../reference/GT.text_case_match.md#great_tables.GT.text_case_match) method provides a switch-like mechanism for replacing cell text. You supply tuples of `(old_text, new_text)` and the method matches cell content against each case in order.
``` python
(
gt_tbl
.text_case_match(
("DONE", "Complete ✓"),
("IN_PROGRESS", "In Progress"),
("NOT_STARTED", "Not Started"),
locations=loc.body(columns="status")
)
)
```
| | status | priority | progress |
|-----------------|-------------|----------|----------|
| Data collection | Complete ✓ | high | 100 |
| Analysis | In Progress | high | 65 |
| Report writing | Not Started | medium | 0 |
| Peer review | Complete ✓ | low | 100 |
Each status code is mapped to a more readable label. By default, [text_case_match()](../reference/GT.text_case_match.md#great_tables.GT.text_case_match) compares the entire cell text (i.e., `replace="all"`). You can set `replace="partial"` to match substrings instead.
## Matching Multiple Values to One Replacement
The first element of each case tuple can be a list of strings, allowing you to map multiple values to the same replacement.
``` python
(
gt_tbl
.text_case_match(
(["DONE", "IN_PROGRESS"], "Active"),
("NOT_STARTED", "Pending"),
locations=loc.body(columns="status")
)
)
```
| | status | priority | progress |
|-----------------|---------|----------|----------|
| Data collection | Active | high | 100 |
| Analysis | Active | high | 65 |
| Report writing | Pending | medium | 0 |
| Peer review | Active | low | 100 |
Both `"DONE"` and `"IN_PROGRESS"` map to `"Active"`, reducing several statuses down to fewer categories. This is convenient when you want to simplify grouped labels for presentation.
## Providing a Default
If some cell values do not match any case, they remain unchanged by default. You can set a fallback value with the `default=` argument.
``` python
(
gt_tbl
.text_case_match(
("DONE", "Complete"),
default="Other",
locations=loc.body(columns="status")
)
)
```
| | status | priority | progress |
|-----------------|----------|----------|----------|
| Data collection | Complete | high | 100 |
| Analysis | Other | high | 65 |
| Report writing | Other | medium | 0 |
| Peer review | Complete | low | 100 |
Cells containing `"IN_PROGRESS"` and `"NOT_STARTED"` both become `"Other"` since they did not match the single case provided.
# Conditional Text Replacement
The [text_case_when()](../reference/GT.text_case_when.md#great_tables.GT.text_case_when) method gives you predicate-based replacement logic. Each case is a tuple of `(predicate_function, replacement_text)`, where the predicate receives the cell text as a string and returns `True` or `False`. The first matching predicate determines the replacement.
``` python
(
gt_tbl
.text_case_when(
(lambda x: x == "100", "Complete"),
(lambda x: int(x) > 0, "In Progress"),
(lambda x: x == "0", "Not Started"),
locations=loc.body(columns="progress")
)
)
```
| | status | priority | progress |
|-----------------|-------------|----------|-------------|
| Data collection | DONE | high | Complete |
| Analysis | IN_PROGRESS | high | In Progress |
| Report writing | NOT_STARTED | medium | Not Started |
| Peer review | DONE | low | Complete |
This approach is particularly powerful when your replacement logic depends on the value itself (such as numeric thresholds) rather than exact string matching.
# Targeting Different Locations
All text methods support the `locations=` argument, which defaults to [loc.body()](../reference/loc.body.md#great_tables.loc.body) when not specified. You can target other parts of the table as well.
## Transforming Row Group Labels
``` python
df_grouped = pl.DataFrame({
"name": ["Alice", "Bob", "Charlie", "Diana"],
"team": ["team_alpha", "team_alpha", "team_beta", "team_beta"],
"score": [92, 87, 95, 78],
})
(
GT(df_grouped, rowname_col="name", groupname_col="team")
.text_replace(
pattern=r"team_(\w+)",
replacement=r"Team \1",
locations=loc.row_groups()
)
)
```
|
score |
| Team alpha |
| Alice |
92 |
| Bob |
87 |
| Team beta |
| Charlie |
95 |
| Diana |
78 |
The row group labels are transformed from `"team_alpha"` and `"team_beta"` to `"Team alpha"` and `"Team beta"`. This keeps the source data unchanged while presenting a polished label in the table.
## Transforming Column Labels
``` python
(
gt_tbl
.text_transform(
locations=loc.column_labels(columns="progress"),
fn=lambda text: text.upper()
)
)
```
| | status | priority | PROGRESS |
|-----------------|-------------|----------|----------|
| Data collection | DONE | high | 100 |
| Analysis | IN_PROGRESS | high | 65 |
| Report writing | NOT_STARTED | medium | 0 |
| Peer review | DONE | low | 100 |
The `"progress"` column label is converted to uppercase. You can target any combination of column labels using the `columns=` argument within [loc.column_labels()](../reference/loc.column_labels.md#great_tables.loc.column_labels).
# Combining Text Methods
You can chain multiple text methods together. They are applied in the order specified, each operating on the result of the previous transformation.
``` python
(
gt_tbl
.text_case_match(
("DONE", "Complete"),
("IN_PROGRESS", "In Progress"),
("NOT_STARTED", "Not Started"),
locations=loc.body(columns="status")
)
.text_case_match(
("high", "High ●"),
("medium", "Medium ●"),
("low", "Low ●"),
locations=loc.body(columns="priority")
)
)
```
| | status | priority | progress |
|-----------------|-------------|----------|----------|
| Data collection | Complete | High ● | 100 |
| Analysis | In Progress | High ● | 65 |
| Report writing | Not Started | Medium ● | 0 |
| Peer review | Complete | Low ● | 100 |
The text transformation methods provide a final layer of control over how your table content appears. Whether you need simple find-and-replace, switch-like mappings, or complex conditional logic, these methods let you shape the text to match your exact presentation needs.