matplotlib.projections

class matplotlib.projections.ProjectionRegistry

Bases: object

A mapping of registered projection names to projection classes.

get_projection_class(self, name)

Get a projection class from its name.

get_projection_names(self)

Return the names of all projections currently registered.

register(self, *projections)

Register a new set of projections.

matplotlib.projections.get_projection_class(projection=None)

Get a projection class from its name.

If projection is None, a standard rectilinear projection is returned.

matplotlib.projections.get_projection_names()

Return the names of all projections currently registered.

matplotlib.projections.process_projection_requirements(figure, *args, **kwargs)

[Deprecated]

Notes

Deprecated since version 3.1:

matplotlib.projections.register_projection(cls)

matplotlib.projections.polar

class matplotlib.projections.polar.InvertedPolarTransform(axis=None, use_rmin=True, _apply_theta_transforms=True)

Bases: matplotlib.transforms.Transform

The inverse of the polar transform, mapping Cartesian coordinate space x and y back to theta and r.

Creates a new TransformNode.

Parameters:

shorthand_namestr

A string representing the "name" of the transform. The name carries no significance other than to improve the readability of str(transform) when DEBUG=True.

has_inverse = True

input_dims = 2

inverted(self)

Return the corresponding inverse transformation.

It holds x == self.inverted().transform(self.transform(x)).

The return value of this method should be treated as temporary. An update to self does not cause a corresponding update to its inverted copy.

is_separable = False

output_dims = 2

transform_non_affine(self, xy)

Performs only the non-affine part of the transformation.

transform(values) is always equivalent to transform_affine(transform_non_affine(values)).

In non-affine transformations, this is generally equivalent to transform(values). In affine transformations, this is always a no-op.

Parameters:

valuesarray

The input values as NumPy array of length input_dims or shape (N x input_dims).

Returns:

valuesarray

The output values as NumPy array of length input_dims or shape (N x output_dims), depending on the input.

class matplotlib.projections.polar.PolarAffine(scale_transform, limits)

Bases: matplotlib.transforms.Affine2DBase

The affine part of the polar projection. Scales the output so that maximum radius rests on the edge of the axes circle.

limits is the view limit of the data. The only part of its bounds that is used is the y limits (for the radius limits). The theta range is handled by the non-affine transform.

get_matrix(self)

Get the Affine transformation array for the affine part of this transform.

class matplotlib.projections.polar.PolarAxes(*args, theta_offset=0, theta_direction=1, rlabel_position=22.5, **kwargs)

Bases: matplotlib.axes._axes.Axes

A polar graph projection, where the input dimensions are theta, r.

Theta starts pointing east and goes anti-clockwise.

Build an axes in a figure.

Parameters:

figFigure

The axes is build in the Figure fig.

rect[left, bottom, width, height]

The axes is build in the rectangle rect. rect is in Figure coordinates.

sharex, shareyAxes, optional

The x or y axis is shared with the x or y axis in the input Axes.

frameonbool, optional

True means that the axes frame is visible.

**kwargs

Other optional keyword arguments:

Property	Description
adjustable	{'box', 'datalim'}
agg_filter	a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array
alpha	float or None
anchor	2-tuple of floats or {'C', 'SW', 'S', 'SE', ...}
animated	bool
aspect	{'auto', 'equal'} or num
autoscale_on	bool
autoscalex_on	bool
autoscaley_on	bool
axes_locator	Callable[[Axes, Renderer], Bbox]
axisbelow	bool or 'line'
clip_box	Bbox
clip_on	bool
clip_path	Patch or (Path, Transform) or None
contains	callable
facecolor	color
fc	color
figure	Figure
frame_on	bool
gid	str
in_layout	bool
label	object
navigate	bool
navigate_mode	unknown
path_effects	AbstractPathEffect
picker	None or bool or float or callable
position	[left, bottom, width, height] or Bbox
prop_cycle	unknown
rasterization_zorder	float or None
rasterized	bool or None
sketch_params	(scale: float, length: float, randomness: float)
snap	bool or None
title	str
transform	Transform
url	str
visible	bool
xbound	unknown
xlabel	str
xlim	(bottom: float, top: float)
xmargin	float greater than -0.5
xscale	{"linear", "log", "symlog", "logit", ...}
xticklabels	List[str]
xticks	unknown
ybound	unknown
ylabel	str
ylim	(bottom: float, top: float)
ymargin	float greater than -0.5
yscale	{"linear", "log", "symlog", "logit", ...}
yticklabels	List[str]
yticks	unknown
zorder	float

Returns:

axesAxes

The new Axes object.

class InvertedPolarTransform(axis=None, use_rmin=True, _apply_theta_transforms=True)

Bases: matplotlib.transforms.Transform

The inverse of the polar transform, mapping Cartesian coordinate space x and y back to theta and r.

Creates a new TransformNode.

Parameters:

shorthand_namestr

A string representing the "name" of the transform. The name carries no significance other than to improve the readability of str(transform) when DEBUG=True.

has_inverse = True

input_dims = 2

inverted(self)

Return the corresponding inverse transformation.

It holds x == self.inverted().transform(self.transform(x)).

The return value of this method should be treated as temporary. An update to self does not cause a corresponding update to its inverted copy.

is_separable = False

output_dims = 2

transform_non_affine(self, xy)

Performs only the non-affine part of the transformation.

transform(values) is always equivalent to transform_affine(transform_non_affine(values)).

In non-affine transformations, this is generally equivalent to transform(values). In affine transformations, this is always a no-op.

Parameters:

valuesarray

The input values as NumPy array of length input_dims or shape (N x input_dims).

Returns:

valuesarray

The output values as NumPy array of length input_dims or shape (N x output_dims), depending on the input.

class PolarAffine(scale_transform, limits)

Bases: matplotlib.transforms.Affine2DBase

The affine part of the polar projection. Scales the output so that maximum radius rests on the edge of the axes circle.

limits is the view limit of the data. The only part of its bounds that is used is the y limits (for the radius limits). The theta range is handled by the non-affine transform.

get_matrix(self)

Get the Affine transformation array for the affine part of this transform.

class PolarTransform(axis=None, use_rmin=True, _apply_theta_transforms=True)

Bases: matplotlib.transforms.Transform

The base polar transform. This handles projection theta and r into Cartesian coordinate space x and y, but does not perform the ultimate affine transformation into the correct position.

Creates a new TransformNode.

Parameters:

shorthand_namestr

A string representing the "name" of the transform. The name carries no significance other than to improve the readability of str(transform) when DEBUG=True.

has_inverse = True

input_dims = 2

inverted(self)

Return the corresponding inverse transformation.

It holds x == self.inverted().transform(self.transform(x)).

The return value of this method should be treated as temporary. An update to self does not cause a corresponding update to its inverted copy.

is_separable = False

output_dims = 2

transform_non_affine(self, tr)

Performs only the non-affine part of the transformation.

transform(values) is always equivalent to transform_affine(transform_non_affine(values)).

In non-affine transformations, this is generally equivalent to transform(values). In affine transformations, this is always a no-op.

Parameters:

valuesarray

The input values as NumPy array of length input_dims or shape (N x input_dims).

Returns:

valuesarray

The output values as NumPy array of length input_dims or shape (N x output_dims), depending on the input.

transform_path_non_affine(self, path)

Returns a path, transformed only by the non-affine part of this transform.

path: a Path instance.

transform_path(path) is equivalent to transform_path_affine(transform_path_non_affine(values)).

class RadialLocator(base, axes=None)

Bases: matplotlib.ticker.Locator

Used to locate radius ticks.

Ensures that all ticks are strictly positive. For all other tasks, it delegates to the base Locator (which may be different depending on the scale of the r-axis.

autoscale(self)

[Deprecated]

Notes

Deprecated since version 3.2:

nonsingular(self, vmin, vmax)

Adjust a range as needed to avoid singularities.

This method gets called during autoscaling, with (v0, v1) set to the data limits on the axes if the axes contains any data, or (-inf, +inf) if not.

• If v0 == v1 (possibly up to some floating point slop), this method returns an expanded interval around this value.
• If (v0, v1) == (-inf, +inf), this method returns appropriate default view limits.
• Otherwise, (v0, v1) is returned without modification.

pan(self, numsteps)

Pan numticks (can be positive or negative)

refresh(self)

Refresh internal information based on current limits.

view_limits(self, vmin, vmax)

Select a scale for the range from vmin to vmax.

Subclasses should override this method to change locator behaviour.

zoom(self, direction)

Zoom in/out on axis; if direction is >0 zoom in, else zoom out

class ThetaFormatter

Bases: matplotlib.ticker.Formatter

Used to format the theta tick labels. Converts the native unit of radians into degrees and adds a degree symbol.

class ThetaLocator(base)

Bases: matplotlib.ticker.Locator

Used to locate theta ticks.

This will work the same as the base locator except in the case that the view spans the entire circle. In such cases, the previously used default locations of every 45 degrees are returned.

autoscale(self)

[Deprecated]

Notes

Deprecated since version 3.2:

pan(self, numsteps)

Pan numticks (can be positive or negative)

refresh(self)

Refresh internal information based on current limits.

set_axis(self, axis)

view_limits(self, vmin, vmax)

Select a scale for the range from vmin to vmax.

Subclasses should override this method to change locator behaviour.

zoom(self, direction)

Zoom in/out on axis; if direction is >0 zoom in, else zoom out

can_pan(self)

Return True if this axes supports the pan/zoom button functionality.

For polar axes, this is slightly misleading. Both panning and zooming are performed by the same button. Panning is performed in azimuth while zooming is done along the radial.

can_zoom(self)

Return True if this axes supports the zoom box button functionality.

Polar axes do not support zoom boxes.

cla(self)

Clear the current axes.

drag_pan(self, button, key, x, y)

Called when the mouse moves during a pan operation.

button is the mouse button number:

• 1: LEFT
• 2: MIDDLE
• 3: RIGHT

key is a "shift" key

x, y are the mouse coordinates in display coords.

Note

Intended to be overridden by new projection types.

draw(self, *args, **kwargs)

Draw everything (plot lines, axes, labels)

end_pan(self)

Called when a pan operation completes (when the mouse button is up.)

Note

Intended to be overridden by new projection types.

format_coord(self, theta, r)

Return a format string formatting the coordinate using Unicode characters.

get_data_ratio(self)

Return the aspect ratio of the data itself. For a polar plot, this should always be 1.0

get_rlabel_position(self)

Returns:

float

The theta position of the radius labels in degrees.

get_rmax(self)

Returns:

float

Outer radial limit.

get_rmin(self)

Returns:

float

The inner radial limit.

get_rorigin(self)

Returns:

float

get_rsign(self)

get_theta_direction(self)

Get the direction in which theta increases.

-1:

Theta increases in the clockwise direction

1:

Theta increases in the counterclockwise direction

get_theta_offset(self)

Get the offset for the location of 0 in radians.

get_thetamax(self)

Return the maximum theta limit in degrees.

get_thetamin(self)

Get the minimum theta limit in degrees.

get_xaxis_text1_transform(self, pad)

Returns:

transformTransform

The transform used for drawing x-axis labels, which will add pad_points of padding (in points) between the axes and the label. The x-direction is in data coordinates and the y-direction is in axis corrdinates

valign{'center', 'top', 'bottom', 'baseline', 'center_baseline'}

The text vertical alignment.

halign{'center', 'left', 'right'}

The text horizontal alignment.

Notes

This transformation is primarily used by the Axis class, and is meant to be overridden by new kinds of projections that may need to place axis elements in different locations.

get_xaxis_text2_transform(self, pad)

Returns:

transformTransform

The transform used for drawing secondary x-axis labels, which will add pad_points of padding (in points) between the axes and the label. The x-direction is in data coordinates and the y-direction is in axis corrdinates

valign{'center', 'top', 'bottom', 'baseline', 'center_baseline'}

The text vertical alignment.

halign{'center', 'left', 'right'}

The text horizontal alignment.

Notes

This transformation is primarily used by the Axis class, and is meant to be overridden by new kinds of projections that may need to place axis elements in different locations.

get_xaxis_transform(self, which='grid')

Get the transformation used for drawing x-axis labels, ticks and gridlines. The x-direction is in data coordinates and the y-direction is in axis coordinates.

Note

This transformation is primarily used by the Axis class, and is meant to be overridden by new kinds of projections that may need to place axis elements in different locations.

get_yaxis_text1_transform(self, pad)

Returns:

transformTransform

The transform used for drawing y-axis labels, which will add pad_points of padding (in points) between the axes and the label. The x-direction is in axis coordinates and the y-direction is in data corrdinates

valign{'center', 'top', 'bottom', 'baseline', 'center_baseline'}

The text vertical alignment.

halign{'center', 'left', 'right'}

The text horizontal alignment.

Notes

This transformation is primarily used by the Axis class, and is meant to be overridden by new kinds of projections that may need to place axis elements in different locations.

get_yaxis_text2_transform(self, pad)

Returns:

transformTransform

The transform used for drawing secondart y-axis labels, which will add pad_points of padding (in points) between the axes and the label. The x-direction is in axis coordinates and the y-direction is in data corrdinates

valign{'center', 'top', 'bottom', 'baseline', 'center_baseline'}

The text vertical alignment.

halign{'center', 'left', 'right'}

The text horizontal alignment.

Notes

This transformation is primarily used by the Axis class, and is meant to be overridden by new kinds of projections that may need to place axis elements in different locations.

get_yaxis_transform(self, which='grid')

Get the transformation used for drawing y-axis labels, ticks and gridlines. The x-direction is in axis coordinates and the y-direction is in data coordinates.

Note

This transformation is primarily used by the Axis class, and is meant to be overridden by new kinds of projections that may need to place axis elements in different locations.

name = 'polar'

set_rgrids(self, radii, labels=None, angle=None, fmt=None, **kwargs)

Set the radial gridlines on a polar plot.

Parameters:

radiituple with floats

The radii for the radial gridlines

labelstuple with strings or None

The labels to use at each radial gridline. The matplotlib.ticker.ScalarFormatter will be used if None.

anglefloat

The angular position of the radius labels in degrees.

fmtstr or None

Format string used in matplotlib.ticker.FormatStrFormatter. For example '%f'.

Returns:

lines, labelslist of lines.Line2D, list of text.Text

lines are the radial gridlines and labels are the tick labels.

Other Parameters:

**kwargs

kwargs are optional Text properties for the labels.

See also

PolarAxes.set_thetagrids

Axis.get_gridlines

Axis.get_ticklabels

set_rlabel_position(self, value)

Updates the theta position of the radius labels.

Parameters:

valuenumber

The angular position of the radius labels in degrees.

set_rlim(self, bottom=None, top=None, emit=True, auto=False, **kwargs)

See set_ylim.

set_rmax(self, rmax)

Set the outer radial limit.

Parameters:

rmaxfloat

set_rmin(self, rmin)

Set the inner radial limit.

Parameters:

rminfloat

set_rorigin(self, rorigin)

Update the radial origin.

Parameters:

roriginfloat

set_rscale(self, *args, **kwargs)

set_rticks(self, *args, **kwargs)

set_theta_direction(self, direction)

Set the direction in which theta increases.

clockwise, -1:

Theta increases in the clockwise direction

counterclockwise, anticlockwise, 1:

Theta increases in the counterclockwise direction

set_theta_offset(self, offset)

Set the offset for the location of 0 in radians.

set_theta_zero_location(self, loc, offset=0.0)

Sets the location of theta's zero. (Calls set_theta_offset with the correct value in radians under the hood.)

locstr

May be one of "N", "NW", "W", "SW", "S", "SE", "E", or "NE".

offsetfloat, optional

An offset in degrees to apply from the specified loc. Note: this offset is always applied counter-clockwise regardless of the direction setting.

set_thetagrids(self, angles, labels=None, fmt=None, **kwargs)

Set the theta gridlines in a polar plot.

Parameters:

anglestuple with floats, degrees

The angles of the theta gridlines.

labelstuple with strings or None

The labels to use at each theta gridline. The projections.polar.ThetaFormatter will be used if None.

fmtstr or None

Format string used in matplotlib.ticker.FormatStrFormatter. For example '%f'. Note that the angle that is used is in radians.

Returns:

lines, labelslist of lines.Line2D, list of text.Text

lines are the theta gridlines and labels are the tick labels.

Other Parameters:

**kwargs

kwargs are optional Text properties for the labels.

See also

PolarAxes.set_rgrids

Axis.get_gridlines

Axis.get_ticklabels

set_thetalim(self, *args, **kwargs)

Set the minimum and maximum theta values.

Parameters:

thetaminfloat

Minimum value in degrees.

thetamaxfloat

Maximum value in degrees.

set_thetamax(self, thetamax)

Set the maximum theta limit in degrees.

set_thetamin(self, thetamin)

Set the minimum theta limit in degrees.

set_xscale(self, scale, *args, **kwargs)

Set the x-axis scale.

Parameters:

value{"linear", "log", "symlog", "logit", ...}

The axis scale type to apply.

**kwargs

Different keyword arguments are accepted, depending on the scale. See the respective class keyword arguments:

• matplotlib.scale.LinearScale
• matplotlib.scale.LogScale
• matplotlib.scale.SymmetricalLogScale
• matplotlib.scale.LogitScale

Notes

By default, Matplotlib supports the above mentioned scales. Additionally, custom scales may be registered using matplotlib.scale.register_scale. These scales can then also be used here.

set_ylim(self, bottom=None, top=None, emit=True, auto=False, *, ymin=None, ymax=None)

Set the data limits for the radial axis.

Parameters:

bottomscalar, optional

The bottom limit (default: None, which leaves the bottom limit unchanged). The bottom and top ylims may be passed as the tuple (bottom, top) as the first positional argument (or as the bottom keyword argument).

topscalar, optional

The top limit (default: None, which leaves the top limit unchanged).

emitbool, optional

Whether to notify observers of limit change (default: True).

autobool or None, optional

Whether to turn on autoscaling of the y-axis. True turns on, False turns off (default action), None leaves unchanged.

ymin, ymaxscalar, optional

These arguments are deprecated and will be removed in a future version. They are equivalent to bottom and top respectively, and it is an error to pass both ymin and bottom or ymax and top.

Returns:

bottom, top(float, float)

The new y-axis limits in data coordinates.

set_yscale(self, *args, **kwargs)

Set the y-axis scale.

Parameters:

value{"linear", "log", "symlog", "logit", ...}

The axis scale type to apply.

**kwargs

Different keyword arguments are accepted, depending on the scale. See the respective class keyword arguments:

• matplotlib.scale.LinearScale
• matplotlib.scale.LogScale
• matplotlib.scale.SymmetricalLogScale
• matplotlib.scale.LogitScale

Notes

By default, Matplotlib supports the above mentioned scales. Additionally, custom scales may be registered using matplotlib.scale.register_scale. These scales can then also be used here.

start_pan(self, x, y, button)

Called when a pan operation has started.

x, y are the mouse coordinates in display coords. button is the mouse button number:

• 1: LEFT
• 2: MIDDLE
• 3: RIGHT

Note

Intended to be overridden by new projection types.

class matplotlib.projections.polar.PolarTransform(axis=None, use_rmin=True, _apply_theta_transforms=True)

Bases: matplotlib.transforms.Transform

The base polar transform. This handles projection theta and r into Cartesian coordinate space x and y, but does not perform the ultimate affine transformation into the correct position.

Creates a new TransformNode.

Parameters:

shorthand_namestr

A string representing the "name" of the transform. The name carries no significance other than to improve the readability of str(transform) when DEBUG=True.

has_inverse = True

input_dims = 2

inverted(self)

Return the corresponding inverse transformation.

It holds x == self.inverted().transform(self.transform(x)).

The return value of this method should be treated as temporary. An update to self does not cause a corresponding update to its inverted copy.

is_separable = False

output_dims = 2

transform_non_affine(self, tr)

Performs only the non-affine part of the transformation.

transform(values) is always equivalent to transform_affine(transform_non_affine(values)).

In non-affine transformations, this is generally equivalent to transform(values). In affine transformations, this is always a no-op.

Parameters:

valuesarray

The input values as NumPy array of length input_dims or shape (N x input_dims).

Returns:

valuesarray

The output values as NumPy array of length input_dims or shape (N x output_dims), depending on the input.

transform_path_non_affine(self, path)

Returns a path, transformed only by the non-affine part of this transform.

path: a Path instance.

transform_path(path) is equivalent to transform_path_affine(transform_path_non_affine(values)).

class matplotlib.projections.polar.RadialAxis(*args, **kwargs)

Bases: matplotlib.axis.YAxis

A radial Axis.

This overrides certain properties of a YAxis to provide special-casing for a radial axis.

Parameters:

axesmatplotlib.axes.Axes

The Axes to which the created Axis belongs.

pickradiusfloat

The acceptance radius for containment tests. See also Axis.contains.

axis_name = 'radius'

Read-only name identifying the axis.

cla(self)

Clear this axis.

class matplotlib.projections.polar.RadialLocator(base, axes=None)

Bases: matplotlib.ticker.Locator

Used to locate radius ticks.

Ensures that all ticks are strictly positive. For all other tasks, it delegates to the base Locator (which may be different depending on the scale of the r-axis.

autoscale(self)

[Deprecated]

Notes

Deprecated since version 3.2:

nonsingular(self, vmin, vmax)

Adjust a range as needed to avoid singularities.

This method gets called during autoscaling, with (v0, v1) set to the data limits on the axes if the axes contains any data, or (-inf, +inf) if not.

• If v0 == v1 (possibly up to some floating point slop), this method returns an expanded interval around this value.
• If (v0, v1) == (-inf, +inf), this method returns appropriate default view limits.
• Otherwise, (v0, v1) is returned without modification.

pan(self, numsteps)

Pan numticks (can be positive or negative)

refresh(self)

Refresh internal information based on current limits.

view_limits(self, vmin, vmax)

Select a scale for the range from vmin to vmax.

Subclasses should override this method to change locator behaviour.

zoom(self, direction)

Zoom in/out on axis; if direction is >0 zoom in, else zoom out

class matplotlib.projections.polar.RadialTick(axes, loc, label, size=None, width=None, color=None, tickdir=None, pad=None, labelsize=None, labelcolor=None, zorder=None, gridOn=None, tick1On=True, tick2On=True, label1On=True, label2On=False, major=True, labelrotation=0, grid_color=None, grid_linestyle=None, grid_linewidth=None, grid_alpha=None, **kw)

Bases: matplotlib.axis.YTick

A radial-axis tick.

This subclass of YTick provides radial ticks with some small modification to their re-positioning such that ticks are rotated based on axes limits. This results in ticks that are correctly perpendicular to the spine. Labels are also rotated to be perpendicular to the spine, when 'auto' rotation is enabled.

bbox is the Bound2D bounding box in display coords of the Axes loc is the tick location in data coords size is the tick size in points

update_position(self, loc)

Set the location of tick in data coords with scalar loc.

class matplotlib.projections.polar.ThetaAxis(axes, pickradius=15)

Bases: matplotlib.axis.XAxis

A theta Axis.

This overrides certain properties of an XAxis to provide special-casing for an angular axis.

Parameters:

axesmatplotlib.axes.Axes

The Axes to which the created Axis belongs.

pickradiusfloat

The acceptance radius for containment tests. See also Axis.contains.

axis_name = 'theta'

Read-only name identifying the axis.

cla(self)

Clear this axis.

class matplotlib.projections.polar.ThetaFormatter

Bases: matplotlib.ticker.Formatter

Used to format the theta tick labels. Converts the native unit of radians into degrees and adds a degree symbol.

class matplotlib.projections.polar.ThetaLocator(base)

Bases: matplotlib.ticker.Locator

Used to locate theta ticks.

This will work the same as the base locator except in the case that the view spans the entire circle. In such cases, the previously used default locations of every 45 degrees are returned.

autoscale(self)

[Deprecated]

Notes

Deprecated since version 3.2:

pan(self, numsteps)

Pan numticks (can be positive or negative)

refresh(self)

Refresh internal information based on current limits.

set_axis(self, axis)

view_limits(self, vmin, vmax)

Select a scale for the range from vmin to vmax.

Subclasses should override this method to change locator behaviour.

zoom(self, direction)

Zoom in/out on axis; if direction is >0 zoom in, else zoom out

class matplotlib.projections.polar.ThetaTick(axes, *args, **kwargs)

Bases: matplotlib.axis.XTick

A theta-axis tick.

This subclass of XTick provides angular ticks with some small modification to their re-positioning such that ticks are rotated based on tick location. This results in ticks that are correctly perpendicular to the arc spine.

When 'auto' rotation is enabled, labels are also rotated to be parallel to the spine. The label padding is also applied here since it's not possible to use a generic axes transform to produce tick-specific padding.

bbox is the Bound2D bounding box in display coords of the Axes loc is the tick location in data coords size is the tick size in points

update_position(self, loc)

Set the location of tick in data coords with scalar loc.