Positions API Reference¶
Position adjustments control how overlapping geoms are displayed.
Dodge Positions¶
ggplotly.positions.position_dodge
¶
Dodge overlapping objects side-to-side.
__init__(width=None, preserve='total')
¶
Dodge overlapping objects side-to-side.
Dodging preserves the vertical position of a geom while adjusting the horizontal position. This is useful for bar charts, boxplots, and other geoms where multiple groups would otherwise overlap at the same x position.
Unlike position_jitter, position_dodge requires a grouping variable to determine which objects should be dodged relative to each other.
Parameters¶
width : float, optional Total width of the dodged area. Default is None, which uses the width of the elements. For most cases, 0.9 works well. preserve : str, default='total' Should dodging preserve the 'total' width of all elements at a position, or the width of a 'single' element?
Examples¶
from ggplotly import ggplot, aes, geom_bar, geom_point, data from ggplotly.positions import position_dodge mpg = data('mpg')
Dodged bar chart showing cylinder counts by drive type¶
ggplot(mpg, aes(x='cyl', fill='drv')) + \ ... geom_bar(position=position_dodge())
Dodged points with explicit width¶
ggplot(mpg, aes(x='cyl', y='hwy', color='drv')) + \ ... geom_point(position=position_dodge(width=0.5))
adjust(x, group=None, width=None)
¶
Adjust x positions by dodging based on group.
Parameters¶
x : array-like Original x positions. group : array-like, optional Group labels for each point. Points with the same x but different groups will be dodged. width : float, optional Total width of the dodge. Overrides instance width if provided.
Returns¶
array-like Adjusted x positions with groups dodged side-by-side.
compute_dodged_positions(data, x_col, group_col, width=None)
¶
Compute dodged positions for a DataFrame.
This is a convenience method for dodging positions in a DataFrame, handling the grouping automatically.
Parameters¶
data : DataFrame Data containing x and group columns. x_col : str Name of the x position column. group_col : str Name of the grouping column. width : float, optional Total dodge width.
Returns¶
array-like Adjusted x positions.
ggplotly.positions.position_dodge2
¶
Bases: position_dodge
Dodge overlapping objects side-to-side (version 2).
__init__(width=None, preserve='total', padding=0.1, reverse=False)
¶
Dodge overlapping objects side-to-side (version 2).
Unlike position_dodge(), position_dodge2() works without a grouping variable in a layer. It's particularly useful for arranging box plots, which can have variable widths.
Parameters¶
width : float, optional Total width of the dodged area. preserve : str, default='total' Whether to preserve 'total' or 'single' element width. padding : float, default=0.1 Padding between elements. reverse : bool, default=False Reverse the order of dodging.
Examples¶
from ggplotly import ggplot, aes, geom_boxplot, data from ggplotly.positions import position_dodge2 mpg = data('mpg')
Boxplots with custom padding¶
ggplot(mpg, aes(x='class', y='hwy')) + \ ... geom_boxplot(position=position_dodge2(padding=0.2))
Jitter Position¶
ggplotly.positions.position_jitter
¶
Adjust positions by adding random noise.
__init__(width=0.4, height=0, seed=None)
¶
Adjust positions by adding random noise.
This is useful for scatter plots where points would otherwise overlap, particularly when one or both axes are categorical or discrete.
Parameters¶
width : float, default=0.4 Amount of horizontal jitter. The jitter is added in both directions, so the total spread is width. height : float, default=0 Amount of vertical jitter. seed : int, optional Random seed for reproducibility.
Examples¶
from ggplotly import ggplot, aes, geom_point, data from ggplotly.positions import position_jitter mpg = data('mpg')
Jittered points to reduce overplotting¶
ggplot(mpg, aes(x='cyl', y='hwy')) + \ ... geom_point(position=position_jitter())
Control jitter amount¶
ggplot(mpg, aes(x='cyl', y='hwy')) + \ ... geom_point(position=position_jitter(width=0.2, height=0.5))
adjust(x, y=None, width=None, height=None)
¶
Adjust positions by jittering.
Parameters¶
x : array-like Original x positions. y : array-like, optional Original y positions. width : float, optional Override horizontal jitter width. height : float, optional Override vertical jitter height.
Returns¶
array-like or tuple If y is None: adjusted x positions. If y is provided: tuple of (adjusted x, adjusted y).
Stack Positions¶
ggplotly.positions.position_stack
¶
Stack overlapping objects on top of each other.
__init__(vjust=1, reverse=False)
¶
Stack overlapping objects on top of each other.
This is useful for stacked bar charts and area plots where you want to show how parts contribute to a whole.
Parameters¶
vjust : float, default=1 Vertical adjustment for position. reverse : bool, default=False Reverse stacking order.
Examples¶
from ggplotly import ggplot, aes, geom_bar, data from ggplotly.positions import position_stack mpg = data('mpg')
Stacked bar chart¶
ggplot(mpg, aes(x='class', fill='drv')) + \ ... geom_bar(position=position_stack())
adjust(y, group=None)
¶
compute_stacked_positions(data, x_col, y_col, group_col)
¶
Compute stacked positions for a DataFrame.
Stacks y values within each unique x position, ordered by group.
Parameters¶
data : DataFrame Data containing position columns. x_col : str Name of the x position column. y_col : str Name of the y value column. group_col : str Name of the grouping column.
Returns¶
tuple (y_bottom, y_top) arrays for each bar.
ggplotly.positions.position_fill
¶
Bases: position_stack
Stack and normalize to equal height for proportions.
__init__(vjust=1, reverse=False)
¶
Stack overlapping objects and standardize to have equal height.
This is useful for showing proportions rather than absolute values. Each stack is normalized to sum to 1 (or 100%).
Parameters¶
vjust : float, default=1 Vertical adjustment. reverse : bool, default=False Reverse stacking order.
Examples¶
from ggplotly import ggplot, aes, geom_bar, data from ggplotly.positions import position_fill mpg = data('mpg')
Proportional stacked bar chart (100% stacked)¶
ggplot(mpg, aes(x='class', fill='drv')) + \ ... geom_bar(position=position_fill())
compute_stacked_positions(data, x_col, y_col, group_col)
¶
Compute normalized stacked positions for a DataFrame.
Each x position's values are normalized to sum to 1.
Parameters¶
data : DataFrame Data containing position columns. x_col : str Name of the x position column. y_col : str Name of the y value column. group_col : str Name of the grouping column.
Returns¶
tuple (y_bottom, y_top) arrays normalized to [0, 1].
Other Positions¶
ggplotly.positions.position_identity
¶
Don't adjust position (identity transformation).
__init__()
¶
Don't adjust position.
This is the default position adjustment - it leaves the data unchanged.
Examples¶
from ggplotly import ggplot, aes, geom_point, data from ggplotly.positions import position_identity mpg = data('mpg')
Points with no position adjustment (default behavior)¶
ggplot(mpg, aes(x='displ', y='hwy')) + \ ... geom_point(position=position_identity())
adjust(x, **kwargs)
¶
Return positions unchanged.
ggplotly.positions.position_nudge
¶
Nudge points a fixed distance.
__init__(x=0, y=0)
¶
Nudge points a fixed distance.
This is useful for moving labels or points away from their anchors by a fixed amount.
Parameters¶
x : float, default=0 Horizontal distance to nudge. y : float, default=0 Vertical distance to nudge.
Examples¶
from ggplotly import ggplot, aes, geom_point, geom_text, data from ggplotly.positions import position_nudge mtcars = data('mtcars')
Nudge text labels away from points¶
ggplot(mtcars.head(10), aes(x='wt', y='mpg', label='model')) + \ ... geom_point() + \ ... geom_text(position=position_nudge(x=0.1, y=0.5))