Geoms API Reference

Geometric objects (geoms) are the visual elements used to represent data in a plot.

Basic Geoms

ggplotly.geoms.geom_point.geom_point

Bases: Geom

Geom for drawing point plots.

Automatically handles categorical variables for color, shape, and group. When used with geom_map (geographic plots), automatically uses geographic coordinates where x=longitude and y=latitude.

Parameters:

Name	Type	Description	Default
color	str	Color of the points. If a column name, maps categories to colors.	required
size	int	Size of the points. Default is 8.	required
alpha	float	Transparency level for the points. Default is 1.	required
shape	str	Shape of the points. If a column name, maps categories to shapes. Literal values can be any Plotly marker symbol (e.g., 'circle', 'square', 'diamond', 'cross', 'x', 'triangle-up', 'triangle-down', 'star', 'hexagon', etc.)	required
stroke	float	Width of the point border/outline. Default is 0. In ggplot2, this applies to shapes 21-25 (filled shapes with borders).	required
group	str	Grouping variable for the points.	required

Required Aesthetics

x, y

Optional Aesthetics

color, fill, size, shape, alpha, group

ggplotly.geoms.geom_line.geom_line

Bases: Geom

Geom for drawing line plots, sorted by x-axis values.

Connects points in order of x-axis values (sorted). For connecting points in data order (unsorted), use geom_path instead.

Parameters:

Name	Type	Description	Default
color	str	Color of the lines. If not provided, will use the theme's color palette.	required
linetype	str	Line style ('solid', 'dash', etc.). Default is 'solid'.	required
alpha	float	Transparency level for the lines. Default is 1.	required
size	float	Line width. Default is 2.	required
linewidth	float	Alias for size (ggplot2 3.4+ compatibility).	required
group	str	Grouping variable for the lines.	required

Aesthetics

• x: x-axis values (data will be sorted by this)
• y: y-axis values
• color: Grouping variable for colored lines
• group: Grouping variable for separate lines

See Also

geom_path: Connect points in data order (no sorting)

ggplotly.geoms.geom_path.geom_path

Bases: Geom

Geom for drawing paths connecting points in data order.

Unlike geom_line which sorts points by x-axis value, geom_path connects points in the order they appear in the data. This is useful for: - Trajectories and movement paths - Time series with non-monotonic x values - Connected scatterplots - Drawing arbitrary shapes

Parameters:

Name	Type	Description	Default
color	str	Color of the path. Can be a column name for grouping.	required
colour	str	Alias for color (British spelling).	required
size	float	Line width. Default is 2.	required
linewidth	float	Alias for size (ggplot2 3.4+ compatibility).	required
linetype	str	Line style ('solid', 'dash', 'dot', 'dashdot'). Default is 'solid'.	required
alpha	float	Transparency level. Default is 1.	required
na_rm	bool	If True, remove missing values. Default is False.	required
show_legend	bool	Whether to show in legend. Default is True.	required

Aesthetics

• x: x-axis values
• y: y-axis values
• color: Grouping variable for colored paths
• group: Grouping variable for separate paths

Examples:

Simple path (connects points in data order)

ggplot(trajectory, aes(x='x', y='y')) + geom_path()

Spiral (x is not monotonic)

ggplot(spiral_data, aes(x='x', y='y')) + geom_path()

Connected scatterplot with time

ggplot(data, aes(x='gdp', y='life_exp', group='country')) + geom_path()

Multiple colored trajectories

ggplot(tracks, aes(x='x', y='y', color='track_id')) + geom_path()

ggplotly.geoms.geom_lines.geom_lines

Bases: Geom

Geom for efficiently plotting many line series.

Designed for T×N matrices where each column is a separate series. Uses a single Plotly trace with None separators for performance.

Parameters

data : DataFrame, optional Data for the geom (overrides plot data). mapping : aes, optional Aesthetic mappings. If x not specified, uses DataFrame index. columns : list, optional Specific columns to plot. Default is all numeric columns. color : str, optional Line color. Default is theme color. Ignored if multicolor=True. alpha : float, optional Line transparency. Default is 0.5. size : float, optional Line width. Default is 1. showlegend : bool, optional Whether to show legend. Default is False. multicolor : bool, optional If True, each series gets a different color from the palette. Default is False. palette : str or list, optional Color palette to use when multicolor=True. Can be a Plotly colorscale name ('Viridis', 'Plasma', etc.) or a list of colors. Default is 'Plotly'.

Examples

Plot all columns (single color)

ggplot(df) + geom_lines()

Multi-colored lines

ggplot(df) + geom_lines(multicolor=True)

Multi-colored with custom palette

ggplot(df) + geom_lines(multicolor=True, palette='Viridis')

ggplotly.geoms.geom_fanchart.geom_fanchart

Bases: Geom

Geom for displaying fan charts (percentile bands) from T×N matrices.

Computes percentiles across columns at each time point and displays as nested transparent ribbons with an optional median line.

Uses stat_fanchart internally for percentile computation.

Parameters

data : DataFrame, optional Data for the geom (overrides plot data). mapping : aes, optional Aesthetic mappings. If x not specified, uses DataFrame index. columns : list, optional Specific columns to include in percentile calculation. Default is all numeric columns. percentiles : list, optional Percentile levels to display. Default is [10, 25, 50, 75, 90]. color : str, optional Base color for the bands. Default is 'steelblue'. alpha : float, optional Base transparency for outermost band. Inner bands are more opaque. Default is 0.2. show_median : bool, optional Whether to show the median line. Default is True. median_color : str, optional Color for median line. Default is same as color. median_width : float, optional Width of median line. Default is 2.

Examples

Basic fan chart

ggplot(df) + geom_fanchart()

Custom percentiles

ggplot(df) + geom_fanchart(percentiles=[5, 25, 50, 75, 95])

Styled fan chart

ggplot(df) + geom_fanchart(color='coral', alpha=0.3)

ggplotly.geoms.geom_bar.geom_bar

Bases: Geom

Geom for drawing bar plots.

Automatically handles categorical variables for color and fill. Automatically converts 'group' and 'fill' columns to categorical if necessary.

Parameters:

Name	Type	Description	Default
mapping	aes	Aesthetic mappings created by aes().	None
color	str	Color of the bars. If a categorical variable is mapped to color, different colors will be assigned.	required
group	str	Grouping variable for the bars.	required
fill	str	Fill color for the bars.	required
alpha	float	Transparency level for the fill color. Default is 1.	required
showlegend	bool	Whether to show legend entries. Default is True.	required
stat		['count', 'identity', None] The statistical transformation to use on the data for this layer. Default is 'count'.	required
width	float	Bar width as a fraction of the distance between bars. Default is 0.9 (90% of available space). Use values between 0 and 1.	required
position	str	Position adjustment. Options are 'stack' (default), 'dodge', 'fill', or 'identity'.	required
na_rm	bool	If True, silently remove missing values. Default is False.	required

Examples:

>>> ggplot(df, aes(x='category')) + geom_bar()
>>> ggplot(df, aes(x='category', fill='group')) + geom_bar(position='dodge')
>>> ggplot(df, aes(x='category')) + geom_bar(width=0.5)  # narrower bars

ggplotly.geoms.geom_col.geom_col

Bases: Geom

Geom for drawing column plots (similar to bar plots).

Automatically handles categorical variables for color and fill. Automatically converts 'group' and 'fill' columns to categorical if necessary.

Parameters:

Name	Type	Description	Default
fill	str	Fill color for the columns.	required
color	str	Border color for the columns.	required
alpha	float	Transparency level for the fill color. Default is 1.	required
width	float	Width of the bars as fraction of available space. Default is 0.9. Values should be between 0 and 1.	required
group	str	Grouping variable for the columns.	required
na_rm	bool	If True, remove missing values. Default is False.	required
show_legend	bool	Whether to show in legend. Default is True.	required

Examples:

>>> ggplot(df, aes(x='category', y='value')) + geom_col()
>>> ggplot(df, aes(x='category', y='value', fill='group')) + geom_col()
>>> ggplot(df, aes(x='category', y='value')) + geom_col(width=0.5)

ggplotly.geoms.geom_histogram.geom_histogram

Bases: Geom

Geom for drawing histograms.

Automatically handles categorical variables for color and fill. Automatically converts 'group' and 'fill' columns to categorical if necessary.

Parameters:

Name	Type	Description	Default
mapping	aes	Aesthetic mappings created by aes().	None
bins	int	Number of bins. Default is 30. Overridden by binwidth if specified.	30
binwidth	float	Width of each bin. Overrides bins if specified. In ggplot2, this is the preferred way to specify bin size.	None
boundary	float	A boundary between bins. Shifts bin edges to align with this value. For example, boundary=0 ensures a bin edge at 0.	None
center	float	The center of one of the bins. Alternative to boundary.	None
color	str	Color of the histogram bars. If a categorical variable is mapped to color, different colors will be assigned.	required
group	str	Grouping variable for the histogram bars.	required
fill	str	Fill color for the bars.	required
alpha	float	Transparency level for the fill color. Default is 1.	required
showlegend	bool	Whether to show legend entries. Default is True.	required
position	str	Position adjustment: 'stack' (default), 'dodge', 'identity'.	required
na_rm	bool	If True, silently remove missing values. Default is False.	required

Examples:

>>> ggplot(df, aes(x='value')) + geom_histogram()
>>> ggplot(df, aes(x='value')) + geom_histogram(bins=20)
>>> ggplot(df, aes(x='value')) + geom_histogram(binwidth=5)
>>> ggplot(df, aes(x='value', fill='category')) + geom_histogram(alpha=0.5)

__init__(data=None, mapping=None, bins=30, binwidth=None, boundary=None, center=None, barmode='stack', bin=None, **params)

Initialize the histogram geom.

Parameters:

Name	Type	Description	Default
data	DataFrame	Data for this geom.	None
mapping	aes	Aesthetic mappings.	None
bins	int	Number of bins. Default is 30. Overridden by binwidth if specified.	30
binwidth	float	Width of each bin. Overrides bins if specified.	None
boundary	float	A boundary between bins.	None
center	float	The center of one of the bins.	None
barmode	str	Bar mode ('stack', 'overlay', 'group'). Default is 'stack'.	'stack'
bin	int	Deprecated alias for bins. Use bins instead.	None
**params		Additional parameters.	{}

Distribution Geoms

ggplotly.geoms.geom_boxplot.geom_boxplot

Bases: Geom

Geom for drawing boxplots.

__init__(data=None, mapping=None, outlier_colour=None, outlier_color=None, outlier_fill=None, outlier_shape='circle', outlier_size=1.5, outlier_stroke=0.5, outlier_alpha=None, notch=False, varwidth=False, coef=1.5, width=0.75, **params)

Create a boxplot geom.

Automatically handles categorical variables for color and fill. Automatically converts 'group' and 'fill' columns to categorical if necessary.

Parameters

data : DataFrame, optional Data for this geom. mapping : aes, optional Aesthetic mappings. outlier_colour : str, optional Color of outlier points. Default is 'black'. Alias: outlier_color. outlier_color : str, optional Alias for outlier_colour. outlier_fill : str, optional Fill color of outlier points. Default is None (same as outlier_colour). outlier_shape : str or int, default='circle' Shape of outlier points. Plotly marker symbols: 'circle', 'square', 'diamond', 'cross', etc. outlier_size : float, default=1.5 Size of outlier points. outlier_stroke : float, default=0.5 Stroke width of outlier points. outlier_alpha : float, optional Alpha transparency of outlier points. Default is None (use main alpha). notch : bool, default=False If True, draw a notched boxplot. Notches display confidence interval around median. varwidth : bool, default=False If True, vary box width by group size. Note: Limited support in Plotly. coef : float, default=1.5 Length of whiskers as multiple of IQR. Points beyond whiskers are plotted as outliers. width : float, default=0.75 Box width. **params Additional parameters passed to the geom.

Examples

from ggplotly import ggplot, aes, geom_boxplot, data mpg = data('mpg')

Basic boxplot by vehicle class

ggplot(mpg, aes(x='class', y='hwy')) + geom_boxplot()

Boxplot with fill color by drive type

ggplot(mpg, aes(x='class', y='hwy', fill='drv')) + geom_boxplot()

Notched boxplot showing confidence interval

ggplot(mpg, aes(x='class', y='hwy')) + geom_boxplot(notch=True)

Custom outlier styling

ggplot(mpg, aes(x='class', y='hwy')) + geom_boxplot(outlier_colour='red', outlier_size=3)

ggplotly.geoms.geom_violin.geom_violin

Bases: Geom

Geom for drawing violin plots.

Automatically handles categorical variables for color and fill. Automatically converts 'group' and 'fill' columns to categorical if necessary.

Parameters:

Name	Type	Description	Default
fill	str	Fill color for the violins.	required
alpha	float	Transparency level for the fill color. Default is 0.5.	required
color	str	Outline color of the violin plots.	required
linewidth	float	Line width of the violin outline.	required
group	str	Grouping variable for the violin plots.	required

ggplotly.geoms.geom_density.geom_density

Bases: Geom

Geom for drawing density plots.

__init__(data=None, mapping=None, bw='nrd0', adjust=1, kernel='gaussian', n=512, trim=False, **params)

Create a density plot geom.

Automatically handles categorical variables for color and fill. Automatically converts 'group' and 'fill' columns to categorical if necessary.

Parameters

data : DataFrame, optional Data for this geom. mapping : aes, optional Aesthetic mappings. bw : str or float, default='nrd0' Bandwidth method or value. Options:

- 'nrd0': Scott's rule (default, matches R's default)
- 'nrd': Silverman's rule
- 'scott': Scott's rule (alias for nrd0)
- 'silverman': Silverman's rule (alias for nrd)
- A numeric value for a fixed bandwidth

adjust : float, default=1 Bandwidth adjustment multiplier. Values > 1 produce smoother curves, < 1 produce more detail. kernel : str, default='gaussian' Kernel to use. Note: scipy's gaussian_kde only supports gaussian kernel. n : int, default=512 Number of evaluation points (matches R's default). trim : bool, default=False If True, trim density to range of data. **params Additional parameters including:

- fill (str): Fill color for the density plot.
- color (str): Line color for the density curve.
- colour (str): Alias for color (British spelling).
- alpha (float): Transparency level. Default is 0.5.
- size (float): Line width. Default is 2.
- linewidth (float): Alias for size (ggplot2 3.4+ compatibility).
- linetype (str): Line style ('solid', 'dash', etc.).
- na_rm (bool): If True, silently remove missing values.
- show_legend (bool): Whether to show in legend. Default is True.

Examples

from ggplotly import ggplot, aes, geom_density, data mpg = data('mpg')

Basic density plot of highway MPG

ggplot(mpg, aes(x='hwy')) + geom_density()

Less smoothing with adjust parameter

ggplot(mpg, aes(x='hwy')) + geom_density(adjust=0.5)

Fixed bandwidth

ggplot(mpg, aes(x='hwy')) + geom_density(bw=2)

Grouped density with fill and transparency

ggplot(mpg, aes(x='hwy', fill='drv')) + geom_density(alpha=0.3)

ggplotly.geoms.geom_norm.geom_norm

Bases: Geom

Geom for overlaying a normal distribution curve.

Automatically fits a normal distribution to the data (using mean and std) unless mean and sd are explicitly provided. Useful for comparing actual data distribution to theoretical normal distribution.

Parameters

data : DataFrame, optional Data for the geom (overrides plot data). mapping : aes, optional Aesthetic mappings. Uses x aesthetic to determine data range. mean : float, optional Mean of the normal distribution. If None, computed from data. sd : float, optional Standard deviation of the normal distribution. If None, computed from data. scale : str, optional Output scale: 'density' (default) outputs PDF values, 'count' scales to match histogram counts (PDF * n * binwidth). When 'count', automatically estimates binwidth from data range and number of observations. binwidth : float, optional Bin width for count scaling. If None, estimated as data_range / 30. n : int, optional Number of points for the curve. Default is 101. color : str, optional Color of the line. Default is 'red'. size : float, optional Width of the line. Default is 2. linetype : str, optional Line style ('solid', 'dash', etc.). Default is 'solid'.

Examples

With density-scaled histogram (default)

ggplot(df, aes(x='x')) + geom_histogram(aes(y=after_stat('density'))) + geom_norm()

With count histogram (no density scaling needed on histogram)

ggplot(df, aes(x='x')) + geom_histogram(bins=30) + geom_norm(scale='count')

Explicit parameters

ggplot(df, aes(x='x')) + geom_histogram(bins=30) + geom_norm(scale='count', mean=0, sd=1)

Styled

ggplot(df, aes(x='x')) + geom_histogram(aes(y=after_stat('density'))) + geom_norm(color='blue', size=3)

Area Geoms

ggplotly.geoms.geom_area.geom_area

Bases: Geom

Geom for drawing area plots.

Automatically handles continuous and categorical variables for fill. Automatically converts 'group' columns to categorical if necessary.

Parameters:

Name	Type	Description	Default
mapping	aes	Aesthetic mappings created by aes().	None
color	str	Color of the area outline.	required
colour	str	Alias for color (British spelling).	required
linetype	str	Line type ('solid', 'dash', etc.). Default is 'solid'.	required
size	float	Line width. Default is 1.	required
linewidth	float	Alias for size (ggplot2 3.4+ compatibility).	required
group	str	Grouping variable for the areas.	required
fill	str	Fill color for the area.	required
alpha	float	Transparency level for the fill color. Default is 0.5.	required
position	str	Position adjustment. Options: - 'identity': No stacking (default) - 'stack': Stack areas on top of each other	required
show_legend	bool	Whether to show legend entries. Default is True.	required
showlegend	bool	Alias for show_legend.	required
na_rm	bool	If True, remove missing values. Default is False.	required

Examples:

>>> ggplot(df, aes(x='x', y='y')) + geom_area()
>>> ggplot(df, aes(x='x', y='y', fill='group')) + geom_area(alpha=0.5)
>>> ggplot(df, aes(x='x', y='y', fill='group')) + geom_area(position='stack')

ggplotly.geoms.geom_ribbon.geom_ribbon

Bases: Geom

Geom for drawing ribbon plots.

Automatically handles categorical variables for color and fill. Automatically converts 'group' and 'fill' columns to categorical if necessary.

Parameters:

Name	Type	Description	Default
ymin	float	Minimum y value for the ribbon.	required
ymax	float	Maximum y value for the ribbon.	required
fill	str	Fill color for the ribbon.	required
color	str	Color of the ribbon outline.	required
alpha	float	Transparency level for the fill color. Default is 0.5.	required
size	float	Line width for the ribbon outline. Default is 1.	required
linewidth	float	Alias for size (ggplot2 3.4+ compatibility).	required
linetype	str	Line style for the outline ('solid', 'dash', etc.).	required
group	str	Grouping variable for the ribbon.	required
na_rm	bool	If True, remove missing values. Default is False.	required
show_legend	bool	Whether to show in legend. Default is True.	required

Examples:

>>> ggplot(df, aes(x='x', ymin='lower', ymax='upper')) + geom_ribbon()
>>> ggplot(df, aes(x='x', ymin='lower', ymax='upper')) + geom_ribbon(fill='blue', alpha=0.3)

setup_data(data, plot_mapping)

Override setup_data to propagate data to child layers.

Parameters:

Name	Type	Description	Default
data	DataFrame	The dataset to use.	required
plot_mapping	dict	The global aesthetic mappings from the plot.	required

ggplotly.geoms.geom_tile.geom_tile

Bases: Geom

Geom for drawing tile plots (heatmaps).

Automatically handles both continuous and categorical variables for color and fill. Automatically converts 'group' and 'fill' columns to categorical if necessary.

Parameters:

Name	Type	Description	Default
fill	str	Fill color for the tiles.	required
alpha	float	Transparency level for the fill color. Default is 1.	required
palette	str	Color palette name for continuous fill. Default is 'Viridis'.	required
group	str	Grouping variable for the tiles.	required

ggplotly.geoms.geom_rect.geom_rect

Bases: Geom

Geom for drawing rectangles.

Rectangles are defined by their corner coordinates (xmin, xmax, ymin, ymax). Useful for highlighting regions, drawing backgrounds, or creating custom shapes.

Parameters:

Name	Type	Description	Default
fill	str	Fill color for the rectangles. Default is theme color.	required
color	str	Border color for the rectangles. Default is None (no border).	required
alpha	float	Transparency level (0-1). Default is 0.5.	required
linetype	str	Border line style ('solid', 'dash', 'dot', 'dashdot'). Default is 'solid'.	required
size	float	Border line width. Default is 1.	required
linewidth	float	Alias for size (ggplot2 3.4+ compatibility).	required

Aesthetics

• xmin: Left edge of rectangle (required)
• xmax: Right edge of rectangle (required)
• ymin: Bottom edge of rectangle (required)
• ymax: Top edge of rectangle (required)
• fill: Fill color (optional, can be mapped to variable)
• color: Border color (optional)
• group: Grouping variable (optional)

Examples:

>>> # Highlight a region
>>> df = pd.DataFrame({'xmin': [2], 'xmax': [4], 'ymin': [1], 'ymax': [3]})
>>> ggplot(df, aes(xmin='xmin', xmax='xmax', ymin='ymin', ymax='ymax')) + geom_rect()

>>> # Multiple rectangles with fill mapping
>>> df = pd.DataFrame({
...     'xmin': [1, 3], 'xmax': [2, 4],
...     'ymin': [1, 2], 'ymax': [3, 4],
...     'category': ['A', 'B']
... })
>>> ggplot(df, aes(xmin='xmin', xmax='xmax', ymin='ymin', ymax='ymax', fill='category')) + geom_rect()

>>> # Rectangle with border
>>> ggplot(df, aes(xmin='xmin', xmax='xmax', ymin='ymin', ymax='ymax')) + geom_rect(
...     fill='lightblue', color='navy', size=2
... )

>>> # Highlight region on existing plot
>>> highlight = pd.DataFrame({'xmin': [2], 'xmax': [4], 'ymin': [0], 'ymax': [10]})
>>> (ggplot(data, aes(x='x', y='y'))
...  + geom_rect(data=highlight, aes(xmin='xmin', xmax='xmax', ymin='ymin', ymax='ymax'),
...              fill='yellow', alpha=0.3)
...  + geom_point())

Statistical Geoms

ggplotly.geoms.geom_smooth.geom_smooth

Bases: Geom

Geom for drawing smooth lines (regression/LOESS/etc.).

Automatically handles categorical variables for color. Automatically converts 'group' and 'color' columns to categorical if necessary.

Parameters:

Name	Type	Description	Default
method	str	The smoothing method. Options: - 'loess': Custom LOESS with degree-2 polynomials (default, best for R compatibility) - 'lowess': statsmodels lowess with degree-1 (faster) - 'lm': Linear regression	required
span	float	The smoothing span for LOESS. Controls the amount of smoothing. Larger values (closer to 1) produce smoother lines. Default is 2/3 (~0.667) to match R.	required
se	bool	Whether to display confidence interval ribbon. Default is True to match R.	required
level	float	Confidence level for the interval (e.g., 0.95 for 95% CI). Default is 0.95 to match R.	required
fullrange	bool	If True, extend the smooth line to fill the full x-axis range. Default is False (smooth only within data range).	required
n	int	Number of points to evaluate predictions at. Default is 80.	required
color	str	Color of the smooth lines. If a categorical variable is mapped to color, different colors will be assigned.	required
linetype	str	Line type ('solid', 'dash', etc.). Default is 'solid'.	required
alpha	float	Transparency level for the smooth lines. Default is 1.	required
group	str	Grouping variable for the smooth lines.	required
na_rm	bool	If True, remove missing values. Default is False.	required
show_legend	bool	Whether to show in legend. Default is True.	required

Examples:

>>> ggplot(df, aes(x='x', y='y')) + geom_point() + geom_smooth()
>>> ggplot(df, aes(x='x', y='y')) + geom_point() + geom_smooth(method='lm', se=False)
>>> ggplot(df, aes(x='x', y='y')) + geom_point() + geom_smooth(fullrange=True)

ggplotly.geoms.geom_qq.geom_qq

Bases: Geom

Geom for creating Q-Q (quantile-quantile) plots.

Displays sample quantiles against theoretical quantiles from a specified distribution. By default uses the standard normal distribution.

Parameters

distribution : scipy.stats distribution, optional A scipy.stats distribution object with a ppf method. Default is scipy.stats.norm. dparams : dict, optional Additional parameters to pass to the distribution's ppf method. For example, {'df': 5} for a t-distribution. color : str, optional Color of the points. size : float, optional Size of the points. Default is 8. alpha : float, optional Transparency level for the points. Default is 1. shape : str, optional Shape of the points.

Aesthetics

sample : str (required) Column name containing the sample data to compare against the theoretical distribution. color : str, optional Grouping variable for colored points. group : str, optional Grouping variable for separate Q-Q plots.

See Also

geom_qq_line : Reference line for Q-Q plots stat_qq : Underlying stat for quantile computation

Examples

import numpy as np import pandas as pd from scipy import stats

Basic Q-Q plot against normal distribution

df = pd.DataFrame({'values': np.random.randn(100)}) (ggplot(df, aes(sample='values')) ... + geom_qq())

Q-Q plot with reference line

(ggplot(df, aes(sample='values')) ... + geom_qq() ... + geom_qq_line())

Q-Q plot against t-distribution

(ggplot(df, aes(sample='values')) ... + geom_qq(distribution=stats.t, dparams={'df': 5}))

Q-Q plot with color grouping

df = pd.DataFrame({ ... 'values': np.concatenate([np.random.randn(50), np.random.randn(50) + 2]), ... 'group': ['A'] * 50 + ['B'] * 50 ... }) (ggplot(df, aes(sample='values', color='group')) ... + geom_qq())

draw(fig, data=None, row=1, col=1)

Draw the Q-Q plot on the figure.

Overrides base draw to create stat with current mapping (after merge).

ggplotly.geoms.geom_qq_line.geom_qq_line

Bases: Geom

Geom for drawing the Q-Q reference line.

Draws a reference line for Q-Q plots that passes through the points where the sample and theoretical quantiles match at specified probability levels (default: Q1 and Q3, i.e., 25th and 75th percentiles).

Parameters

distribution : scipy.stats distribution, optional A scipy.stats distribution object with a ppf method. Default is scipy.stats.norm. dparams : dict, optional Additional parameters to pass to the distribution's ppf method. line_p : tuple of float, optional Two probability values (between 0 and 1) specifying which quantiles to use for fitting the line. Default is (0.25, 0.75) for Q1 and Q3. color : str, optional Color of the line. Default is 'red'. linetype : str, optional Line style ('solid', 'dash', 'dot', 'dashdot'). Default is 'dashed'. size : float, optional Line width. Default is 1.5. alpha : float, optional Transparency level for the line. Default is 1.

Aesthetics

sample : str (required) Column name containing the sample data.

See Also

geom_qq : Q-Q plot points stat_qq_line : Underlying stat for line computation

Examples

import numpy as np import pandas as pd from scipy import stats

Q-Q plot with default reference line (through Q1 and Q3)

df = pd.DataFrame({'values': np.random.randn(100)}) (ggplot(df, aes(sample='values')) ... + geom_qq() ... + geom_qq_line())

Reference line through 10th and 90th percentiles

(ggplot(df, aes(sample='values')) ... + geom_qq() ... + geom_qq_line(line_p=(0.10, 0.90)))

Custom line styling

(ggplot(df, aes(sample='values')) ... + geom_qq() ... + geom_qq_line(color='blue', linetype='solid', size=2))

Q-Q plot against t-distribution

(ggplot(df, aes(sample='values')) ... + geom_qq(distribution=stats.t, dparams={'df': 5}) ... + geom_qq_line(distribution=stats.t, dparams={'df': 5}))

draw(fig, data=None, row=1, col=1)

Draw the Q-Q reference line on the figure.

Overrides base draw to create stat with current mapping (after merge).

Text and Annotation

ggplotly.geoms.geom_text.geom_text

Bases: Geom

Geom for adding text labels to a plot.

Automatically handles categorical variables for color and text. Automatically converts 'group' and 'color' columns to categorical if necessary.

Parameters:

Name	Type	Description	Default
hjust	float	Horizontal justification (0=left, 0.5=center, 1=right). Default is 0.5 (centered). Maps to Plotly textposition.	required
vjust	float	Vertical justification (0=bottom, 0.5=middle, 1=top). Default is 0.5 (middle). Maps to Plotly textposition.	required
angle	float	Rotation angle in degrees (counter-clockwise). Default is 0.	required
nudge_x	float	Horizontal offset to apply to text position. Default is 0.	required
nudge_y	float	Vertical offset to apply to text position. Default is 0.	required
check_overlap	bool	If True, text that overlaps previous text will not be plotted. Default is False. Note: Limited support in Plotly.	required
size	float	Text size in points. Default is 11.	required
family	str	Font family. Default is None (use Plotly default).	required
fontface	str	Font face ('plain', 'bold', 'italic', 'bold.italic'). Default is 'plain'.	required
parse	bool	If True, parse text labels as LaTeX math expressions. Labels will be rendered using MathJax. Default is False.	required
na_rm	bool	If True, silently remove missing values. Default is False.	required
textposition	str	Direct Plotly textposition override ('top center', 'middle right', etc.). If provided, overrides hjust/vjust.	required
color	str	Color of the text labels.	required
alpha	float	Transparency level for the text labels. Default is 1.	required
group	str	Grouping variable for the text labels.	required

Examples:

>>> ggplot(df, aes(x='x', y='y', label='name')) + geom_text()
>>> ggplot(df, aes(x='x', y='y', label='name')) + geom_text(hjust=0, vjust=1)  # top-left
>>> ggplot(df, aes(x='x', y='y', label='name')) + geom_text(angle=45)
>>> ggplot(df, aes(x='x', y='y', label='name')) + geom_text(nudge_y=0.5)

ggplotly.geoms.geom_label.geom_label

Bases: Geom

Geom for adding text labels with a background box.

Similar to geom_text but draws a rectangle behind the text for better readability, especially when labels overlap with data.

Parameters:

Name	Type	Description	Default
hjust	float	Horizontal justification (0=left, 0.5=center, 1=right). Default is 0.5 (centered).	required
vjust	float	Vertical justification (0=bottom, 0.5=middle, 1=top). Default is 0.5 (middle).	required
nudge_x	float	Horizontal offset to apply to label position. Default is 0.	required
nudge_y	float	Vertical offset to apply to label position. Default is 0.	required
size	float	Text size in points. Default is 11.	required
family	str	Font family. Default is None (use Plotly default).	required
fontface	str	Font face ('plain', 'bold', 'italic', 'bold.italic'). Default is 'plain'.	required
color	str	Text color. Default is 'black'.	required
fill	str	Background fill color. Default is 'white'.	required
alpha	float	Background transparency (0-1). Default is 0.8.	required
label_padding	float	Padding around text in pixels. Default is 4.	required
label_r	float	Border radius in pixels. Default is 2.	required
label_size	float	Border line width. Default is 0.5.	required
parse	bool	If True, parse text labels as LaTeX math expressions. Default is False.	required
na_rm	bool	If True, silently remove missing values. Default is False.	required

Aesthetics

• x: x-axis position (required)
• y: y-axis position (required)
• label: Text to display (required)
• color: Text color (optional)
• fill: Background color (optional)
• group: Grouping variable (optional)

Examples:

>>> # Basic label
>>> ggplot(df, aes(x='x', y='y', label='name')) + geom_label()

>>> # Styled label
>>> ggplot(df, aes(x='x', y='y', label='name')) + geom_label(
...     fill='lightblue', color='navy', size=12
... )

>>> # Labels with nudge to avoid overlapping points
>>> (ggplot(df, aes(x='x', y='y', label='name'))
...  + geom_point()
...  + geom_label(nudge_y=0.5))

>>> # Labels colored by category
>>> ggplot(df, aes(x='x', y='y', label='name', fill='category')) + geom_label()

See Also

geom_text: Text labels without background

Reference Lines

ggplotly.geoms.geom_hline.geom_hline

Bases: Geom

Geom for drawing horizontal reference lines.

__init__(data=None, mapping=None, **params)

Draw horizontal lines at specified y-intercepts.

Parameters

data : float or list of float Y-coordinate(s) for horizontal line(s). Same as yintercept. mapping : aes, optional Aesthetic mappings (typically not used for hline). color : str, default='black' Line color. linetype : str, default='solid' Line style: 'solid', 'dash', 'dot', 'dashdot'. alpha : float, default=1 Transparency (0-1). size : float, default=2 Line width. name : str, optional Legend name.

Examples

geom_hline(data=100) geom_hline(data=[50, 100, 150], color='red', linetype='dash')

ggplotly.geoms.geom_vline.geom_vline

Bases: Geom

Geom for drawing vertical reference lines.

__init__(data=None, mapping=None, **params)

Draw vertical lines at specified x-intercepts.

Parameters

data : float or list of float X-coordinate(s) for vertical line(s). Same as xintercept. mapping : aes, optional Aesthetic mappings (typically not used for vline). color : str, default='black' Line color. linetype : str, default='solid' Line style: 'solid', 'dash', 'dot', 'dashdot'. alpha : float, default=1 Transparency (0-1). size : float, default=2 Line width. name : str, optional Legend name.

Examples

geom_vline(data=5) geom_vline(data=[1, 2, 3], color='red', linetype='dash')

ggplotly.geoms.geom_abline.geom_abline

Bases: Geom

Geom for drawing lines with specified slope and intercept.

__init__(data=None, mapping=None, **params)

Draw lines defined by slope and intercept (y = intercept + slope * x).

Useful for adding regression lines, reference lines, or theoretical relationships to plots.

Parameters

data : DataFrame, optional Data for the geom (overrides plot data). mapping : aes, optional Aesthetic mappings (typically not used for abline). slope : float or list, default=1 Slope(s) of the line(s). intercept : float or list, default=0 Y-intercept(s) of the line(s). color : str, default='black' Line color. linetype : str, default='solid' Line style: 'solid', 'dash', 'dot', 'dashdot'. size : float, default=1 Line width. alpha : float, default=1 Transparency (0-1). name : str, optional Name for the legend.

Examples

geom_abline(slope=1, intercept=0) # y = x line geom_abline(slope=0.5, intercept=2, color='red', linetype='dash') geom_abline(slope=[1, 2], intercept=[0, -1]) # multiple lines

Segments and Error Bars

ggplotly.geoms.geom_segment.geom_segment

Bases: Geom

Geom for drawing line segments.

Automatically handles categorical variables for color. Automatically converts 'group' and 'color' columns to categorical if necessary.

Parameters:

Name	Type	Description	Default
xend	float	End x-coordinate of the line segment.	required
yend	float	End y-coordinate of the line segment.	required
color	str	Color of the segment lines.	required
colour	str	Alias for color (British spelling).	required
size	float	Line width. Default is 2.	required
linewidth	float	Alias for size (ggplot2 3.4+ compatibility).	required
linetype	str	Line style ('solid', 'dash', etc.). Default is 'solid'.	required
alpha	float	Transparency level for the segments. Default is 1.	required
group	str	Grouping variable for the segments.	required
arrow	bool	If True, adds an arrowhead at the end of the segment. Default is False.	required
arrow_size	int	Size of the arrowhead. Default is 15.	required
na_rm	bool	If True, remove missing values. Default is False.	required
show_legend	bool	Whether to show in legend. Default is True.	required

Examples:

>>> ggplot(df, aes(x='x', y='y', xend='xend', yend='yend')) + geom_segment()
>>> ggplot(df, aes(x='x', y='y', xend='xend', yend='yend')) + geom_segment(arrow=True)

ggplotly.geoms.geom_errorbar.geom_errorbar

Bases: Geom

Geom for drawing error bars.

Automatically handles categorical variables for color and fill. Automatically converts 'group' and 'fill' columns to categorical if necessary.

Parameters:

Name	Type	Description	Default
ymin	float	Minimum y value for the error bar.	required
ymax	float	Maximum y value for the error bar.	required
color	str	Color of the error bars.	required
alpha	float	Transparency level for the error bars. Default is 1.	required
linetype	str	Line style of the error bars ('solid', 'dash', etc.).	required
width	float	Width of the error bar caps in pixels. Default is 4.	required
group	str	Grouping variable for the error bars.	required

Step and Range Geoms

ggplotly.geoms.geom_step.geom_step

Bases: Geom

Geom for drawing step plots.

Automatically handles categorical variables for color. Automatically converts 'group' and 'color' columns to categorical if necessary.

Parameters:

Name	Type	Description	Default
color	str	Color of the steps.	required
colour	str	Alias for color (British spelling).	required
size	float	Line width. Default is 2.	required
linewidth	float	Alias for size (ggplot2 3.4+ compatibility).	required
linetype	str	Line style ('solid', 'dash', etc.). Default is 'solid'.	required
alpha	float	Transparency level for the steps. Default is 1.	required
group	str	Grouping variable for the steps.	required
stat	str	The statistical transformation to use. Default is 'identity'. Use 'ecdf' for empirical cumulative distribution function.	required
na_rm	bool	If True, remove missing values. Default is False.	required
show_legend	bool	Whether to show in legend. Default is True.	required

Examples:

>>> ggplot(df, aes(x='x', y='y')) + geom_step()
>>> ggplot(df, aes(x='x')) + geom_step(stat='ecdf')

ggplotly.geoms.geom_range.geom_range

Bases: Geom

Geom for drawing 5-year range plots with historical context.

Shows historical min/max as a ribbon, historical average as a dotted line, prior year as a blue line, and current year as a red line. The historical statistics (min, max, avg) are calculated from the 5 years prior to the current year (excluding current year).

Parameters:

Name	Type	Description	Default
years	int	Number of historical years to include in range calculation. Default is 5.	required
freq	str	Pandas frequency string for resampling. Examples: - 'D': Daily - 'W': Weekly (Sunday end) - 'W-Fri': Weekly ending Friday - 'ME': Month end - 'MS': Month start - 'QE': Quarter end - '2W': Bi-weekly - None: Auto-detect based on data	required
current_year	int	Year to treat as "current". Default is the max year in the data.	required
show_years	list	Additional specific years to display as separate lines. Each will get a unique color.	required
ribbon_color	str	Color for the historical range ribbon. Default is 'gray'.	required
ribbon_alpha	float	Transparency for ribbon. Default is 0.3.	required
avg_color	str	Color for average line. Default is 'black'.	required
avg_linetype	str	Line style for average. Default is 'dot'.	required
prior_color	str	Color for prior year line. Default is 'blue'.	required
current_color	str	Color for current year line. Default is 'red'.	required
show_legend	bool	Whether to show legend. Default is True.	required

Aesthetics

• x: Date column (must be datetime or date type)
• y: Value column

Examples:

Basic 5-year range plot

ggplot(df, aes(x='date', y='value')) + geom_range()

With weekly frequency ending Friday

ggplot(df, aes(x='date', y='value')) + geom_range(freq='W-Fri')

Show specific additional years

ggplot(df, aes(x='date', y='value')) + geom_range(show_years=[2019, 2020])

Custom colors

ggplot(df, aes(x='date', y='value')) + geom_range( current_color='green', prior_color='orange' )

__init__(data=None, mapping=None, **params)

Initialize the range geom.

Parameters:

Name	Type	Description	Default
data	DataFrame	Data for this geom.	None
mapping	aes	Aesthetic mappings.	None
**params		Additional parameters (years, freq, colors, etc.).	{}

Scatter Variants

ggplotly.geoms.geom_jitter.geom_jitter

Bases: Geom

Geom for drawing jittered point plots.

Jittering adds a small amount of random noise to the position of each point, which is useful for visualizing overlapping points in categorical data.

Parameters:

Name	Type	Description	Default
width	float	Amount of horizontal jitter. Default is 0.2. The jitter is added in both directions, so the total spread is 2*width.	required
height	float	Amount of vertical jitter. Default is 0. The jitter is added in both directions, so the total spread is 2*height.	required
color	str	Color of the points. If a column name, maps categories to colors.	required
size	int	Size of the points. Default is 8.	required
alpha	float	Transparency level for the points. Default is 1.	required
shape	str	Shape of the points. If a column name, maps categories to shapes.	required
seed	int	Random seed for reproducibility. Default is None.	required
group	str	Grouping variable for the points.	required

Examples:

>>> ggplot(df, aes(x='category', y='value')) + geom_jitter()
>>> ggplot(df, aes(x='category', y='value', color='group')) + geom_jitter(width=0.3)

__init__(data=None, mapping=None, **params)

Initialize the jitter geom.

Parameters:

Name	Type	Description	Default
data	DataFrame	Data for this geom.	None
mapping	aes	Aesthetic mappings.	None
**params		Additional parameters (width, height, seed, etc.).	{}

ggplotly.geoms.geom_rug.geom_rug

Bases: Geom

Geom for drawing rug plots (marginal tick marks on axes).

__init__(data=None, mapping=None, **params)

Draw rug plots (marginal tick marks) along axes.

Rug plots display individual data points as tick marks along the axes, useful for showing the marginal distribution of data in scatter plots.

Parameters

data : DataFrame, optional Data for the geom (overrides plot data). mapping : aes, optional Aesthetic mappings. Required: x and/or y. sides : str, default='bl' Which sides to draw rugs on: - 'b' = bottom (x-axis) - 't' = top (x-axis at top) - 'l' = left (y-axis) - 'r' = right (y-axis at right) Can combine, e.g., 'bl' for bottom and left. length : float, default=0.03 Length of rug ticks as fraction of plot area. color : str, default='black' Color of the rug lines. alpha : float, default=0.5 Transparency (0-1). size : float, default=1 Line width of the rug ticks.

Examples

geom_rug() # default: bottom and left rugs geom_rug(sides='b', color='red') # bottom only

Contour Geoms

ggplotly.geoms.geom_contour.geom_contour

Bases: Geom

Geom for drawing contour lines from 2D data.

__init__(data=None, mapping=None, **params)

Draw contour lines from 2D data.

Can be used in two ways: 1. With x and y aesthetics: Computes 2D kernel density estimation 2. With x, y, and z aesthetics: Draws contours from gridded z values

Parameters

data : DataFrame, optional Data for the geom (overrides plot data). mapping : aes, optional Aesthetic mappings. Required: x, y. Optional: z. bins : int, default=10 Number of contour levels. color : str, optional Color of contour lines. Default uses theme colors. size : float, default=1 Line width of contours. alpha : float, default=1 Transparency (0-1). linetype : str, default='solid' Line style: 'solid', 'dash', 'dot'. gridsize : int, default=100 Grid resolution for KDE computation. label : bool, default=False Whether to show contour labels.

Examples

geom_contour() # 2D density contours geom_contour(bins=5, color='blue')

ggplotly.geoms.geom_contour_filled.geom_contour_filled

Bases: Geom

Geom for drawing filled contours from 2D data.

__init__(data=None, mapping=None, **params)

Draw filled contours from 2D data.

Can be used in two ways: 1. With x and y aesthetics: Computes 2D kernel density estimation 2. With x, y, and z aesthetics: Draws filled contours from gridded z values

Parameters

data : DataFrame, optional Data for the geom (overrides plot data). mapping : aes, optional Aesthetic mappings. Required: x, y. Optional: z. bins : int, default=10 Number of contour levels. palette : str, default='Viridis' Color palette name. Options: 'Viridis', 'Plasma', 'Inferno', 'Magma', 'Blues', 'Greens', 'Reds', etc. alpha : float, default=0.8 Transparency (0-1). gridsize : int, default=100 Grid resolution for KDE computation. label : bool, default=False Whether to show contour labels. show_colorbar : bool, default=True Whether to show the colorbar.

Examples

geom_contour_filled() # 2D density filled contours geom_contour_filled(bins=15, palette='Plasma')

Map and Geo Geoms

ggplotly.geoms.geom_map.geom_map

Bases: Geom

Geom for drawing geographic maps (base maps, choropleths, and GeoJSON/sf).

__init__(data=None, mapping=None, **params)

Create a geographic map layer.

Supports base maps, choropleths, and GeoJSON/sf-style rendering.

Parameters

data : DataFrame, optional Data for the geom (overrides plot data). mapping : aes, optional Aesthetic mappings. Key aesthetics: - map_id: Region identifiers (for choropleth) - fill: Values to map to fill color (triggers choropleth) map : DataFrame, optional Map region data with 'id' column. Use map_data('state') or map_data('world'). geojson : dict or GeoDataFrame, optional GeoJSON dict or GeoDataFrame for sf-like rendering. featureidkey : str, default='properties.id' Path to feature ID in GeoJSON properties. map_type : str, default='state' Map scope: 'state', 'usa', 'world', 'europe', 'asia', 'africa', etc. region : str, optional Region format: 'USA-states', 'ISO-3', 'country names', 'geojson-id'. color : str, default='white' Border color. linewidth : float, default=0.5 Border line width. alpha : float, default=1 Transparency (0-1). palette : str, default='Viridis' Color palette for fill. projection : str, optional Map projection: 'albers usa', 'mercator', 'natural earth', etc. landcolor : str, optional Land area color. oceancolor : str, optional Ocean color. lakecolor : str, optional Lake color. bgcolor : str, optional Background color. fitbounds : str, optional How to fit bounds: 'locations', 'geojson', False.

Examples

Base map with points

ggplot(cities, aes(x='lon', y='lat')) + geom_map(map_type='usa') + geom_point()

Choropleth

ggplot(data, aes(map_id='state', fill='pop')) + geom_map(map=map_data('state'))

ggplotly.geoms.geom_map.geom_sf = geom_map module-attribute

3D Geoms

ggplotly.geoms.geom_point_3d.geom_point_3d

Bases: Geom

Geom for drawing 3D scatter plots.

Creates interactive 3D scatter plots using Plotly's Scatter3d trace. Supports color, size, and shape aesthetics for categorical grouping.

Parameters:

Name	Type	Description	Default
x	str	Column name for x-axis (via aes mapping).	required
y	str	Column name for y-axis (via aes mapping).	required
z	str	Column name for z-axis (via aes mapping).	required
color	str	Color of the points. If a column name, maps categories to colors.	required
size	int	Size of the points. Default is 6.	required
alpha	float	Transparency level for the points. Default is 1.	required
shape	str	Shape of the points. If a column name, maps categories to shapes. Literal values can be any Plotly 3D marker symbol (e.g., 'circle', 'square', 'diamond', 'cross', 'x', 'circle-open', 'square-open', etc.)	required
group	str	Grouping variable for the points.	required

Examples:

>>> # Basic 3D scatter plot
>>> ggplot(df, aes(x='x', y='y', z='z')) + geom_point_3d()

>>> # 3D scatter with color grouping
>>> ggplot(df, aes(x='x', y='y', z='z', color='category')) + geom_point_3d()

>>> # 3D scatter with custom size and alpha
>>> ggplot(df, aes(x='x', y='y', z='z')) + geom_point_3d(size=10, alpha=0.7)

ggplotly.geoms.geom_surface.geom_surface

Bases: Geom

Geom for drawing 3D surface plots.

__init__(data=None, mapping=None, **params)

Create a 3D surface plot.

Visualizes functions z = f(x, y) or grid data as continuous surfaces. Data can be long format (x, y, z columns) or grid format.

Parameters

data : DataFrame, optional Data for the geom (overrides plot data). mapping : aes, optional Aesthetic mappings. Required: x, y, z. colorscale : str, default='Viridis' Plotly colorscale: 'Viridis', 'Plasma', 'Inferno', 'Blues', 'RdBu', etc. alpha : float, default=1 Surface opacity (0-1). showscale : bool, default=True Show the colorbar. contours : dict, optional Contour settings for x, y, z projections. hidesurface : bool, default=False Hide surface and show only contours. reversescale : bool, default=False Reverse the colorscale. lighting : dict, optional Lighting settings for 3D effect.

Examples

Basic surface

ggplot(df, aes(x='x', y='y', z='z')) + geom_surface()

Custom colorscale

ggplot(df, aes(x='x', y='y', z='z')) + geom_surface(colorscale='Plasma')

ggplotly.geoms.geom_surface.geom_wireframe

Bases: Geom

Geom for drawing 3D wireframe plots.

Creates a wireframe (mesh) representation of a surface using Plotly's Scatter3d with lines connecting grid points.

Parameters:

Name	Type	Description	Default
x	str	Column name for x-axis values (via aes mapping).	required
y	str	Column name for y-axis values (via aes mapping).	required
z	str	Column name for z-axis values (via aes mapping).	required
color	str	Wire color. Default is '#1f77b4'.	required
linewidth	float	Width of wireframe lines. Default is 1.	required
alpha	float	Line opacity. Default is 1.	required

Examples:

>>> # Basic wireframe
>>> ggplot(df, aes(x='x', y='y', z='z')) + geom_wireframe()

>>> # Wireframe with custom color
>>> ggplot(df, aes(x='x', y='y', z='z')) + geom_wireframe(color='red', linewidth=2)

Financial Geoms

ggplotly.geoms.geom_candlestick.geom_candlestick

Bases: Geom

Geom for drawing candlestick charts for financial OHLC data.

__init__(data=None, mapping=None, **params)

Create a candlestick chart for financial data.

Visualizes price movements with open, high, low, close (OHLC) values.

Parameters

data : DataFrame, optional Data for the geom (overrides plot data). mapping : aes, optional Aesthetic mappings. Required: x, open, high, low, close. increasing_color : str, default='#26A69A' Color for candles where close > open (green). decreasing_color : str, default='#EF5350' Color for candles where close < open (red). increasing_line_color : str, optional Wick color for increasing candles. Default same as increasing_color. decreasing_line_color : str, optional Wick color for decreasing candles. Default same as decreasing_color. line_width : float, default=1 Width of wick lines. whisker_width : float, default=0 Width of whisker lines (0-1). 0 = same as body. opacity : float, default=1 Candlestick opacity (0-1). name : str, default='Candlestick' Name for legend. showlegend : bool, default=True Show in legend.

Examples

Basic candlestick

ggplot(df, aes(x='date', open='open', high='high', low='low', close='close')) + geom_candlestick()

Custom colors

ggplot(df, aes(x='date', open='open', high='high', low='low', close='close')) + geom_candlestick( ... increasing_color='#2196F3', decreasing_color='#FF9800')

ggplotly.geoms.geom_candlestick.geom_ohlc

Bases: Geom

Geom for drawing OHLC (Open-High-Low-Close) bar charts.

__init__(data=None, mapping=None, **params)

Draw OHLC bar charts for financial data.

Similar to candlestick but uses bars instead of filled bodies. The left tick shows the opening price, the right tick shows the closing price, and the vertical line shows the high-low range.

Parameters

data : DataFrame, optional Data for the geom (overrides plot data). mapping : aes, optional Aesthetic mappings. Required: x, open, high, low, close. increasing_color : str, default='#26A69A' Color for bars where close > open (green). decreasing_color : str, default='#EF5350' Color for bars where close < open (red). line_width : float, default=2 Width of the lines. tickwidth : float, default=0.05 Width of open/close ticks. opacity : float, default=1 Opacity of bars (0-1). name : str, default='OHLC' Name for legend. showlegend : bool, default=True Whether to show in legend.

Examples

ggplot(df, aes(x='date', open='open', high='high', low='low', close='close')) + geom_ohlc() geom_ohlc(increasing_color='blue', decreasing_color='orange')

ggplotly.geoms.geom_waterfall.geom_waterfall

Bases: Geom

Geom for creating waterfall charts.

Waterfall charts show how an initial value is affected by a series of positive or negative values, culminating in a final value. They are commonly used to visualize financial statements, budget changes, or any cumulative effect analysis.

Parameters

data : DataFrame, optional Data for the geom (overrides plot data). mapping : aes, optional Aesthetic mappings. Required: x, y. Optional: measure (to specify 'relative', 'total', or 'absolute'). increasing_color : str, default='#2ca02c' Color for increasing (positive) values. decreasing_color : str, default='#d62728' Color for decreasing (negative) values. total_color : str, default='#1f77b4' Color for total/absolute values. connector_color : str, default='rgba(128, 128, 128, 0.5)' Color for connector lines between bars. connector_width : float, default=1 Width of connector lines. connector_visible : bool, default=True Whether to show connector lines. text_position : str, default='outside' Position of value labels: 'inside', 'outside', 'auto', 'none'. text_format : str, optional Format string for text labels (e.g., '.2f', ',.0f'). orientation : str, default='v' Orientation: 'v' (vertical) or 'h' (horizontal). name : str, default='Waterfall' Name for legend.

Aesthetics

x : str (required) Column containing category labels. y : str (required) Column containing values. measure : str, optional Column specifying the measure type for each bar: - 'relative': Value is added to running total (default behavior) - 'total': Bar shows running total up to this point - 'absolute': Bar shows absolute value (resets running total)

Examples

import pandas as pd from ggplotly import ggplot, aes, geom_waterfall

Basic waterfall chart

df = pd.DataFrame({ ... 'category': ['Start', 'Sales', 'Returns', 'Expenses', 'End'], ... 'value': [100, 50, -20, -30, 0], ... 'measure': ['absolute', 'relative', 'relative', 'relative', 'total'] ... }) (ggplot(df, aes(x='category', y='value', measure='measure')) ... + geom_waterfall())

Simple waterfall (auto-detect totals by value=0 at start/end)

df = pd.DataFrame({ ... 'category': ['Q1', 'Q2', 'Q3', 'Q4'], ... 'value': [100, 50, -30, 20] ... }) (ggplot(df, aes(x='category', y='value')) ... + geom_waterfall())

Financial statement waterfall

df = pd.DataFrame({ ... 'item': ['Revenue', 'COGS', 'Gross Profit', 'OpEx', 'Net Income'], ... 'amount': [1000, -400, 0, -200, 0], ... 'type': ['absolute', 'relative', 'total', 'relative', 'total'] ... }) (ggplot(df, aes(x='item', y='amount', measure='type')) ... + geom_waterfall())

Notes

If no 'measure' aesthetic is provided, all values are treated as relative changes from the previous value. Use the measure aesthetic to explicitly mark starting values ('absolute') and subtotals ('total').

Time Series Geoms

ggplotly.geoms.geom_stl.geom_stl

Bases: Geom

Geom for displaying STL decomposition as a 4-panel chart.

Performs STL (Seasonal-Trend decomposition using Loess) and displays the Observed, Trend, Seasonal, and Residual components as stacked line plots with shared x-axis.

Uses stat_stl internally for the decomposition.

Parameters

data : DataFrame, optional Data for the geom (overrides plot data). mapping : aes, optional Aesthetic mappings. Requires x and y. period : int Seasonal period. Required unless data has DatetimeIndex with frequency. seasonal : int, optional Length of the seasonal smoother. Must be odd. Default is 7. trend : int, optional Length of the trend smoother. Default is auto-calculated. robust : bool, optional Use robust fitting to downweight outliers. Default is False. color : str, optional Line color. Default is 'steelblue'. line_width : float, optional Width of lines. Default is 1.5. rangeslider : bool, optional Whether to show a range slider on the bottom subplot. Default is True.

Examples

Basic STL decomposition

ggplot(df, aes(x='date', y='value')) + geom_stl(period=12)

Robust decomposition for data with outliers

ggplot(df, aes(x='date', y='value')) + geom_stl(period=12, robust=True)

Styled decomposition

ggplot(df, aes(x='date', y='value')) + geom_stl(period=12, color='coral')

before_add()

Called before the geom is added to the plot.

For geom_stl, we need to signal that this geom will create its own subplot structure and should bypass normal faceting.

ggplotly.geoms.geom_acf.geom_acf

Bases: Geom

Geom for displaying Autocorrelation Function (ACF) plots.

Computes and displays the autocorrelation at each lag as vertical bars with horizontal confidence interval bands.

Parameters

data : DataFrame, optional Data for the geom (overrides plot data). mapping : aes, optional Aesthetic mappings. Requires y (the time series values). nlags : int, optional Number of lags to compute. Default is 40. alpha : float, optional Significance level for confidence intervals. Default is 0.05. color : str, optional Color for the bars. Default is 'steelblue'. ci_color : str, optional Color for confidence interval bands. Default is 'lightblue'. ci_alpha : float, optional Transparency of confidence bands. Default is 0.3. bar_width : float, optional Width of the bars. Default is 0.3.

Examples

Basic ACF plot

ggplot(df, aes(y='value')) + geom_acf()

Custom number of lags

ggplot(df, aes(y='value')) + geom_acf(nlags=20)

Styled ACF

ggplot(df, aes(y='value')) + geom_acf(color='coral', nlags=30)

ggplotly.geoms.geom_pacf.geom_pacf

Bases: Geom

Geom for displaying Partial Autocorrelation Function (PACF) plots.

Computes and displays the partial autocorrelation at each lag as vertical bars with horizontal confidence interval bands.

Parameters

data : DataFrame, optional Data for the geom (overrides plot data). mapping : aes, optional Aesthetic mappings. Requires y (the time series values). nlags : int, optional Number of lags to compute. Default is 40. alpha : float, optional Significance level for confidence intervals. Default is 0.05. method : str, optional Method for computing PACF. Options: 'ywm' (Yule-Walker with MLE), 'yw' (Yule-Walker), 'ols' (OLS), 'ld' (Levinson-Durbin). Default is 'ywm'. color : str, optional Color for the bars. Default is 'steelblue'. ci_color : str, optional Color for confidence interval bands. Default is 'lightblue'. ci_alpha : float, optional Transparency of confidence bands. Default is 0.3. bar_width : float, optional Width of the bars. Default is 0.3.

Examples

Basic PACF plot

ggplot(df, aes(y='value')) + geom_pacf()

Custom number of lags

ggplot(df, aes(y='value')) + geom_pacf(nlags=20)

Styled PACF

ggplot(df, aes(y='value')) + geom_pacf(color='coral', nlags=30)

Network Geoms

ggplotly.geoms.geom_edgebundle.geom_edgebundle

Bases: Geom

Bundled edges for graph visualization using force-directed edge bundling.

__init__(mapping=None, data=None, graph=None, weight=None, K=1.0, E=1.0, C=6, P=1, S=0.04, P_rate=2, I=50, I_rate=2 / 3, compatibility_threshold=0.6, color='#9d0191', alpha=0.8, linewidth=0.5, show_highlight=True, highlight_color='white', highlight_alpha=0.3, highlight_width=0.1, show_nodes=True, node_color='white', node_size=3, node_alpha=1.0, verbose=True, **kwargs)

Create bundled edges for graph visualization.

Applies force-directed edge bundling to create smooth, bundled paths between nodes, reducing visual clutter in dense graphs. Automatically detects map context and uses Scattergeo for geographic rendering.

Parameters

mapping : aes, optional Aesthetic mappings. Required: x, y (start), xend, yend (end). Optional: weight (edge weight for bundling attraction). Not needed when using graph parameter. data : DataFrame, optional Data to use for this geom (overrides plot data). graph : igraph.Graph, optional An igraph Graph object with vertex coordinate attributes. When provided, edges and nodes are extracted automatically. Vertices must have 'longitude'/'lon'/'x' and 'latitude'/'lat'/'y'. Edge 'weight' attribute is used automatically if present. weight : str, optional Column name or igraph edge attribute for edge weights. Heavier edges attract compatible edges more strongly during bundling, causing lighter edges to bundle toward heavy routes. Weights are normalized to [0.5, 1.5] range internally. K : float, default=1.0 Spring constant controlling edge stiffness (resists bundling). E : float, default=1.0 Electrostatic constant controlling bundling attraction strength. Higher values increase bundling, lower values decrease it. C : int, default=6 Number of cycles. More = smoother curves. P : int, default=1 Initial edge subdivisions. S : float, default=0.04 Initial step size for force simulation. P_rate : int, default=2 Subdivision increase rate per cycle. I : int, default=50 Initial iterations per cycle. I_rate : float, default=2/3 Iteration decrease rate per cycle. compatibility_threshold : float, default=0.6 Min compatibility (0-1). Higher = more selective bundling. color : str, default='#9d0191' Edge color. alpha : float, default=0.8 Edge transparency (0-1). linewidth : float, default=0.5 Edge line width. show_highlight : bool, default=True Add highlight lines on top of edges. highlight_color : str, default='white' Highlight line color. highlight_alpha : float, default=0.3 Highlight transparency (0-1). highlight_width : float, default=0.1 Highlight line width. show_nodes : bool, default=True Show nodes when using igraph input. node_color : str, default='white' Node marker color. node_size : float, default=3 Node marker size. node_alpha : float, default=1.0 Node transparency (0-1). verbose : bool, default=True Print progress messages.

Examples

From igraph (auto-detects 'weight' edge attribute)

g = data('us_flights') ggplot() + geom_map(map_type='usa') + geom_edgebundle(graph=g)

From igraph with explicit weight attribute

ggplot() + geom_map(map_type='usa') + geom_edgebundle(graph=g, weight='passengers')

From DataFrame

(ggplot(edges_df, aes(x='x', y='y', xend='xend', yend='yend')) ... + geom_edgebundle(compatibility_threshold=0.6))

From DataFrame with weights

(ggplot(edges_df, aes(x='x', y='y', xend='xend', yend='yend', weight='traffic')) ... + geom_edgebundle())

ggplotly.geoms.geom_searoute.geom_searoute

Bases: Geom

Sea routes for maritime visualization using the searoute package.

__init__(mapping=None, data=None, units='km', speed_knot=None, append_orig_dest=False, restrictions=None, include_ports=False, port_params=None, color='#ff6b35', alpha=0.6, linewidth=0.8, show_highlight=True, highlight_color='white', highlight_alpha=0.2, highlight_width=0.15, show_ports=True, port_color='#00ff88', port_size=5, port_alpha=0.9, verbose=False, **kwargs)

Create sea routes for maritime visualization.

Uses the searoute package to calculate realistic shipping routes between ports. Routes follow actual maritime lanes and avoid land. Supports overlap highlighting similar to geom_edgebundle.

Note: This is for visualization purposes only, not for actual maritime navigation or routing.

Parameters

mapping : aes, optional Aesthetic mappings. Required: x, y (origin lon/lat), xend, yend (destination lon/lat). data : DataFrame, optional Data containing origin and destination coordinates. Each row represents one route. units : str, default='km' Distance units. Options: 'km', 'm', 'mi', 'naut' (nautical miles), 'ft', 'in', 'deg', 'rad', 'yd'. speed_knot : float, optional If provided, calculates estimated duration based on this speed. append_orig_dest : bool, default=False Whether to append origin and destination to the route path. restrictions : list, optional List of passages to avoid. Options include: 'northwest', 'suez', 'panama', 'malacca', 'bering', etc. include_ports : bool, default=False Whether to include port information in the route calculation. port_params : dict, optional Additional parameters for port selection. color : str, default='#ff6b35' Route line color. alpha : float, default=0.6 Route line transparency (0-1). linewidth : float, default=0.8 Route line width. show_highlight : bool, default=True Add highlight lines on top of routes to emphasize overlaps. highlight_color : str, default='white' Highlight line color. highlight_alpha : float, default=0.2 Highlight transparency (0-1). highlight_width : float, default=0.15 Highlight line width. show_ports : bool, default=True Show origin and destination port markers. port_color : str, default='#00ff88' Port marker color. port_size : float, default=5 Port marker size. port_alpha : float, default=0.9 Port marker transparency (0-1). verbose : bool, default=False Print progress messages and route statistics.

Examples

Basic sea route visualization

routes = pd.DataFrame({ ... 'x': [0.35, -74.01], # origin longitudes ... 'y': [50.06, 40.71], # origin latitudes ... 'xend': [117.42, 1.29], # destination longitudes ... 'yend': [39.37, 103.85] # destination latitudes ... }) (ggplot(routes, aes(x='x', y='y', xend='xend', yend='yend')) ... + geom_map(map_type='world') ... + geom_searoute())

With custom styling and no Suez Canal

(ggplot(routes, aes(x='x', y='y', xend='xend', yend='yend')) ... + geom_map(map_type='world') ... + geom_searoute( ... restrictions=['suez'], ... color='steelblue', ... linewidth=1.0, ... highlight_color='yellow' ... ))

Flow Geoms

ggplotly.geoms.geom_sankey.geom_sankey

Bases: Geom

Geom for creating Sankey diagrams.

Sankey diagrams visualize flows between nodes, where the width of each link is proportional to the flow quantity. This is useful for showing how values flow from one set of categories to another.

Parameters

data : DataFrame, optional Data for the geom (overrides plot data). mapping : aes, optional Aesthetic mappings. Required: source, target, value. Optional: node_label (for custom node labels). node_pad : float, default=15 Padding between nodes. node_thickness : float, default=20 Thickness of nodes. node_color : str or list, optional Color(s) for nodes. Can be a single color or list of colors. link_color : str, optional Color for links. If not specified, uses source node color with alpha. link_alpha : float, default=0.4 Transparency of links (0-1). arrangement : str, default='snap' Node arrangement: 'snap', 'perpendicular', 'freeform', 'fixed'. orientation : str, default='h' Orientation: 'h' (horizontal) or 'v' (vertical). valueformat : str, default='.0f' Format string for values in hover. name : str, default='Sankey' Name for the diagram.

Aesthetics

source : str (required) Column containing source node names/IDs. target : str (required) Column containing target node names/IDs. value : str (required) Column containing flow values/weights. node_label : str, optional Column containing custom node labels.

Examples

import pandas as pd from ggplotly import ggplot, aes, geom_sankey

Basic Sankey diagram

df = pd.DataFrame({ ... 'source': ['A', 'A', 'B', 'B'], ... 'target': ['X', 'Y', 'X', 'Y'], ... 'value': [10, 20, 15, 25] ... }) (ggplot(df, aes(source='source', target='target', value='value')) ... + geom_sankey())

With custom colors

(ggplot(df, aes(source='source', target='target', value='value')) ... + geom_sankey(node_color=['#1f77b4', '#ff7f0e', '#2ca02c', '#d62728']))

Multi-stage Sankey (long format)

df = pd.DataFrame({ ... 'source': ['Budget', 'Budget', 'Sales', 'Sales', 'Marketing', 'Marketing'], ... 'target': ['Sales', 'Marketing', 'Revenue', 'Costs', 'Revenue', 'Costs'], ... 'value': [100, 50, 80, 20, 40, 10] ... }) (ggplot(df, aes(source='source', target='target', value='value')) ... + geom_sankey())

See Also

geom_edgebundle : For circular flow visualizations.

Notes

Data should be in "edge list" format with source, target, and value columns. Each row represents a flow from source to target with the given value.