fmt_pct_extra

fmt_pct_extra(gt, columns, scale=100, threshold=1.0, color='grey', decimals=1)

Convert to percent and show less than 1% as <1% in grey.

The fmt_pct_extra() function takes an existing GT object and formats a column of numeric values as percentages. Values below the specified threshold are displayed as "<threshold%" instead of their actual percentage value, and in a color of your choosing. The default behavior expects values in the range [0, 1], use scale if your values are in a different range.

Parameters

gt : GT: A GT object to modify.
columns : SelectExpr: The columns containing numeric values to format as percentages.
scale : float = 100: Multiplication factor to convert values to percentages. For some common cases: use 100 if values are decimals (0.05 -> 5%) (default), use 1 if values are already percentages (5 -> 5%).
threshold : float = 1.0: The percentage threshold below which values are displayed as "<threshold%" instead of their actual value. Note this refers to the scaled value, not the original, so you will have to provide 5 for <5% even if your original are in the range [0,1].
color : str = 'grey': The color to use for values below the threshold.
decimals : int = 1: Number of decimal places to display for percentages.

Returns

: GT: A GT object with formatted percentage column.

Examples

from great_tables import GT
from great_tables.data import towny
import gt_extras as gte

towny_mini = towny[
    [
        "name",
        "pop_change_1996_2001_pct",
        "pop_change_2001_2006_pct",
        "pop_change_2006_2011_pct",
    ]
].tail(10)

gt = (
    GT(towny_mini)
    .tab_spanner(label="Population Change", columns=[1, 2, 3])
    .cols_label(
        pop_change_1996_2001_pct="'96-'01",
        pop_change_2001_2006_pct="'01-'06",
        pop_change_2006_2011_pct="'06-'11",
    )
)

gt.pipe(
    gte.fmt_pct_extra,
    columns=[1, 2, 3],
    threshold=5,
    color="green",
)

name	Population Change
name	'96-'01	'01-'06	'06-'11
Whitchurch-Stouffville	11.6%	6.7%	54.3%
White River	<5%	-15.3%	-27.8%
Whitestone	6.4%	20.8%	-10.9%
Whitewater	<5%	<5%	<5%
Wilmot	7.5%	15.0%	12.4%
Windsor	5.4%	<5%	<5%
Wollaston	-5.6%	7.5%	<5%
Woodstock	<5%	8.3%	5.4%
Woolwich	5.1%	8.0%	17.7%
Zorra	<5%	<5%	<5%