Axes

class Axes(*args, **kwargs)

Bases: _ExternalModeMixin, Axes

The lowest-level Axes subclass used by ultraplot. Implements basic universal features.

Parameters:

• *args – Passed to matplotlib.axes.Axes.

• title (str or sequence, optional) – The axes title. Can optionally be a sequence strings, in which case the title will be selected from the sequence according to number.

• abc (bool or str or sequence, default: rc.abc = False) – The “a-b-c” subplot label style. Must contain the character a or A, for example 'a.', or 'A'. If True then the default style of 'a' is used. The a or A is replaced with the alphabetic character matching the number. If number is greater than 26, the characters loop around to a, …, z, aa, …, zz, aaa, …, zzz, etc. Can also be a sequence of strings, in which case the “a-b-c” label will be selected sequentially from the list. For example axs.format(abc = ["X", "Y"]) for a two-panel figure, and axes[3:5].format(abc = ["X", "Y"]) for a two-panel subset of a larger figure.

• abcloc, titleloc (str, default: rc['abc.loc'] = 'left', rc['title.loc'] = 'center') – Strings indicating the location for the a-b-c label and main title. The following locations are valid:

  Location	Valid keys
  center above axes	'center', 'c'
  left above axes	'left', 'l'
  right above axes	'right', 'r'
  lower center inside axes	'lower center', 'lc'
  upper center inside axes	'upper center', 'uc'
  upper right inside axes	'upper right', 'ur'
  upper left inside axes	'upper left', 'ul'
  lower left inside axes	'lower left', 'll'
  lower right inside axes	'lower right', 'lr'
  left of y axis	'outer left', 'ol'
  right of y axis	'outer right', 'or'

• abcborder, titleborder (bool, default: rc['abc.border'] = True and rc['title.border'] = True) – Whether to draw a white border around titles and a-b-c labels positioned inside the axes. This can help them stand out on top of artists plotted inside the axes.

• abcbbox, titlebbox (bool, default: rc['abc.bbox'] = False and rc['title.bbox'] = False) – Whether to draw a white bbox around titles and a-b-c labels positioned inside the axes. This can help them stand out on top of artists plotted inside the axes.

• abcpad (float or unit-spec, default: rc['abc.pad']) – Horizontal offset to shift the a-b-c label position. Positive values move the label right, negative values move it left. This is separate from abctitlepad, which controls spacing between abc and title when co-located. If float, units are points. If string, interpreted by units.

• abc_kw, title_kw (dict-like, optional) – Additional settings used to update the a-b-c label and title with text.update().

• titlepad (float, default: rc['title.pad'] = 5.0) – The padding for the inner and outer titles and a-b-c labels. If float, units are points. If string, interpreted by units.

• titleabove (bool, default: rc['title.above'] = True) – Whether to try to put outer titles and a-b-c labels above panels, colorbars, or legends that are above the axes.

• abctitlepad (float, default: rc['abc.titlepad'] = 4.0) – The horizontal padding between a-b-c labels and titles in the same location. If float, units are points. If string, interpreted by units.

• ltitle, ctitle, rtitle, ultitle, uctitle, urtitle, lltitle, lctitle, lrtitle (str or sequence, :py:class:`optional `) – Shorthands for the below keywords. lefttitle, centertitle, righttitle, upperlefttitle, uppercentertitle, upperrighttitle : str or sequence, optional

• lowerlefttitle, lowercentertitle, lowerrighttitle (str or sequence, optional) – Additional titles in specific positions (see title for details). This works as an alternative to the ax.format(title='Title', titleloc=loc) workflow and permits adding more than one title-like label for a single axes.

• a, alpha, fc, facecolor, ec, edgecolor, lw, linewidth, ls, linestyle (**default* *) – rc['axes.alpha'] = None (default: 1.0), rc['axes.facecolor'] = 'white' (default: white), rc['axes.edgecolor'] = 'black' (default: black), rc['axes.linewidth'] = 0.6 (default: 0.6), - Additional settings applied to the background patch, and their shorthands. Their defaults values are the 'axes' properties.

Other Parameters:

• rc_mode (int, optional) – The context mode passed to context.

• rc_kw (dict-like, optional) – An alternative to passing extra keyword arguments. See below.

• **kwargs – Remaining keyword arguments are passed to matplotlib.axes.Axes.n Keyword arguments that match the name of an rc setting are passed to ultraplot.config.Configurator.context and used to update the axes. If the setting name has “dots” you can simply omit the dots. For example, abc='A.' modifies the rc.abc setting, titleloc='left' modifies the rc['title.loc'] setting, gridminor=True modifies the rc.gridminor setting, and gridbelow=True modifies the rc['grid.below'] setting. Many of the keyword arguments documented above are internally applied by retrieving settings passed to context.

See also

Axes.format, matplotlib.axes.Axes, ultraplot.axes.PlotAxes, ultraplot.axes.CartesianAxes, ultraplot.axes.PolarAxes, ultraplot.axes.GeoAxes, ultraplot.figure.Figure.subplot, ultraplot.figure.Figure.add_subplot

Attributes Summary

number

The axes number.

Methods Summary

colorbar(**kwargs)	Add an inset colorbar or an outer colorbar along the edge of the axes.
draw([renderer])	Draw the Artist (and its children) using the given renderer.
format()	Modify the a-b-c label, axes title(s), and background patch, and call ultraplot.figure.Figure.format on the axes figure.
get_center_of_axes([axes])
get_default_bbox_extra_artists()	Return a default list of artists that are used for the bounding box calculation.
get_tightbbox(renderer, *args, **kwargs)	Return the tight bounding box of the Axes, including axis and their decorators (xlabel, title, etc).
indicate_inset_zoom(**kwargs)	Add indicators denoting the zoom range of the inset axes.
inset(*args, **kwargs)	Add an inset axes.
inset_axes(*args, **kwargs)	Add an inset axes.
legend(**kwargs)	Add an inset legend or outer legend along the edge of the axes.
panel([side])	Add a panel axes.
panel_axes([side])	Add a panel axes.
set(*[, adjustable, agg_filter, alpha, ...])	Set multiple properties at once.
set_prop_cycle(*args, **kwargs)	Set the property cycle of the Axes.
text(**kwargs)	Add text to the axes.

Attributes Documentation

number

The axes number. This controls the order of a-b-c labels and the order of appearance in the SubplotGrid returned by subplots.

Methods Documentation

colorbar(**kwargs)

Add an inset colorbar or an outer colorbar along the edge of the axes.

mappable : mappable, colormap-spec, sequence of color-spec,

or sequence of Artist

There are four options here:

1. A ScalarMappable (e.g., an object returned by contourf or pcolormesh).

2. A Colormap or registered colormap name used to build a ScalarMappable on-the-fly. The colorbar range and ticks depend on the arguments values, vmin, vmax, and norm. The default for a ContinuousColormap is vmin=0 and vmax=1 (note that passing values will “discretize” the colormap). The default for a DiscreteColormap is values=np.arange(0, cmap.N).

3. A sequence of hex strings, color names, or RGB[A] tuples. A DiscreteColormap will be generated from these colors and used to build a ScalarMappable on-the-fly. The colorbar range and ticks depend on the arguments values, norm, and norm_kw. The default is values=np.arange(0, len(mappable)).

4. A sequence of matplotlib.artist.Artist instances (e.g., a list of Line2D instances returned by plot). A colormap will be generated from the colors of these objects (where the color is determined by get_color, if available, or get_facecolor). The colorbar range and ticks depend on the arguments values, norm, and norm_kw. The default is to infer colorbar ticks and tick labels by calling get_label on each artist.

valuessequence of float or str, optional

Ignored if mappable is a ScalarMappable. This maps the colormap colors to numeric values using DiscreteNorm. If the colormap is a ContinuousColormap then its colors will be “discretized”. These These can also be strings, in which case the list indices are used for tick locations and the strings are applied as tick labels.

loc, locationint or str, default: rc['colorbar.loc'] = 'right'

The colorbar location. Valid location keys are shown in the below table.

Location	Valid keys
outer left	'left', 'l'
outer right	'right', 'r'
outer bottom	'bottom', 'b'
outer top	'top', 't'
default inset	'best', 'inset', 'i', 0
upper right inset	'upper right', 'ur', 1
upper left inset	'upper left', 'ul', 2
lower left inset	'lower left', 'll', 3
lower right inset	'lower right', 'lr', 4
“filled”	'fill'

shrink

Alias for length. This is included for consistency with matplotlib.figure.Figure.colorbar.

length

: float or unit-spec, default: rc['colorbar.length'] = 1.0 or rc['colorbar.insetlength'] = 8.0

The colorbar length. For outer colorbars, units are relative to the axes width or height (default is rc['colorbar.length']). For inset colorbars, floats interpreted as em-widths and strings interpreted by units (default is rc['colorbar.insetlength']).

widthunit-spec, default: rc['colorbar.width'] = 0.2 or rc['colorbar.insetwidth'] = 1.2

The colorbar width. For outer colorbars, floats are interpreted as inches (default is rc['colorbar.width']). For inset colorbars, floats are interpreted as em-widths (default is rc['colorbar.insetwidth']). Strings are interpreted by units.

queue : bool, optional

If True and loc is the same as an existing colorbar, the input arguments are added to a queue and this function returns None. This is used to “update” the same colorbar with successive ax.colorbar(...) calls. If False (the default) and loc is the same as an existing inset colorbar, the old colorbar is removed. If False and loc is an outer colorbar, the colorbars are “stacked”.

spaceunit-spec, default: None

For outer colorbars only. The fixed space between the colorbar and the subplot edge. If float, units are em-widths. If string, interpreted by units. When the tight layout algorithm is active for the figure, space is computed automatically (see pad). Otherwise, space is set to a suitable default.

padunit-spec, default: rc['subplots.panelpad'] = 0.5 or rc['colorbar.insetpad'] = 0.7

For outer colorbars, this is the tight layout padding between the colorbar and the subplot (default is rc['subplots.panelpad']). For inset colorbars, this is the fixed space between the axes edge and the colorbar (default is rc['colorbar.insetpad']). If float, units are em-widths. If string, interpreted by units.

align{‘center’, ‘top’, ‘bottom’, ‘left’, ‘right’, ‘t’, ‘b’, ‘l’, ‘r’}, optional

For outer colorbars only. How to align the colorbar against the subplot edge. The values 'top' and 'bottom' are valid for left and right colorbars and 'left' and 'right' are valid for top and bottom colorbars. The default is always 'center'.

Has no visible effect if length is 1.

orientation : {None, ‘horizontal’, ‘vertical’}, optional

The colorbar orientation. By default this depends on the “side” of the subplot or figure where the colorbar is drawn. Inset colorbars are always horizontal.

normnorm-spec, optional

Ignored if mappable is a ScalarMappable. This is the continuous normalizer used to scale the ContinuousColormap (or passed to DiscreteNorm if values was passed). Passed to the Norm constructor function.

norm_kwdict-like, optional

Ignored if mappable is a ScalarMappable. These are the normalizer keyword arguments. Passed to Norm.

vmin, vmaxfloat, optional

Ignored if mappable is a ScalarMappable. These are the minimum and maximum colorbar values. Passed to Norm.

label, titlestr, optional

The colorbar label. The title keyword is also accepted for consistency with legend.

reversebool, optional

Whether to reverse the direction of the colorbar. This is done automatically when descending levels are used with DiscreteNorm.

rotationfloat, default: 0

The tick label rotation.

grid, edges, drawedgesbool, default: rc['colorbar.grid'] = False

Whether to draw “grid” dividers between each distinct color.

extend{‘neither’, ‘both’, ‘min’, ‘max’}, optional

Direction for drawing colorbar “extensions” (i.e. color keys for out-of-bounds data on the end of the colorbar). Default behavior is to use the value of extend passed to the plotting command or use 'neither' if the value is unknown.

extendfracfloat, optional

The length of the colorbar “extensions” relative to the length of the colorbar. This is a native matplotlib colorbar keyword.

extendsizeunit-spec, default: rc['colorbar.extend'] = 1.3 or rc['colorbar.insetextend'] = 0.9

The length of the colorbar “extensions” in physical units. Default is rc['colorbar.extend'] for outer colorbars and rc['colorbar.insetextend'] for inset colorbars. If float, units are em-widths. If string, interpreted by units.

extendrectbool, default: False

Whether to draw colorbar “extensions” as rectangles. If False then the extensions are drawn as triangles.

locator, tickslocator-spec, optional

Used to determine the colorbar tick positions. Passed to the Locator constructor function. By default AutoLocator is used for continuous color levels and DiscreteLocator is used for discrete color levels.

locator_kwdict-like, optional

Keyword arguments passed to matplotlib.ticker.Locator class.

minorlocator, minorticks

As with locator, ticks but for the minor ticks. By default AutoMinorLocator is used for continuous color levels and DiscreteLocator is used for discrete color levels.

minorlocator_kw

As with locator_kw, but for the minor ticks.

format, formatter, ticklabelsformatter-spec, optional

The tick label format. Passed to the Formatter constructor function.

formatter_kwdict-like, optional

Keyword arguments passed to matplotlib.ticker.Formatter class.

frame, frameonbool, default: rc['colorbar.frameon'] = True

For inset colorbars only. Indicates whether to draw a “frame”, just like legend.

tickminorbool, optional

Whether to add minor ticks using minorticks_on.

tickloc, ticklocation{‘bottom’, ‘top’, ‘left’, ‘right’}, optional

Where to draw tick marks on the colorbar. Default is toward the outside of the subplot for outer colorbars and 'bottom' for inset colorbars.

tickdir, tickdirection{‘out’, ‘in’, ‘inout’}, default: rc['tick.dir'] = 'out'

Direction of major and minor colorbar ticks.

ticklenunit-spec, default: rc['tick.len'] = 4.0

Major tick lengths for the colorbar ticks.

ticklenratiofloat, default: rc['tick.lenratio'] = 0.5

Relative scaling of ticklen used to determine minor tick lengths.

tickwidthunit-spec, default: linewidth

Major tick widths for the colorbar ticks. or rc['tick.width'] = 0.6 if linewidth was not passed.

tickwidthratiofloat, default: rc['tick.widthratio'] = 0.8

Relative scaling of tickwidth used to determine minor tick widths.

ticklabelcolor, ticklabelsize, ticklabelweight : default: rc['tick.labelcolor'] = 'black', rc['tick.labelsize'] = 'medium', rc['tick.labelweight'] = 'normal'.

The font color, size, and weight for colorbar tick labels

labelloc, labellocation{‘bottom’, ‘top’, ‘left’, ‘right’}

The colorbar label location. Inherits from tickloc by default. Default is toward the outside of the subplot for outer colorbars and 'bottom' for inset colorbars.

labelcolor, labelsize, labelweight : default: rc['label.color'] = 'black', rc['label.size'] = 'medium', and rc['label.weight'] = 'normal'.

The font color, size, and weight for the colorbar label.

a, alpha, framealpha, fc, facecolor, framecolor, ec, edgecolor, ew, edgewidth : default: rc['colorbar.framealpha'] = 0.8, rc['colorbar.framecolor']

For inset colorbars only. Controls the transparency and color of the background frame.

lw, linewidth, c, coloroptional

Controls the line width and edge color for both the colorbar outline and the level dividers.

edgefixbool or float, default: rc.edgefix = True

Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). See this github repo for a demonstration of the problem. If True, a small default linewidth of 0.3 is used to cover up the white lines. If float (e.g. edgefix=0.5), this specific linewidth is used to cover up the white lines. This feature is automatically disabled when the patches have transparency.

rasterizebool, default: rc['colorbar.rasterize'] = False

Whether to rasterize the colorbar solids. The matplotlib default was True but ultraplot changes this to False since rasterization can cause misalignment between the color patches and the colorbar outline.

outlinebool, None defaultNone

Controls the visibility of the frame. When set to False, the spines of the colorbar are hidden. If set to None it uses the rc['colorbar.outline'] value.

labelrotationstr, float, default: None

Controls the rotation of the colorbar label. When set to None it takes on the value of rc["colorbar.labelrotation"]. When set to auto it produces a sensible default where the rotation is adjusted to where the colorbar is located. For example, a horizontal colorbar with a label to the left or right will match the horizontal alignment and rotate the label to 0 degrees. Users can provide a float to rotate to any arbitrary angle.

**kwargs

Passed to colorbar.

ultraplot.figure.Figure.colorbar matplotlib.figure.Figure.colorbar

draw(renderer=None, *args, **kwargs)

Draw the Artist (and its children) using the given renderer.

This has no effect if the artist is not visible (Artist.get_visible returns False).

Parameters:

renderer (RendererBase subclass.)

Notes

This method is overridden in the Artist subclasses.

format()

Modify the a-b-c label, axes title(s), and background patch, and call ultraplot.figure.Figure.format on the axes figure.

Parameters:

• title (str or sequence, optional) – The axes title. Can optionally be a sequence strings, in which case the title will be selected from the sequence according to number.

• abc (bool or str or sequence, default: rc.abc = False) – The “a-b-c” subplot label style. Must contain the character a or A, for example 'a.', or 'A'. If True then the default style of 'a' is used. The a or A is replaced with the alphabetic character matching the number. If number is greater than 26, the characters loop around to a, …, z, aa, …, zz, aaa, …, zzz, etc. Can also be a sequence of strings, in which case the “a-b-c” label will be selected sequentially from the list. For example axs.format(abc = ["X", "Y"]) for a two-panel figure, and axes[3:5].format(abc = ["X", "Y"]) for a two-panel subset of a larger figure.

• abcloc, titleloc (str, default: rc['abc.loc'] = 'left', rc['title.loc'] = 'center') – Strings indicating the location for the a-b-c label and main title. The following locations are valid:

  Location	Valid keys
  center above axes	'center', 'c'
  left above axes	'left', 'l'
  right above axes	'right', 'r'
  lower center inside axes	'lower center', 'lc'
  upper center inside axes	'upper center', 'uc'
  upper right inside axes	'upper right', 'ur'
  upper left inside axes	'upper left', 'ul'
  lower left inside axes	'lower left', 'll'
  lower right inside axes	'lower right', 'lr'
  left of y axis	'outer left', 'ol'
  right of y axis	'outer right', 'or'

• abcborder, titleborder (bool, default: rc['abc.border'] = True and rc['title.border'] = True) – Whether to draw a white border around titles and a-b-c labels positioned inside the axes. This can help them stand out on top of artists plotted inside the axes.

• abcbbox, titlebbox (bool, default: rc['abc.bbox'] = False and rc['title.bbox'] = False) – Whether to draw a white bbox around titles and a-b-c labels positioned inside the axes. This can help them stand out on top of artists plotted inside the axes.

• abcpad (float or unit-spec, default: rc['abc.pad']) – Horizontal offset to shift the a-b-c label position. Positive values move the label right, negative values move it left. This is separate from abctitlepad, which controls spacing between abc and title when co-located. If float, units are points. If string, interpreted by units.

• abc_kw, title_kw (dict-like, optional) – Additional settings used to update the a-b-c label and title with text.update().

• titlepad (float, default: rc['title.pad'] = 5.0) – The padding for the inner and outer titles and a-b-c labels. If float, units are points. If string, interpreted by units.

• titleabove (bool, default: rc['title.above'] = True) – Whether to try to put outer titles and a-b-c labels above panels, colorbars, or legends that are above the axes.

• abctitlepad (float, default: rc['abc.titlepad'] = 4.0) – The horizontal padding between a-b-c labels and titles in the same location. If float, units are points. If string, interpreted by units.

• ltitle, ctitle, rtitle, ultitle, uctitle, urtitle, lltitle, lctitle, lrtitle (str or sequence, :py:class:`optional `) – Shorthands for the below keywords. lefttitle, centertitle, righttitle, upperlefttitle, uppercentertitle, upperrighttitle : str or sequence, optional

• lowerlefttitle, lowercentertitle, lowerrighttitle (str or sequence, optional) – Additional titles in specific positions (see title for details). This works as an alternative to the ax.format(title='Title', titleloc=loc) workflow and permits adding more than one title-like label for a single axes.

• a, alpha, fc, facecolor, ec, edgecolor, lw, linewidth, ls, linestyle (**default* *) – rc['axes.alpha'] = None (default: 1.0), rc['axes.facecolor'] = 'white' (default: white), rc['axes.edgecolor'] = 'black' (default: black), rc['axes.linewidth'] = 0.6 (default: 0.6), - Additional settings applied to the background patch, and their shorthands. Their defaults values are the 'axes' properties.

Important

abc, abcloc, titleloc, titleabove, titlepad, and abctitlepad are actually configuration settings. We explicitly document these arguments here because it is common to change them for specific axes. But many other configuration settings can be passed to format too.

Other Parameters:

• rowlabels, collabels, llabels, tlabels, rlabels, blabels – Aliases for leftlabels and toplabels, and for leftlabels, toplabels, rightlabels, and bottomlabels, respectively.

• leftlabels, toplabels, rightlabels, bottomlabels (sequence of str, optional) – Labels for the subplots lying along the left, top, right, and bottom edges of the figure. The length of each list must match the number of subplots along the corresponding edge.

• leftlabelpad, toplabelpad, rightlabelpad, bottomlabelpad (float or unit-spec, default )

• rc['leftlabel.pad'] = 5.0, rc['toplabel.pad'] = 5.0, rc['rightlabel.pad'] = 5.0, rc['bottomlabel.pad'] = 5.0 – The padding between the labels and the axes content. If float, units are points. If string, interpreted by units.

• leftlabels_kw, toplabels_kw, rightlabels_kw, bottomlabels_kw (dict-like, optional) – Additional settings used to update the labels with text.update().

• figtitle – Alias for suptitle.

• suptitle (str, optional) – The figure “super” title, centered between the left edge of the leftmost subplot and the right edge of the rightmost subplot.

• suptitlepad (float, default: rc['suptitle.pad'] = 5.0) – The padding between the super title and the axes content. If float, units are points. If string, interpreted by units.

• suptitle_kw (optional) – Additional settings used to update the super title with text.update().

• includepanels (bool, default: False) – Whether to include panels when aligning figure “super titles” along the top of the subplot grid and when aligning the spanx x axis labels and spany y axis labels along the sides of the subplot grid.

• rc_mode (int, optional) – The context mode passed to context.

• rc_kw (dict-like, optional) – An alternative to passing extra keyword arguments. See below.

• **kwargs – Keyword arguments that match the name of an rc setting are passed to ultraplot.config.Configurator.context and used to update the axes. If the setting name has “dots” you can simply omit the dots. For example, abc='A.' modifies the rc.abc setting, titleloc='left' modifies the rc['title.loc'] setting, gridminor=True modifies the rc.gridminor setting, and gridbelow=True modifies the rc['grid.below'] setting. Many of the keyword arguments documented above are internally applied by retrieving settings passed to context.

See also

ultraplot.axes.CartesianAxes.format, ultraplot.axes.PolarAxes.format, ultraplot.axes.GeoAxes.format, ultraplot.figure.Figure.format, ultraplot.gridspec.SubplotGrid.format, ultraplot.config.Configurator.context

static get_center_of_axes(axes=None)

get_default_bbox_extra_artists()

Return a default list of artists that are used for the bounding box calculation.

Artists are excluded either by not being visible or artist.set_in_layout(False).

get_tightbbox(renderer, *args, **kwargs)

Return the tight bounding box of the Axes, including axis and their decorators (xlabel, title, etc).

Artists that have artist.set_in_layout(False) are not included in the bbox.

Parameters:

• renderer (RendererBase subclass) – renderer that will be used to draw the figures (i.e. fig.canvas.get_renderer())

• bbox_extra_artists (list of Artist or None) – List of artists to include in the tight bounding box. If None (default), then all artist children of the Axes are included in the tight bounding box.

• call_axes_locator (bool, default: True) – If call_axes_locator is False, it does not call the _axes_locator attribute, which is necessary to get the correct bounding box. call_axes_locator=False can be used if the caller is only interested in the relative size of the tightbbox compared to the Axes bbox.

• for_layout_only (default: False) – The bounding box will not include the x-extent of the title and the xlabel, or the y-extent of the ylabel.

Returns:

BboxBase – Bounding box in figure pixel coordinates.

See also

matplotlib.axes.Axes.get_window_extent, matplotlib.axis.Axis.get_tightbbox, matplotlib.spines.Spine.get_window_extent

indicate_inset_zoom(**kwargs)

Add indicators denoting the zoom range of the inset axes. This will replace previously drawn zoom indicators.

Parameters:

• lw, linewidth, linewidths (unit-spec, default: rc['patch.linewidth'] = 0.6) – The edge width of the patch(es). If float, units are points. If string, interpreted by units.

• ls, linestyle, linestyles (str, default: '-') – The edge style of the patch(es).

• ec, edgecolor, edgecolors (color-spec, default: 'none') – The edge color of the patch(es).

• fc, facecolor, facecolors, fillcolor, fillcolors (color-spec, optional) – The face color of the patch(es). The property cycle is used by default.

• a, alpha, alphas (float, optional) – The opacity of the patch(es). Inferred from facecolor and edgecolor by default.

• zorder (float, default: 3.5) – The zorder of the indicators. Should be greater than the zorder of elements in the parent axes.

Other Parameters:

**kwargs – Passed to Patch.

Note

This command must be called from the inset axes rather than the parent axes. It is called automatically when zoom=True is passed to inset_axes and whenever the axes are drawn (so the line positions always track the axis limits even if they are later changed).

See also

matplotlib.axes.Axes.indicate_inset, matplotlib.axes.Axes.indicate_inset_zoom

inset(*args, **kwargs)

Add an inset axes. This is similar to matplotlib.axes.Axes.inset_axes.

Parameters:

• bounds (4-tuple of float) – The (left, bottom, width, height) coordinates for the axes.

• transform ({'data', 'axes', 'figure', 'subfigure'} )

• or `~matplotlib.transforms.Transform`, optional – The transform used to interpret the bounds. Can be a Transform instance or a string representing the transData, transAxes, transFigure, or transSubfigure, transforms. Default is to use the same projection as the current axes.

• proj, projection (:py:class:``)

• str, `cartopy.crs.Projection`, or `~mpl_toolkits.basemap.Basemap`, optional – The map projection specification(s). If 'cart' or 'cartesian' (the default), a CartesianAxes is created. If 'polar', a PolarAxes is created. Otherwise, the argument is interpreted by Proj, and the result is used to make a GeoAxes (in this case the argument can be a cartopy.crs.Projection instance, a Basemap instance, or a projection name listed in this table).

• proj_kw, projection_kw (dict-like, optional) – Keyword arguments passed to Basemap or cartopy Projection classes on instantiation.

• backend ({'cartopy', 'basemap'}, default: rc['geo.backend'] = 'cartopy') – Whether to use Basemap or Projection for map projections.

• zorder (float, default: 4) – The zorder of the axes. Should be greater than the zorder of elements in the parent axes.

• zoom (bool, default: True or False) – Whether to draw lines indicating the inset zoom using indicate_inset_zoom. The line positions will automatically adjust when the parent or inset axes limits change. Default is True only if both axes are CartesianAxes.

• zoom_kw (dict, optional) – Passed to indicate_inset_zoom.

Other Parameters:

**kwargs – Passed to ultraplot.axes.Axes.

Returns:

ultraplot.axes.Axes – The inset axes.

See also

Axes.indicate_inset_zoom, matplotlib.axes.Axes.inset_axes, matplotlib.axes.Axes.indicate_inset, matplotlib.axes.Axes.indicate_inset_zoom

inset_axes(*args, **kwargs)

Add an inset axes. This is similar to matplotlib.axes.Axes.inset_axes.

Parameters:

• bounds (4-tuple of float) – The (left, bottom, width, height) coordinates for the axes.

• transform ({'data', 'axes', 'figure', 'subfigure'} )

• or `~matplotlib.transforms.Transform`, optional – The transform used to interpret the bounds. Can be a Transform instance or a string representing the transData, transAxes, transFigure, or transSubfigure, transforms. Default is to use the same projection as the current axes.

• proj, projection (:py:class:``)

• str, `cartopy.crs.Projection`, or `~mpl_toolkits.basemap.Basemap`, optional – The map projection specification(s). If 'cart' or 'cartesian' (the default), a CartesianAxes is created. If 'polar', a PolarAxes is created. Otherwise, the argument is interpreted by Proj, and the result is used to make a GeoAxes (in this case the argument can be a cartopy.crs.Projection instance, a Basemap instance, or a projection name listed in this table).

• proj_kw, projection_kw (dict-like, optional) – Keyword arguments passed to Basemap or cartopy Projection classes on instantiation.

• backend ({'cartopy', 'basemap'}, default: rc['geo.backend'] = 'cartopy') – Whether to use Basemap or Projection for map projections.

• zorder (float, default: 4) – The zorder of the axes. Should be greater than the zorder of elements in the parent axes.

• zoom (bool, default: True or False) – Whether to draw lines indicating the inset zoom using indicate_inset_zoom. The line positions will automatically adjust when the parent or inset axes limits change. Default is True only if both axes are CartesianAxes.

• zoom_kw (dict, optional) – Passed to indicate_inset_zoom.

Other Parameters:

**kwargs – Passed to ultraplot.axes.Axes.

Returns:

ultraplot.axes.Axes – The inset axes.

See also

Axes.indicate_inset_zoom, matplotlib.axes.Axes.inset_axes, matplotlib.axes.Axes.indicate_inset, matplotlib.axes.Axes.indicate_inset_zoom

legend(**kwargs)

Add an inset legend or outer legend along the edge of the axes.

Parameters:

• handles (list of artist, optional) – List of matplotlib artists, or a list of lists of artist instances (see the center keyword). If not passed, artists with valid labels (applied by passing label or labels to a plotting command or calling set_label) are retrieved automatically. If the object is a ContourSet, legend_elements is used to select the central artist in the list (generally useful for single-color contour plots). Note that ultraplot’s contour and contourf accept a legend label keyword argument.

• labels (list of str, optional) – A matching list of string labels or None placeholders, or a matching list of lists (see the center keyword). Wherever None appears in the list (or if no labels were passed at all), labels are retrieved by calling get_label on each Artist in the handle list. If a handle consists of a tuple group of artists, labels are inferred from the artists in the tuple (if there are multiple unique labels in the tuple group of artists, the tuple group is expanded into unique legend entries – otherwise, the tuple group elements are drawn on top of eachother). For details on matplotlib legend handlers and tuple groups, see the matplotlib `legend guide

• -<https (:py:class:`//matplotlib.org/stable/tutorials/intermediate/legend_guide.html>`__.`)

• loc, location (int or str, default: rc['legend.loc'] = 'best') – The legend location. Valid location keys are shown in the below table.

  Location	Valid keys
  outer left	'left', 'l'
  outer right	'right', 'r'
  outer bottom	'bottom', 'b'
  outer top	'top', 't'
  “best” inset	'best', 'inset', 'i', 0
  upper right inset	'upper right', 'ur', 1
  upper left inset	'upper left', 'ul', 2
  lower left inset	'lower left', 'll', 3
  lower right inset	'lower right', 'lr', 4
  center left inset	'center left', 'cl', 5
  center right inset	'center right', 'cr', 6
  lower center inset	'lower center', 'lc', 7
  upper center inset	'upper center', 'uc', 8
  center inset	'center', 'c', 9
  “filled”	'fill'

• width (unit-spec, optional) – For outer legends only. The space allocated for the legend box. This does nothing if the tight layout algorithm is active for the figure. If float, units are inches. If string, interpreted by units.

• queue (bool, optional) – If True and loc is the same as an existing legend, the input arguments are added to a queue and this function returns None. This is used to “update” the same legend with successive ax.legend(...) calls. If False (the default) and loc is the same as an existing inset legend, the old legend is removed. If False and loc is an outer legend, the legends are “stacked”.

• space (unit-spec, default: None) – For outer legends only. The fixed space between the legend and the subplot edge. If float, units are em-widths. If string, interpreted by units. When the tight layout algorithm is active for the figure, space is computed automatically (see pad). Otherwise, space is set to a suitable default.

• pad (unit-spec, default: rc['subplots.panelpad'] = 0.5 or rc['legend.borderaxespad'] = 0.0) – For outer legends, this is the tight layout padding between the legend and the subplot (default is rc['subplots.panelpad']). For inset legends, this is the fixed space between the axes edge and the legend (default is rc['legend.borderaxespad']). If float, units are em-widths. If string, interpreted by units.

• align ({'center', 'top', 'bottom', 'left', 'right', 't', 'b', 'l', 'r'}, optional) – For outer legends only. How to align the legend against the subplot edge. The values 'top' and 'bottom' are valid for left and right legends and 'left' and 'right' are valid for top and bottom legends. The default is always 'center'.

Other Parameters:

• frame, frameon (bool, optional) – Toggles the legend frame. For centered-row legends, a frame independent from matplotlib’s built-in legend frame is created.

• ncol, ncols (int, optional) – The number of columns. ncols is an alias, added for consistency with subplots.

• order ({'C', 'F'}, optional) – Whether legend handles are drawn in row-major ('C') or column-major ('F') order. Analagous to numpy.array ordering. The matplotlib default was 'F' but ultraplot changes this to 'C'.

• center (bool, optional) – Whether to center each legend row individually. If True, we draw successive single-row legends “stacked” on top of each other. If None, we infer this setting from handles. By default, center is set to True if handles is a list of lists (each sublist is used as a row in the legend).

• alphabetize (bool, default: False) – Whether to alphabetize the legend entries according to the legend labels.

• title, label (str, optional) – The legend title. The label keyword is also accepted, for consistency with colorbar.

• fontsize, fontweight, fontcolor (optional) – The font size, weight, and color for the legend text. Font size is interpreted by units. The default font size is rc['legend.fontsize'].

• titlefontsize, titlefontweight, titlefontcolor (optional) – The font size, weight, and color for the legend title. Font size is interpreted by units. The default size is fontsize.

• **borderpad, borderaxespad, handlelength, handleheight, handletextpad, **

• labelspacing, columnspacing (unit-spec, optional) – Various matplotlib legend spacing arguments. If float, units are em-widths. If string, interpreted by units.

• **a, alpha, framealpha, fc, facecolor, framecolor, ec, edgecolor, ew, edgewidth **

• default: rc['legend.framealpha'] = 0.8, rc['legend.facecolor'] = 'white', rc['legend.edgecolor'] = 'black', :py:class:``

• :rc:`axes.linewidth` – The opacity, face color, edge color, and edge width for the legend frame.

• c, color, lw, linewidth, m, marker, ls, linestyle, dashes, ms, markersize (optional) – Properties used to override the legend handles. For example, for a legend describing variations in line style ignoring variations in color, you might want to use color='black'.

• handle_kw (dict-like, optional) – Additional properties used to override legend handles, e.g. handle_kw={'edgecolor': 'black'}. Only line properties can be passed as keyword arguments.

• handler_map (dict-like, optional) – A dictionary mapping instances or types to a legend handler. This handler_map updates the default handler map found at matplotlib.legend.Legend.get_legend_handler_map.

• **kwargs – Passed to legend.

See also

ultraplot.figure.Figure.legend, matplotlib.axes.Axes.legend

panel(side=None, **kwargs)

Add a panel axes.

Parameters:

• side (str, optional) – The panel location. Valid location keys are as follows.

  Location	Valid keys
  left	'left', 'l'
  right	'right', 'r'
  bottom	'bottom', 'b'
  top	'top', 't'

• width (unit-spec, default: rc['subplots.panelwidth'] = 0.5) – The panel width. If float, units are inches. If string, interpreted by units.

• space (unit-spec, default: None) – The fixed space between the panel and the subplot edge. If float, units are em-widths. If string, interpreted by units. When the tight layout algorithm is active for the figure, space is computed automatically (see pad). Otherwise, space is set to a suitable default.

• pad (unit-spec, default: rc['subplots.panelpad'] = 0.5) – The tight layout padding between the panel and the subplot. If float, units are em-widths. If string, interpreted by units.

• row, rows – Aliases for span for panels on the left or right side (vertical panels).

• col, cols – Aliases for span for panels on the top or bottom side (horizontal panels).

• span (int or 2-tuple of int, default: None) – Integer(s) indicating the span of the panel across rows and columns of subplots. For panels on the left or right side, use rows or row to specify which rows the panel should span. For panels on the top or bottom side, use cols or col to specify which columns the panel should span. For example, ax.panel('b', col=1) draws a panel beneath only the leftmost column, and ax.panel('b', cols=(1, 2)) draws a panel beneath the left two columns. By default the panel will span all rows or columns aligned with the parent axes.

• share (bool, default: True) – Whether to enable axis sharing between the x and y axes of the main subplot and the panel long axes for each panel in the “stack”. Sharing between the panel short axis and other panel short axes is determined by figure-wide sharex and sharey settings.

Other Parameters:

**kwargs – Passed to ultraplot.axes.CartesianAxes. Supports all valid format keywords.

Returns:

ultraplot.axes.CartesianAxes – The panel axes.

panel_axes(side=None, **kwargs)

Add a panel axes.

Parameters:

• side (str, optional) – The panel location. Valid location keys are as follows.

  Location	Valid keys
  left	'left', 'l'
  right	'right', 'r'
  bottom	'bottom', 'b'
  top	'top', 't'

• width (unit-spec, default: rc['subplots.panelwidth'] = 0.5) – The panel width. If float, units are inches. If string, interpreted by units.

• space (unit-spec, default: None) – The fixed space between the panel and the subplot edge. If float, units are em-widths. If string, interpreted by units. When the tight layout algorithm is active for the figure, space is computed automatically (see pad). Otherwise, space is set to a suitable default.

• pad (unit-spec, default: rc['subplots.panelpad'] = 0.5) – The tight layout padding between the panel and the subplot. If float, units are em-widths. If string, interpreted by units.

• row, rows – Aliases for span for panels on the left or right side (vertical panels).

• col, cols – Aliases for span for panels on the top or bottom side (horizontal panels).

• span (int or 2-tuple of int, default: None) – Integer(s) indicating the span of the panel across rows and columns of subplots. For panels on the left or right side, use rows or row to specify which rows the panel should span. For panels on the top or bottom side, use cols or col to specify which columns the panel should span. For example, ax.panel('b', col=1) draws a panel beneath only the leftmost column, and ax.panel('b', cols=(1, 2)) draws a panel beneath the left two columns. By default the panel will span all rows or columns aligned with the parent axes.

• share (bool, default: True) – Whether to enable axis sharing between the x and y axes of the main subplot and the panel long axes for each panel in the “stack”. Sharing between the panel short axis and other panel short axes is determined by figure-wide sharex and sharey settings.

Other Parameters:

**kwargs – Passed to ultraplot.axes.CartesianAxes. Supports all valid format keywords.

Returns:

ultraplot.axes.CartesianAxes – The panel axes.

set(*, adjustable=<UNSET>, agg_filter=<UNSET>, alpha=<UNSET>, anchor=<UNSET>, animated=<UNSET>, aspect=<UNSET>, autoscale_on=<UNSET>, autoscalex_on=<UNSET>, autoscaley_on=<UNSET>, axes_locator=<UNSET>, axisbelow=<UNSET>, box_aspect=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, external=<UNSET>, facecolor=<UNSET>, forward_navigation_events=<UNSET>, frame_on=<UNSET>, gid=<UNSET>, in_layout=<UNSET>, label=<UNSET>, mouseover=<UNSET>, navigate=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, position=<UNSET>, prop_cycle=<UNSET>, rasterization_zorder=<UNSET>, rasterized=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, subplotspec=<UNSET>, title=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, xbound=<UNSET>, xlabel=<UNSET>, xlim=<UNSET>, xmargin=<UNSET>, xscale=<UNSET>, xticklabels=<UNSET>, xticks=<UNSET>, ybound=<UNSET>, ylabel=<UNSET>, ylim=<UNSET>, ymargin=<UNSET>, yscale=<UNSET>, yticklabels=<UNSET>, yticks=<UNSET>, zorder=<UNSET>)

Set multiple properties at once.

Supported properties are

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 and two offsets from the bottom left corner of the image
alpha	float or None
anchor	(float, float) or {‘C’, ‘SW’, ‘S’, ‘SE’, ‘E’, ‘NE’, …}
animated	bool
aspect	{‘auto’, ‘equal’} or float
autoscale_on	bool
autoscalex_on	unknown
autoscaley_on	unknown
axes_locator	Callable[[Axes, Renderer], Bbox]
axisbelow	bool or ‘line’
box_aspect	float or None
clip_box	BboxBase or None
clip_on	bool
clip_path	Patch or (Path, Transform) or None
external	unknown
facecolor or fc	:mpltype:`color`
figure	Figure or SubFigure
forward_navigation_events	bool or “auto”
frame_on	bool
gid	str
in_layout	bool
label	object
mouseover	bool
navigate	bool
navigate_mode	unknown
path_effects	list of 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
sketch_params	(scale: float, length: float, randomness: float)
snap	bool or None
subplotspec	unknown
title	str
transform	Transform
url	str
visible	bool
xbound	(lower: float, upper: float)
xlabel	str
xlim	(left: float, right: float)
xmargin	float greater than -0.5
xscale	unknown
xticklabels	unknown
xticks	unknown
ybound	(lower: float, upper: float)
ylabel	str
ylim	(bottom: float, top: float)
ymargin	float greater than -0.5
yscale	unknown
yticklabels	unknown
yticks	unknown
zorder	float

set_prop_cycle(*args, **kwargs)

Set the property cycle of the Axes.

The property cycle controls the style properties such as color, marker and linestyle of future plot commands. The style properties of data already added to the Axes are not modified.

Call signatures:

set_prop_cycle(cycler)
set_prop_cycle(label=values, label2=values2, ...)
set_prop_cycle(label, values)

Form 1 sets given Cycler object.

Form 2 creates a Cycler which cycles over one or more properties simultaneously and set it as the property cycle of the Axes. If multiple properties are given, their value lists must have the same length. This is just a shortcut for explicitly creating a cycler and passing it to the function, i.e. it’s short for set_prop_cycle(cycler(label=values, label2=values2, ...)).

Form 3 creates a Cycler for a single property and set it as the property cycle of the Axes. This form exists for compatibility with the original cycler.cycler interface. Its use is discouraged in favor of the kwarg form, i.e. set_prop_cycle(label=values).

Parameters:

• cycler (Cycler or None) – Set the given Cycler. None resets to the cycle defined by the current style.

• label (str) – The property key. Must be a valid Artist property. For example, ‘color’ or ‘linestyle’. Aliases are allowed, such as ‘c’ for ‘color’ and ‘lw’ for ‘linewidth’.

• values (iterable) – Finite-length iterable of the property values. These values are validated and will raise a ValueError if invalid.

See also

matplotlib.rcsetup.cycler

Convenience function for creating validated cyclers for properties.

cycler.cycler

The original function for creating unvalidated cyclers.

Examples

Setting the property cycle for a single property:

>>> ax.set_prop_cycle(color=['red', 'green', 'blue'])

Setting the property cycle for simultaneously cycling over multiple properties (e.g. red circle, green plus, blue cross):

>>> ax.set_prop_cycle(color=['red', 'green', 'blue'],
...                   marker=['o', '+', 'x'])

text(**kwargs)

Add text to the axes.

x, y, [z]float

The coordinates for the text. ThreeAxes accept an optional third coordinate. If only two are provided this automatically redirects to the text2D method.

s, textstr

The string for the text.

transform : {‘data’, ‘axes’, ‘figure’, ‘subfigure’}

or Transform, optional

The transform used to interpret the bounds. Can be a Transform instance or a string representing the transData, transAxes, transFigure, or transSubfigure, transforms.

borderbool, default: False

Whether to draw border around text.

borderwidthfloat, default: 2

The width of the text border.

bordercolorcolor-spec, default: ‘w’

The color of the text border.

borderinvertbool, optional

If True, the text and border colors are swapped.

borderstyle{‘miter’, ‘round’, ‘bevel’}, optional

The `line join style

<https://matplotlib.org/stable/gallery/lines_bars_and_markers/joinstyle.html>`__

used for the border.

bboxbool, default: False

Whether to draw a bounding box around text.

bboxcolorcolor-spec, default: ‘w’

The color of the text bounding box.

bboxstyleboxstyle, default: ‘round’

The style of the bounding box.

bboxalphafloat, default: 0.5

The alpha for the bounding box.

bboxpadfloat, default: rc['title.bboxpad'] = None

The padding for the bounding box.

name, fontname, family, fontfamily : str, optional

The font typeface name (e.g., 'Fira Math') or font family name (e.g., 'serif'). Matplotlib falls back to the system default if not found.

size, fontsizeunit-spec or str, optional

The font size. If float, units are points. If string, interpreted by units. This can also be a string indicating some scaling relative to rc['font.size']. The sizes and scalings are shown below. The scalings 'med', 'med-small', and 'med-large' are added by ultraplot while the rest are native matplotlib sizes.

Size	Scale
'xx-small'	0.579
'x-small'	0.694
'small', 'smaller'	0.833
'med-small'	0.9
'med', 'medium'	1.0
'med-large'	1.1
'large', 'larger'	1.2
'x-large'	1.440
'xx-large'	1.728
'larger'	1.2

**kwargs

Passed to matplotlib.axes.Axes.text.

matplotlib.axes.Axes.text