gt_plt_bar_pct

gt_plt_bar_pct(
    gt,
    column,
    height=16,
    width=100,
    fill='purple',
    background='#e1e1e1',
    autoscale=True,
    labels=False,
    label_cutoff=0.4,
    decimals=1,
    font_style='normal',
    font_size=10,
)

Create horizontal bar plots in percentage in GT cells.

The gt_plt_bar_pct() function takes an existing GT object and adds horizontal bar plots via native HTML. By default, values are normalized as a percentage of the maximum value in the specified column. If the values already represent percentages (i.e., between 0–100), you can disable this behavior by setting autoscale=False.

Parameters

gt : GT

A GT object to modify.

column : SelectExpr

The column to target.

height : int = 16

The height of the bar plot in pixels.

width : int = 100

The width of the maximum bar in pixels.

fill : str = 'purple'

The fill color for the bars.

background : str = '#e1e1e1'

The background filling color for the bars. Defaults to #e1e1e1 (a light grey).

autoscale : bool = True

Indicates whether the function should automatically scale the values. If True, values will be divided by the column’s maximum and multiplied by 100. If False, the values are assumed to already be scaled appropriately.

labels : bool = False

True/False logical representing if labels should be plotted. Defaults to False, meaning that no value labels will be plotted.

label_cutoff : float = 0.4

A number, 0 to 1, representing where to set the inside/outside label boundary. Defaults to 0.40 (40%) of the column’s maximum value. If the value in that row is less than the cutoff, the label will be placed outside the bar; otherwise, it will be placed within the bar. This interacts with the overall width of the bar, so if you are not happy with the placement of the labels, you may try adjusting the width argument as well.

decimals : int = 1

A number representing how many decimal places to be used in label rounding.

font_style : Literal['oblique', 'italic', 'normal'] = 'normal'

The font style for the text labels displayed on the bars. Options are "oblique", "italic", or "normal".

font_size : int = 10

The font size for the text labels displayed on the bars.

Returns

: GT

A GT object with horizontal bar plots added to the specified columns.

Examples

The autoscale parameter is perhaps the most important in the gt_plt_bar_pct() function. This example demonstrates the difference between autoscale=True and autoscale=False using column x:

  • When autoscale=True: The function scales the values relative to the maximum in the column. For example, [10, 20, 30, 40] becomes [25%, 50%, 75%, 100%], which are used for both bar lengths and labels.

  • When autoscale=False: The values are assumed to already represent percentages. The function uses them as-is — e.g., [10%, 20%, 30%, 40%], which are directly reflected in both the bar lengths and labels.

import polars as pl
from great_tables import GT
import gt_extras as gte

df = pl.DataFrame({"x": [10, 20, 30, 40]}).with_columns(
    pl.col("x").alias("autoscale_on"),
    pl.col("x").alias("autoscale_off"),
)

gt = GT(df)

(
    gt.pipe(
        gte.gt_plt_bar_pct,
        column=["autoscale_on"],
        autoscale=True,
        labels=True,
        fill="green",
    ).pipe(
        gte.gt_plt_bar_pct,
        column=["autoscale_off"],
        autoscale=False,
        labels=True,
    )
)
x autoscale_on autoscale_off
10
25%
10%
20
50%
20%
30
75%
30%
40
100%
40%

Finally, label colors are automatically adjusted based on the fill and background parameters to ensure optimal readability.