## GT.sub_values()
Substitute targeted values in the table body.
Usage
``` python
GT.sub_values(
columns=None,
rows=None,
values=None,
pattern=None,
fn=None,
replacement=None
)
```
Should you need to replace specific cell values with custom text, [sub_values()](GT.sub_values.md#great_tables.GT.sub_values) can be a good choice. We can target cells for replacement through value, regex, and custom matching rules.
## Parameters
`columns: SelectExpr = None`
The columns to target. Can either be a single column name or a series of column names provided in a list.
`rows: int | list[int] | None = None`
In conjunction with `columns=`, we can specify which of their rows should be targeted for substitution. The default is all rows, resulting in all rows in all targeted columns being considered for this substitution. Alternatively, we can supply a list of row indices.
`values: list[Any] | Any | None = None`
The specific value or values that should be replaced with a `replacement` value. If `pattern` is also supplied then `values` will be ignored.
`pattern: str | None = None`
A regex pattern that can target solely those values in character-based columns. If `values` is also supplied, `pattern` will take precedence.
`fn: Callable[…, bool] | None = None`
A supplied function that operates on each cell value `x` and should return a boolean indicating whether that value should be replaced. If either of `values` or `pattern` is also supplied, `fn` will take precedence.
`replacement: str | int | float | None = None`
The replacement value for any cell values matched by either `values`, `pattern`, or `fn`. Must be a string or numeric value.
## 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.
## Examples
Let's create an input table with three columns containing an assortment of values that could potentially undergo some substitution via [sub_values()](GT.sub_values.md#great_tables.GT.sub_values).
``` python
from great_tables import GT
import polars as pl
tbl = pl.DataFrame(
{
"num_1": [-0.01, 74.0, None, 0.0, 500.0, 0.001, 84.3],
"int_1": [1, -100000, 800, 5, None, 1, -32],
"lett": ["A", "B", "C", "D", "E", "F", "G"],
}
)
GT(tbl).sub_values(values=[74, 500], replacement="--")
```
| num_1 | int_1 | lett |
|-------|---------|------|
| -0.01 | 1 | A |
| -- | -100000 | B |
| None | 800 | C |
| 0.0 | 5 | D |
| -- | None | E |
| 0.001 | 1 | F |
| 84.3 | -32 | G |
For the most flexibility, use the `fn` argument. The function you provide should accept a cell value and return a boolean indicating whether it should be replaced.
``` python
from great_tables import GT
import polars as pl
tbl = pl.DataFrame(
{
"num_1": [-0.01, 74.0, None, 0.0, 500.0, 0.001, 84.3],
"int_1": [1, -100000, 800, 5, None, 1, -32],
"lett": ["A", "B", "C", "D", "E", "F", "G"],
}
)
(
GT(tbl)
.sub_values(
fn=lambda x: isinstance(x, (int, float)) and x >= 0 and x < 50,
replacement="small"
)
)
```
| num_1 | int_1 | lett |
|-------|---------|------|
| -0.01 | small | A |
| 74.0 | -100000 | B |
| None | 800 | C |
| small | small | D |
| 500.0 | None | E |
| small | small | F |
| 84.3 | -32 | G |