gt_color_box

gt_color_box(
    gt,
    columns,
    domain=None,
    palette=None,
    alpha=0.2,
    min_width=70,
    min_height=20,
    font_weight='normal',
)

Add PFF-style color boxes to numeric columns in a GT object.

The gt_color_box() function takes an existing GT object and adds colored boxes to specified numeric columns. Each box contains a colored square and the numeric value, with colors mapped to the data values using a gradient palette.

Parameters

gt : GT

An existing GT object.

columns : SelectExpr

The columns to target. Can be a single column or a list of columns (by name or index). If None, the coloring is applied to all columns.

domain : list[int] | list[float] | None = None

The range of values to map to the color palette. Should be a list of two values (min and max). If None, the domain is inferred to be the min and max of the data range.

palette : list[str] | str | None = None

The color palette to use. This should be a list of colors (e.g., ["#FF0000", "#00FF00", "#0000FF"]). A ColorBrewer palette could also be used, just supply the name (see GT.data_color() for additional reference). If None, then a default palette will be used.

alpha : float = 0.2

The alpha (transparency) value for the background colors, as a float between 0 (fully transparent) and 1 (fully opaque).

min_width : int | float = 70

The minimum width of each color box in pixels.

min_height : int | float = 20

The minimum height of each color box in pixels.

font_weight : str = 'normal'

A string indicating the weight of the font for the numeric values. Can be "normal", "bold", or other CSS font-weight values. Defaults to "normal".

Returns

: GT

The modified GT object, allowing for method chaining.

Examples

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

islands_mini = (
    islands
    .sort_values(by="size", ascending=False)
    .head(10)
)

gt = (
    GT(islands_mini, rowname_col="name")
    .tab_stubhead(label="Island")
)

gt.pipe(gte.gt_color_box, columns="size", palette=["lightblue", "navy"])

Island	size
Asia	16988
Africa	11506
North America	9390
South America	6795
Antarctica	5500
Europe	3745
Australia	2968
Greenland	840
New Guinea	306
Borneo	280

Note

The exterior color box will expand to surround the widest cell in the column. The height and width parameters are given as min_width and min_height to ensure a color box always completely surrounds the text.