gt_plt_dumbbell

gt_plt_dumbbell(
    gt,
    col1,
    col2,
    label=None,
    width=100,
    height=30,
    col1_color='purple',
    col2_color='green',
    bar_color='grey',
    dot_border_color='white',
    font_size=10,
    num_decimals=1,
)

Create dumbbell plots in GT cells.

The gt_plt_dumbbell() function takes an existing GT object and adds dumbbell plots to visualize the difference between two numeric values. Each dumbbell consists of two dots (representing values from col1 and col2) connected by a horizontal bar, allowing for easy visual comparison between paired values.

Parameters

gt : GT

A GT object to modify.

col1 : SelectExpr

The column containing the first set of values to plot.

col2 : SelectExpr

The column containing the second set of values to plot.

label : str | None = None

Optional label to replace the column name of col1 in the output table. If None, the original column name is retained.

width : float = 100

The width of the dumbbell plot in pixels. Note that if the width is too narrow, some label text may overlap.

height : float = 30

The height of the dumbbell plot in pixels.

col1_color : str = 'purple'

The color of the dots representing values from col1.

col2_color : str = 'green'

The color of the dots representing values from col2.

bar_color : str = 'grey'

The color of the horizontal bar connecting the two dots.

dot_border_color : = 'white'

The color of the borders around the two dots.

font_size : int = 10

The font size for the value labels displayed above each dot.

num_decimals : int = 1

The number of decimal places to display in the value labels.

Returns

: GT

A GT object with dumbbell plots added to the specified columns. The col2 column is hidden from the final table display.

Examples

import pandas as pd
from great_tables import GT, html, style, loc
from great_tables.data import sp500
import gt_extras as gte

# Trim the data to December 2008
df = sp500[["date", "open", "close"]].copy()
df["date"] = pd.to_datetime(df["date"], errors='coerce')

dec_2008 = df[
    (df["date"].dt.month == 12) &
    (df["date"].dt.year == 2008)
]
dec_2008 = dec_2008.iloc[::-1].iloc[2:11]

# Make the Great Table
gt = (
    GT(dec_2008)
    .tab_source_note(html("Purple: Open<br>Green: Close"))
    .tab_style(
        style=style.text(align="right"),
        locations=[loc.source_notes()]
    )
)

gt.pipe(
    gte.gt_plt_dumbbell,
    col1='open',
    col2='close',
    label = "Open to Close ($)",
    num_decimals=0,
    width = 250,
)

date	Open to Close ($)
2008-12-03	844 871
2008-12-04	870 845
2008-12-05	844 876
2008-12-08	883 910
2008-12-09	906 889
2008-12-10	892 899
2008-12-11	898 874
2008-12-12	872 880
2008-12-15	881 869
Purple: Open Green: Close

Note

All dumbbells are scaled to a common range for visual alignment across rows. The col2 column is automatically hidden from the final table display.