Coordinates API Reference¶
Coordinate systems control how data coordinates are mapped to the plane of the graphic.
Cartesian Coordinates¶
ggplotly.coords.coord_cartesian.coord_cartesian
¶
Bases: Coord
Cartesian coordinate system with optional axis limits.
Unlike setting limits via scales, coord_cartesian zooms into the plot without removing data points outside the range. This preserves statistical summaries computed on the full data.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
xlim
|
tuple
|
Two-element tuple (min, max) for x-axis limits. |
None
|
ylim
|
tuple
|
Two-element tuple (min, max) for y-axis limits. |
None
|
expand
|
bool
|
If True (default), add a small expansion to the limits. If False, use exact limits specified. |
True
|
default_expand
|
tuple
|
Default expansion factor (mult, add). Default is (0.05, 0) meaning 5% multiplicative expansion. |
(0.05, 0)
|
clip
|
str
|
Should drawing be clipped to extent of plot panel? Options: 'on' (default) or 'off'. |
'on'
|
Examples:
>>> ggplot(df, aes(x='x', y='y')) + geom_point() + coord_cartesian(xlim=(0, 10))
>>> ggplot(df, aes(x='x', y='y')) + geom_point() + coord_cartesian(ylim=(-5, 5))
>>> ggplot(df, aes(x='x', y='y')) + geom_point() + coord_cartesian(xlim=(0, 10), ylim=(0, 100))
>>> ggplot(df, aes(x='x', y='y')) + geom_point() + coord_cartesian(expand=False)
>>> ggplot(df, aes(x='x', y='y')) + geom_point() + coord_cartesian(clip='off')
__init__(xlim=None, ylim=None, expand=True, default_expand=(0.05, 0), clip='on')
¶
Initialize the cartesian coordinate system.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
xlim
|
tuple
|
Two-element tuple (min, max) for x-axis limits. |
None
|
ylim
|
tuple
|
Two-element tuple (min, max) for y-axis limits. |
None
|
expand
|
bool
|
Whether to add expansion around limits. Default is True. |
True
|
default_expand
|
tuple
|
Expansion factor (mult, add). Default is (0.05, 0). |
(0.05, 0)
|
clip
|
str
|
Clipping mode ('on' or 'off'). Default is 'on'. |
'on'
|
apply(fig)
¶
Apply axis limits to the figure.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fig
|
Figure
|
Plotly figure object. |
required |
ggplotly.coords.coord_fixed.coord_fixed
¶
Bases: Coord
Cartesian coordinate system with a fixed aspect ratio.
A fixed aspect ratio ensures that one unit on the x-axis is the same length as one unit on the y-axis (when ratio=1). This is essential for: - Maps where distortion must be avoided - Scatter plots where the relationship shape matters - Any plot where physical proportions are important
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ratio
|
float
|
The aspect ratio, expressed as y/x. Default is 1, meaning one unit on the x-axis equals one unit on the y-axis. - ratio > 1: y-axis units are longer than x-axis units - ratio < 1: x-axis units are longer than y-axis units |
1
|
xlim
|
tuple
|
Two-element tuple (min, max) for x-axis limits. |
None
|
ylim
|
tuple
|
Two-element tuple (min, max) for y-axis limits. |
None
|
expand
|
bool
|
If True (default), add a small expansion to the limits. |
True
|
clip
|
str
|
Should drawing be clipped to extent of plot panel? Options: 'on' (default) or 'off'. |
'on'
|
Examples:
>>> # Map with equal coordinates
>>> ggplot(map_df, aes(x='lon', y='lat')) + geom_polygon() + coord_fixed()
>>> # Custom aspect ratio (y is twice as long as x)
>>> ggplot(df, aes(x='x', y='y')) + geom_point() + coord_fixed(ratio=2)
>>> # Fixed ratio with explicit limits
>>> ggplot(df, aes(x='x', y='y')) + geom_point() + coord_fixed(xlim=(0, 10), ylim=(0, 10))
>>> # Circle should look like a circle, not an ellipse
>>> ggplot(circle_df, aes(x='x', y='y')) + geom_path() + coord_fixed()
See Also
coord_cartesian: Cartesian coordinates without fixed ratio coord_sf: Coordinate system for spatial data (also maintains aspect ratio)
__init__(ratio=1, xlim=None, ylim=None, expand=True, clip='on')
¶
Initialize the fixed aspect ratio coordinate system.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ratio
|
float
|
Aspect ratio y/x. Default is 1 (equal scaling). |
1
|
xlim
|
tuple
|
X-axis limits (min, max). |
None
|
ylim
|
tuple
|
Y-axis limits (min, max). |
None
|
expand
|
bool
|
Whether to add expansion around limits. Default is True. |
True
|
clip
|
str
|
Clipping mode ('on' or 'off'). Default is 'on'. |
'on'
|
apply(fig)
¶
Apply fixed aspect ratio to the figure.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fig
|
Figure
|
Plotly figure object. |
required |
ggplotly.coords.coord_flip.coord_flip
¶
Bases: Coord
Flip cartesian coordinates so x becomes y and y becomes x.
This is useful for horizontal bar charts and other cases where you want to swap the axes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
xlim
|
Limits for the x-axis (after flipping, this controls the vertical axis). |
None
|
|
ylim
|
Limits for the y-axis (after flipping, this controls the horizontal axis). |
None
|
|
expand
|
If True (default), adds a small expansion factor to the limits. |
True
|
|
clip
|
Whether to clip points that fall outside the plotting area. "on" (default) clips to panel, "off" allows drawing outside. |
'on'
|
Examples:
>>> ggplot(df, aes(x='category', y='value')) + geom_bar() + coord_flip()
>>> ggplot(df, aes(x='category', y='value')) + geom_bar() + coord_flip(xlim=(0, 100))
__init__(xlim=None, ylim=None, expand=True, clip='on')
¶
Initialize coord_flip.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
xlim
|
Limits for the x-axis (after flipping). |
None
|
|
ylim
|
Limits for the y-axis (after flipping). |
None
|
|
expand
|
Whether to expand limits (default True). |
True
|
|
clip
|
Clipping mode ("on" or "off"). |
'on'
|
apply(fig)
¶
Apply coordinate flip to the figure by swapping x and y data.
This swaps the x and y values in all traces, effectively rotating the plot 90 degrees. Also swaps axis titles and settings.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fig
|
Figure
|
The Plotly figure to modify. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
None |
Modifies the figure in place. |
Polar Coordinates¶
ggplotly.coords.coord_polar.coord_polar
¶
Bases: Coord
Polar coordinate system for circular/radial plots.
Transforms cartesian coordinates into polar coordinates where one variable maps to angle and the other to radius. Useful for pie charts, radar charts, wind roses, and other circular visualizations.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
theta
|
str
|
Variable that maps to angle. Either 'x' (default) or 'y'. If 'x', x values map to angle and y to radius. If 'y', y values map to angle and x to radius. |
'x'
|
start
|
float
|
Offset of starting point from 12 o'clock in radians. Default is 0 (start at 12 o'clock). |
0
|
direction
|
int
|
1 for clockwise (default), -1 for counterclockwise. |
1
|
clip
|
str
|
Should drawing be clipped to the extent of the plot panel? Options: 'on' (default), 'off'. |
'on'
|
Examples:
>>> ggplot(df, aes(x='category', y='value')) + geom_bar() + coord_polar()
>>> ggplot(df, aes(x='category', y='value')) + geom_bar() + coord_polar(theta='y')
>>> ggplot(df, aes(x='wind_dir', y='speed')) + geom_bar() + coord_polar(start=np.pi/2)
>>> ggplot(df, aes(x='category', y='value')) + geom_bar() + coord_polar(direction=-1)
__init__(theta='x', start=0, direction=1, clip='on')
¶
Initialize the polar coordinate system.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
theta
|
str
|
Variable that maps to angle ('x' or 'y'). Default is 'x'. |
'x'
|
start
|
float
|
Starting angle offset in radians. Default is 0. |
0
|
direction
|
int
|
1 for clockwise, -1 for counterclockwise. Default is 1. |
1
|
clip
|
str
|
Clipping mode ('on' or 'off'). Default is 'on'. |
'on'
|
apply(fig)
¶
Apply polar coordinate transformation to the figure.
Converts cartesian traces to polar equivalents: - Bar traces -> Pie chart (when theta='x') or Barpolar (when theta='y') - Scatter traces -> Scatterpolar
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fig
|
Figure
|
Plotly figure object. |
required |
Map Projections¶
ggplotly.coords.coord_sf.coord_sf
¶
Bases: Coord
Coordinate system for sf (simple features) geographic data.
__init__(xlim=None, ylim=None, expand=True, crs=None, datum='EPSG:4326', default_crs=None, label_graticule=None, ndiscr=100, clip='on')
¶
Configure geographic coordinate system for maps.
Designed for use with geom_map/geom_sf. Provides control over projection, geographic bounds, and map display settings.
Parameters¶
xlim : tuple, optional Longitude limits as (min, max). E.g., (-125, -65) for continental US. ylim : tuple, optional Latitude limits as (min, max). E.g., (25, 50) for continental US. expand : bool, default=True Whether to expand limits slightly to prevent data touching edges. crs : str, optional Coordinate reference system / projection. Options: - 'mercator', 'natural earth', 'albers usa', 'orthographic' - 'equirectangular', 'robinson', 'miller', 'mollweide' - EPSG codes like 'EPSG:4326' (WGS84) datum : str, default='EPSG:4326' CRS for graticules (ggplot2 compatibility). default_crs : str, optional Default CRS for non-sf layers. Set to 'EPSG:4326' for lon/lat. label_graticule : str, optional Which graticule lines to label. E.g., 'NESW', 'NS', 'EW'. ndiscr : int, default=100 Number of segments for discretizing lines (smoother curves). clip : str, default='on' Whether to clip to panel: 'on' or 'off'.
Examples¶
coord_sf(xlim=(-125, -65), ylim=(25, 50)) # continental US bounds coord_sf(crs='robinson') # Robinson projection coord_sf(crs='orthographic') # Globe projection
apply(fig)
¶
Apply the coordinate transformation to the figure.
For geo figures (scattergeo, choropleth), updates the geo layout. For mapbox figures (scattermapbox, etc.), updates mapbox layout.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fig
|
Figure
|
Plotly figure object. |
required |