GT.sub_values()

Substitute targeted values in the table body.

Usage

Source

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

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.

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