Guides API Reference¶
Guides help readers interpret the visual encodings in a plot (legends, colorbars, annotations).
Labels¶
ggplotly.guides.labs(**kwargs)
¶
Legend Guides¶
ggplotly.guides.guides(**kwargs)
¶
Control guide (legend/colorbar) display for aesthetics.
Parameters¶
**kwargs Aesthetic-guide mappings. Keys are aesthetic names (color, fill, shape, etc.) Values can be:
- 'none' or False: Hide the guide
- guide_legend(...): Configure legend appearance
- guide_colorbar(...): Configure colorbar appearance
Returns¶
Guides A Guides object that can be added to ggplot.
Examples¶
from ggplotly import ggplot, aes, geom_point, guides, guide_legend, guide_colorbar, data mpg = data('mpg') diamonds = data('diamonds')
Hide color legend¶
ggplot(mpg, aes(x='displ', y='hwy', color='class')) + geom_point() + guides(color='none')
Customize legend with title and columns¶
ggplot(mpg, aes(x='displ', y='hwy', color='class')) + geom_point() + \ ... guides(color=guide_legend(title='Vehicle Class', ncol=2))
Customize colorbar direction¶
ggplot(diamonds.head(1000), aes(x='carat', y='price', color='depth')) + geom_point() + \ ... guides(color=guide_colorbar(direction='horizontal'))
ggplotly.guides.guide_legend
¶
Configure legend appearance for discrete scales.
__init__(title=None, title_position='top', direction='vertical', nrow=None, ncol=None, byrow=False, reverse=False, override_aes=None)
¶
Configure legend appearance for discrete scales.
Parameters¶
title : str, optional Legend title. Use None to suppress title. title_position : str, default='top' Position of title ('top', 'left', 'right'). direction : str, default='vertical' Direction of legend keys ('horizontal', 'vertical'). nrow : int, optional Number of rows for legend keys. ncol : int, optional Number of columns for legend keys. byrow : bool, default=False If True, fill by row. Default is False (fill by column). reverse : bool, default=False If True, reverse the order of keys. override_aes : dict, optional Override aesthetic properties in legend.
Examples¶
from ggplotly import ggplot, aes, geom_point, guides, guide_legend, data mpg = data('mpg')
Customize color legend with title and columns¶
ggplot(mpg, aes(x='displ', y='hwy', color='class')) + geom_point() + \ ... guides(color=guide_legend(title='Vehicle Class', ncol=2))
Reverse legend order¶
ggplot(mpg, aes(x='displ', y='hwy', color='drv')) + geom_point() + \ ... guides(color=guide_legend(reverse=True))
ggplotly.guides.guide_colorbar
¶
Configure colorbar appearance for continuous scales.
__init__(title=None, title_position='top', direction='vertical', barwidth=None, barheight=None, nbin=300, raster=True, ticks=True, draw_ulim=True, draw_llim=True, reverse=False)
¶
Configure colorbar appearance for continuous scales.
Parameters¶
title : str, optional Colorbar title. Use None to suppress title. title_position : str, default='top' Position of title ('top', 'bottom', 'left', 'right'). direction : str, default='vertical' Direction of colorbar ('horizontal', 'vertical'). barwidth : float, optional Width of the colorbar. barheight : float, optional Height of the colorbar. nbin : int, default=300 Number of bins for colorbar. raster : bool, default=True If True, render as raster. ticks : bool, default=True If True, show tick marks. draw_ulim : bool, default=True If True, draw upper limit. draw_llim : bool, default=True If True, draw lower limit. reverse : bool, default=False If True, reverse colorbar direction.
Examples¶
from ggplotly import ggplot, aes, geom_point, guides, guide_colorbar, data diamonds = data('diamonds')
Horizontal colorbar with custom title¶
ggplot(diamonds.head(1000), aes(x='carat', y='price', color='depth')) + geom_point() + \ ... guides(color=guide_colorbar(title='Depth %', direction='horizontal'))
Customize colorbar width¶
ggplot(diamonds.head(1000), aes(x='carat', y='price', color='depth')) + geom_point() + \ ... guides(color=guide_colorbar(barwidth=20))
Annotations¶
ggplotly.guides.annotate(geom, **kwargs)
¶
Create an annotation to add to a plot.
Parameters¶
geom : str Type of annotation ('text', 'label', 'segment', 'rect', 'point', 'curve'). **kwargs Annotation parameters (x, y, label, color, etc.).
Returns¶
Annotate An Annotate object.
Examples¶
from ggplotly import ggplot, aes, geom_point, annotate, data mpg = data('mpg')
Text annotation¶
ggplot(mpg, aes(x='displ', y='hwy')) + geom_point() + \ ... annotate('text', x=5, y=40, label='Outliers')
Rectangle highlight¶
ggplot(mpg, aes(x='displ', y='hwy')) + geom_point() + \ ... annotate('rect', xmin=1.5, xmax=2.5, ymin=30, ymax=45, fill='yellow', alpha=0.2)
Arrow pointing to a feature¶
ggplot(mpg, aes(x='displ', y='hwy')) + geom_point() + \ ... annotate('segment', x=4, y=35, xend=2.5, yend=44, arrow=True)