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 plot 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
2008-12-04
2008-12-05
2008-12-08
2008-12-09
2008-12-10
2008-12-11
2008-12-12
2008-12-15
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.