projections

matplotlib.projections

class matplotlib.projections.ProjectionRegistry

Bases: object

Manages the set of projections available to the system.

get_projection_class(name)

Get a projection class from its name.

get_projection_names()

Get a list of the names of all projections currently registered.

register(*projections)

Register a new set of projection(s).

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()

Get a list of acceptable projection names.

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

Handle the args/kwargs to for add_axes/add_subplot/gca, returning:

(axes_proj_class, proj_class_kwargs, proj_stack_key)

Which can be used for new axes initialization/identification.

Note

kwargs is modified in place.

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.

input_dims = 2

inverted()

Return the corresponding inverse transformation.

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.

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

is_separable = False

output_dims = 2

transform_non_affine(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.

Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims).

Alternatively, accepts a numpy array of length input_dims and returns a numpy array of length output_dims.

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()

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

class matplotlib.projections.polar.PolarAxes(*args, **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 instance in Figure fig with rect=[left, bottom, width, height] in Figure coordinates

Optional keyword arguments:

Keyword	Description
adjustable	[ 'box' | 'datalim' ]
alpha	float: the alpha transparency (can be None)
anchor	[ 'C', 'SW', 'S', 'SE', 'E', 'NE', 'N', 'NW', 'W' ]
aspect	[ 'auto' | 'equal' | aspect_ratio ]
autoscale_on	bool; whether to autoscale the viewlim
axisbelow	[ bool | 'line' ] draw the grids and ticks below or above most other artists, or below lines but above patches
cursor_props	a (float, color) tuple
figure	a Figure instance
frame_on	bool; whether to draw the axes frame
label	the axes label
navigate	bool
navigate_mode	[ 'PAN' | 'ZOOM' | None ] the navigation toolbar button status
position	[left, bottom, width, height] in class:Figure coords
sharex	an class:Axes instance to share the x-axis with
sharey	an class:Axes instance to share the y-axis with
title	the title string
visible	bool, whether the axes is visible
xlabel	the xlabel
xlim	(xmin, xmax) view limits
xscale	['linear' | 'log' | 'logit' | 'symlog']
xticklabels	sequence of strings
xticks	sequence of floats
ylabel	the ylabel strings
ylim	(ymin, ymax) view limits
yscale	['linear' | 'log' | 'logit' | 'symlog']
yticklabels	sequence of strings
yticks	sequence of floats

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.

input_dims = 2

inverted()

Return the corresponding inverse transformation.

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.

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

is_separable = False

output_dims = 2

transform_non_affine(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.

Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims).

Alternatively, accepts a numpy array of length input_dims and returns a numpy array of length output_dims.

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()

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.

input_dims = 2

inverted()

Return the corresponding inverse transformation.

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.

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

is_separable = False

output_dims = 2

transform_non_affine(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.

Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims).

Alternatively, accepts a numpy array of length input_dims and returns a numpy array of length output_dims.

transform_path_non_affine(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()

autoscale the view limits

pan(numsteps)

Pan numticks (can be positive or negative)

refresh()

refresh internal information based on current lim

view_limits(vmin, vmax)

select a scale for the range from vmin to vmax

Normally this method is overridden by subclasses to change locator behaviour.

zoom(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()

autoscale the view limits

pan(numsteps)

Pan numticks (can be positive or negative)

refresh()

refresh internal information based on current lim

set_axis(axis)

view_limits(vmin, vmax)

select a scale for the range from vmin to vmax

Normally this method is overridden by subclasses to change locator behaviour.

zoom(direction)

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

can_pan()

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()

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

Polar axes do not support zoom boxes.

cla()

Clear the current axes.

drag_pan(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(*args, **kwargs)

Draw everything (plot lines, axes, labels)

end_pan()

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

Note

Intended to be overridden by new projection types.

format_coord(theta, r)

Return a format string formatting the coordinate using Unicode characters.

get_data_ratio()

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

get_rlabel_position()

Returns:

float

The theta position of the radius labels in degrees.

get_rmax()

get_rmin()

get_rorigin()

get_theta_direction()

Get the direction in which theta increases.

-1:

Theta increases in the clockwise direction

1:

Theta increases in the counterclockwise direction

get_theta_offset()

Get the offset for the location of 0 in radians.

get_thetamax()

get_thetamin()

get_xaxis_text1_transform(pad)

Get the transformation used for drawing x-axis labels, which will add the given amount of padding (in points) between the axes and the label. The x-direction is in data coordinates and the y-direction is in axis coordinates. Returns a 3-tuple of the form:

(transform, valign, halign)

where valign and halign are requested alignments for the text.

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_xaxis_text2_transform(pad)

Get the transformation used for drawing the secondary x-axis labels, which will add the given amount of padding (in points) between the axes and the label. The x-direction is in data coordinates and the y-direction is in axis coordinates. Returns a 3-tuple of the form:

(transform, valign, halign)

where valign and halign are requested alignments for the text.

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_xaxis_transform(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(pad)

Get the transformation used for drawing y-axis labels, which will add the given amount of padding (in points) between the axes and the label. The x-direction is in axis coordinates and the y-direction is in data coordinates. Returns a 3-tuple of the form:

(transform, valign, halign)

where valign and halign are requested alignments for the text.

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_text2_transform(pad)

Get the transformation used for drawing the secondary y-axis labels, which will add the given amount of padding (in points) between the axes and the label. The x-direction is in axis coordinates and the y-direction is in data coordinates. Returns a 3-tuple of the form:

(transform, valign, halign)

where valign and halign are requested alignments for the text.

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_transform(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(radii, labels=None, angle=None, fmt=None, **kwargs)

Set the radial locations and labels of the r grids.

The labels will appear at radial distances radii at the given angle in degrees.

labels, if not None, is a len(radii) list of strings of the labels to use at each radius.

If labels is None, the built-in formatter will be used.

Return value is a list of tuples (line, label), where line is Line2D instances and the label is Text instances.

kwargs are optional text properties for the labels:

Property	Description
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 (0.0 transparent through 1.0 opaque)
animated	bool
backgroundcolor	any matplotlib color
bbox	FancyBboxPatch prop dict
clip_box	a matplotlib.transforms.Bbox instance
clip_on	bool
clip_path	[ (Path, Transform) | Patch | None ]
color	any matplotlib color
contains	a callable function
family or fontfamily or fontname or name	[FONTNAME | 'serif' | 'sans-serif' | 'cursive' | 'fantasy' | 'monospace' ]
figure	a Figure instance
fontproperties or font_properties	a matplotlib.font_manager.FontProperties instance
gid	an id string
horizontalalignment or ha	[ 'center' | 'right' | 'left' ]
label	object
linespacing	float (multiple of font size)
multialignment or ma	['left' | 'right' | 'center' ]
path_effects	AbstractPathEffect
picker	[None | bool | float | callable]
position	(x,y)
rasterized	bool or None
rotation	[ angle in degrees | 'vertical' | 'horizontal' ]
rotation_mode	[ None | "default" | "anchor" ]
size or fontsize	[size in points | 'xx-small' | 'x-small' | 'small' | 'medium' | 'large' | 'x-large' | 'xx-large' ]
sketch_params	(scale: float, length: float, randomness: float)
snap	bool or None
stretch or fontstretch	[a numeric value in range 0-1000 | 'ultra-condensed' | 'extra-condensed' | 'condensed' | 'semi-condensed' | 'normal' | 'semi-expanded' | 'expanded' | 'extra-expanded' | 'ultra-expanded' ]
style or fontstyle	[ 'normal' | 'italic' | 'oblique']
text	string or anything printable with '%s' conversion.
transform	Transform
url	a url string
usetex	bool or None
variant or fontvariant	[ 'normal' | 'small-caps' ]
verticalalignment or va	[ 'center' | 'top' | 'bottom' | 'baseline' ]
visible	bool
weight or fontweight	[a numeric value in range 0-1000 | 'ultralight' | 'light' | 'normal' | 'regular' | 'book' | 'medium' | 'roman' | 'semibold' | 'demibold' | 'demi' | 'bold' | 'heavy' | 'extra bold' | 'black' ]
wrap	bool
x	float
y	float
zorder	float

ACCEPTS: sequence of floats

set_rlabel_position(value)

Updates the theta position of the radius labels.

Parameters:

value : number

The angular position of the radius labels in degrees.

set_rlim(*args, **kwargs)

set_rmax(rmax)

set_rmin(rmin)

set_rorigin(rorigin)

set_rscale(*args, **kwargs)

set_rticks(*args, **kwargs)

set_theta_direction(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(offset)

Set the offset for the location of 0 in radians.

set_theta_zero_location(loc, offset=0.0)

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

loc : str

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

offset : float, 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(angles, labels=None, frac=None, fmt=None, **kwargs)

Set the angles at which to place the theta grids (these gridlines are equal along the theta dimension). angles is in degrees.

labels, if not None, is a len(angles) list of strings of the labels to use at each angle.

If labels is None, the labels will be fmt % angle

frac is the fraction of the polar axes radius at which to place the label (1 is the edge). e.g., 1.05 is outside the axes and 0.95 is inside the axes.

Return value is a list of tuples (line, label), where line is Line2D instances and the label is Text instances.

kwargs are optional text properties for the labels:

Property	Description
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 (0.0 transparent through 1.0 opaque)
animated	bool
backgroundcolor	any matplotlib color
bbox	FancyBboxPatch prop dict
clip_box	a matplotlib.transforms.Bbox instance
clip_on	bool
clip_path	[ (Path, Transform) | Patch | None ]
color	any matplotlib color
contains	a callable function
family or fontfamily or fontname or name	[FONTNAME | 'serif' | 'sans-serif' | 'cursive' | 'fantasy' | 'monospace' ]
figure	a Figure instance
fontproperties or font_properties	a matplotlib.font_manager.FontProperties instance
gid	an id string
horizontalalignment or ha	[ 'center' | 'right' | 'left' ]
label	object
linespacing	float (multiple of font size)
multialignment or ma	['left' | 'right' | 'center' ]
path_effects	AbstractPathEffect
picker	[None | bool | float | callable]
position	(x,y)
rasterized	bool or None
rotation	[ angle in degrees | 'vertical' | 'horizontal' ]
rotation_mode	[ None | "default" | "anchor" ]
size or fontsize	[size in points | 'xx-small' | 'x-small' | 'small' | 'medium' | 'large' | 'x-large' | 'xx-large' ]
sketch_params	(scale: float, length: float, randomness: float)
snap	bool or None
stretch or fontstretch	[a numeric value in range 0-1000 | 'ultra-condensed' | 'extra-condensed' | 'condensed' | 'semi-condensed' | 'normal' | 'semi-expanded' | 'expanded' | 'extra-expanded' | 'ultra-expanded' ]
style or fontstyle	[ 'normal' | 'italic' | 'oblique']
text	string or anything printable with '%s' conversion.
transform	Transform
url	a url string
usetex	bool or None
variant or fontvariant	[ 'normal' | 'small-caps' ]
verticalalignment or va	[ 'center' | 'top' | 'bottom' | 'baseline' ]
visible	bool
weight or fontweight	[a numeric value in range 0-1000 | 'ultralight' | 'light' | 'normal' | 'regular' | 'book' | 'medium' | 'roman' | 'semibold' | 'demibold' | 'demi' | 'bold' | 'heavy' | 'extra bold' | 'black' ]
wrap	bool
x	float
y	float
zorder	float

ACCEPTS: sequence of floats

set_thetalim(*args, **kwargs)

set_thetamax(thetamax)

set_thetamin(thetamin)

set_xscale(scale, *args, **kwargs)

Set the x-axis scale.

Parameters:

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

scaling strategy to apply

See also

matplotlib.scale.LinearScale

linear transform

matplotlib.scale.LogTransform

log transform

matplotlib.scale.SymmetricalLogTransform

symlog transform

matplotlib.scale.LogisticTransform

logit transform

Notes

Different kwargs are accepted, depending on the scale. See the scale module for more information.

set_yscale(*args, **kwargs)

Set the y-axis scale.

Parameters:

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

scaling strategy to apply

See also

matplotlib.scale.LinearScale

linear transform

matplotlib.scale.LogTransform

log transform

matplotlib.scale.SymmetricalLogTransform

symlog transform

matplotlib.scale.LogisticTransform

logit transform

Notes

Different kwargs are accepted, depending on the scale. See the scale module for more information.

start_pan(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.

input_dims = 2

inverted()

Return the corresponding inverse transformation.

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.

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

is_separable = False

output_dims = 2

transform_non_affine(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.

Accepts a numpy array of shape (N x input_dims) and returns a numpy array of shape (N x output_dims).

Alternatively, accepts a numpy array of length input_dims and returns a numpy array of length output_dims.

transform_path_non_affine(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.

axis_name = 'radius'

cla()

clear the current 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()

autoscale the view limits

pan(numsteps)

Pan numticks (can be positive or negative)

refresh()

refresh internal information based on current lim

view_limits(vmin, vmax)

select a scale for the range from vmin to vmax

Normally this method is overridden by subclasses to change locator behaviour.

zoom(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(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.

Init the axis with the parent Axes instance

axis_name = 'theta'

cla()

clear the current 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()

autoscale the view limits

pan(numsteps)

Pan numticks (can be positive or negative)

refresh()

refresh internal information based on current lim

set_axis(axis)

view_limits(vmin, vmax)

select a scale for the range from vmin to vmax

Normally this method is overridden by subclasses to change locator behaviour.

zoom(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.

update_position(loc)

Set the location of tick in data coords with scalar loc