GT.sub_small_vals()

Substitute small values in the table body.

Usage

Source

GT.sub_small_vals(
    columns=None, rows=None, threshold=0.01, small_pattern=None, sign="+"
)

Wherever there is numerical data that are very small in value, replacement text may be better for explanatory purposes. The sub_small_vals() method allows for this replacement through specification of a threshold, a small_pattern, and the sign of the values to be considered. The substitution will occur for those values found to be between 0 and the threshold value. This is possible for small positive and small negative values (this can be explicitly set by the sign option). Note that the interval does not include the 0 or the threshold value. Should you need to include zero values, use sub_zero().

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 scanned for small values. 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.

threshold: int | float = 0.01

The threshold value with which values should be considered small enough for replacement.

small_pattern: str | None = None

The pattern text to be used in place of the suitably small values in the rendered table. The {x} placeholder within the pattern will be replaced with the threshold value. If not provided, the default is "<{x}" for positive values and ">-{x}" for negative values.

sign: str = "+"

The sign of the numbers to be considered in the replacement. By default, we only consider positive values ("+"). The other option ("-") can be used to consider only negative values.

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 generate a simple, single-column table that contains an assortment of values that could potentially undergo some substitution via sub_small_vals().

from great_tables import GT
import polars as pl

single_vals_df = pl.DataFrame(
    {
        "i": range(1, 8),
        "numbers": [0.0001, 0.001, 0.01, 0.1, 1.0, 10.0, 100.0]
    }
)

GT(single_vals_df).fmt_number(columns="numbers").sub_small_vals()

i	numbers
1	<0.01
2	<0.01
3	0.01
4	0.10
5	1.00
6	10.00
7	100.00

We can also target small negative values by setting sign="-" and use a custom small_pattern to provide alternative replacement text.

from great_tables import GT
import polars as pl

neg_vals_df = pl.DataFrame(
    {
        "i": range(1, 6),
        "numbers": [-0.0001, -0.005, -0.05, -1.0, -100.0]
    }
)

(
    GT(neg_vals_df)
    .fmt_number(columns="numbers")
    .sub_small_vals(sign="-", threshold=0.01, small_pattern="~0")
)

i	numbers
1	~0
2	~0
3	−0.05
4	−1.00
5	−100.00