Figure

Bases: Figure

The Figure subclass used by ultraplot.

Parameters:

refnum (int, optional) – The reference subplot number. The refwidth, refheight, and refaspect keyword args are applied to this subplot, and the aspect ratio is conserved for this subplot in the auto_layout. The default is the first subplot created in the figure.
refaspect (float or 2-tuple of float, optional) – The reference subplot aspect ratio. If scalar, this indicates the width divided by height. If 2-tuple, this indicates the (width, height). Ignored if both figwidth and figheight or both refwidth and refheight were passed. The default value is 1 or the “data aspect ratio” if the latter is explicitly fixed (as with imshow plots and GeoAxes projections; see set_aspect()).
refwidth, refheight (unit-spec, default: rc['subplots.refwidth'] = 2.5) – The width, height of the reference subplot. If float, units are inches. If string, interpreted by units. Ignored if figwidth, figheight, or figsize was passed. If you specify just one, refaspect will be respected.
ref, aspect, axwidth, axheight – Aliases for refnum, refaspect, refwidth, refheight. These may be deprecated in a future release.
figwidth, figheight (unit-spec, optional) – The figure width and height. Default behavior is to use refwidth. If float, units are inches. If string, interpreted by units. If you specify just one, refaspect will be respected.
width, height – Aliases for figwidth, figheight.
figsize (2-tuple, optional) – Tuple specifying the figure (width, height).
sharex, sharey, share ({0, False, 1, 'labels', 'labs', 2, 'limits', 'lims', 3, True, 4, 'all'}, default: rc['subplots.share'] = True) – The axis sharing “level” for the x axis, y axis, or both axes. Options are as follows:
- 0 or False: No axis sharing. This also sets the default spanx and spany values to False.
- 1 or 'labels' or 'labs': Only draw axis labels on the bottommost row or leftmost column of subplots. Tick labels still appear on every subplot.
- 2 or 'limits' or 'lims': As above but force the axis limits, scales, and tick locations to be identical. Tick labels still appear on every subplot.
- 3 or True: As above but only show the tick labels on the bottommost row and leftmost column of subplots.
- 4 or 'all': As above but also share the axis limits, scales, and tick locations between subplots not in the same row or column.
spanx, spany, span (bool or {0, 1}, default: rc['subplots.span'] = True) – Whether to use “spanning” axis labels for the x axis, y axis, or both axes. Default is False if sharex, sharey, or share are 0 or False. When True, a single, centered axis label is used for all axes with bottom and left edges in the same row or column. This can considerably redundancy in your figure. “Spanning” labels integrate with “shared” axes. For example, for a 3-row, 3-column figure, with sharey > 1 and spany == True, your figure will have 1 y axis label instead of 9 y axis labels.
alignx, aligny, align (bool or {0, 1}, default: rc['subplots.align'] = False) – Whether to “align” axis labels for the x axis, y axis, or both axes. Aligned labels always appear in the same row or column. This is ignored if spanx, spany, or span are True.
left, right, top, bottom (unit-spec, default: None) – The fixed space between the subplots and the figure edge. If float, units are em-widths. If string, interpreted by units. If None, the space is determined automatically based on the tick and label settings. If rc['subplots.tight'] is True or tight=True was passed to the figure, the space is determined by the tight layout algorithm.
wspace, hspace, space (unit-spec, default: None) – The fixed space between grid columns, rows, or both. If float, units are em-widths. If string, interpreted by units. If None, the space is determined automatically based on the font size and axis sharing settings. If rc['subplots.tight'] is True or tight=True was passed to the figure, the space is determined by the tight layout algorithm.
tight (bool, default: :rc`subplots.tight`) – Whether automatic calls to auto_layout should include tight layout adjustments. If you manually specified a spacing in the call to subplots, it will be used to override the tight layout spacing. For example, with left=1, the left margin is set to 1 em-width, while the remaining margin widths are calculated automatically.
wequal, hequal, equal (bool, default: rc['subplots.equalspace'] = False) – Whether to make the tight layout algorithm apply equal spacing between columns, rows, or both.
wgroup, hgroup, group (bool, default: rc['subplots.groupspace'] = True) – Whether to make the tight layout algorithm just consider spaces between adjacent subplots instead of entire columns and rows of subplots.
outerpad (unit-spec, default: rc['subplots.outerpad'] = 0.5) – The scalar tight layout padding around the left, right, top, bottom figure edges. If float, units are em-widths. If string, interpreted by units.
innerpad (unit-spec, default: rc['subplots.innerpad'] = 1.0) – The scalar tight layout padding between columns and rows. Synonymous with pad. If float, units are em-widths. If string, interpreted by units.
panelpad (unit-spec, default: rc['subplots.panelpad'] = 0.5) – The scalar tight layout padding between subplots and their panels, colorbars, and legends and between “stacks” of these objects. If float, units are em-widths. If string, interpreted by units.

journal (str, optional) – String corresponding to an academic journal standard used to control the figure width figwidth and, if specified, the figure height figheight. See the below table. Feel free to add to this table by submitting a pull request.

Key	Size description	Organization
`'aaas1'`	1-column	American Association for the Advancement of Science (e.g. Science)
`'aaas2'`	2-column	”
`'agu1'`	1-column	American Geophysical Union
`'agu2'`	2-column	”
`'agu3'`	full height 1-column	”
`'agu4'`	full height 2-column	”
`'ams1'`	1-column	American Meteorological Society
`'ams2'`	small 2-column	”
`'ams3'`	medium 2-column	”
`'ams4'`	full 2-column	”
`'cop1'`	1-column	Copernicus Publications (e.g. The Cryosphere, Geoscientific Model Development)
`'cop2'`	2-column	”
`'nat1'`	1-column	Nature Research
`'nat2'`	2-column	”
`'pnas1'`	1-column	Proceedings of the National Academy of Sciences
`'pnas2'`	2-column	”
`'pnas3'`	landscape page	”

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.
**kwargs – Passed to matplotlib.figure.Figure.

Attributes Summary

`alignx`
`aligny`
`gridspec`	The single `GridSpec` instance used for all subplots in the figure.
`ref`
`sharex`
`sharey`
`spanx`
`spany`
`subplotgrid`	A `SubplotGrid` containing the numbered subplots in the figure.
`tight`

Methods Summary

`add_axes`(**kwargs)	Add a non-subplot axes to the figure.
`add_subplot`(**kwargs)	Add a subplot axes to the figure.
`add_subplots`(args, *kwargs)	Add an arbitrary grid of subplots to the figure.
`auto_layout`([renderer, aspect, tight, resize])	Automatically adjust the figure size and subplot positions.
`colorbar`(**kwargs)	Add a colorbar along the side of the figure.
`draw`(renderer)	Draw the Artist (and its children) using the given renderer.
`format`()	Modify figure-wide labels and call `format` for the input axes.
`legend`(**kwargs)	Add a legend along the side of the figure.
`save`(filename, **kwargs)	Save the figure.
`savefig`(**kwargs)	Save the figure.
`set`(*[, agg_filter, alpha, animated, ...])	Set multiple properties at once.
`set_canvas`(**kwargs)	Set the figure canvas.
`set_constrained_layout`(constrained)	[Deprecated] Set whether `constrained_layout` is used upon drawing.
`set_size_inches`(**kwargs)	Set the figure size.
`set_tight_layout`(tight)	[Deprecated] Set whether and how `Figure.tight_layout` is called when drawing.
`subplot`(args, *kwargs)	Add a subplot axes to the figure.
`subplots`(args, *kwargs)	Add an arbitrary grid of subplots to the figure.
`subplots_adjust`([left, bottom, right, top, ...])	Adjust the subplot layout parameters.
`tight_layout`(*[, pad, h_pad, w_pad, rect])	Adjust the padding between and around subplots.

Attributes Documentation

alignx

aligny

gridspec: The single GridSpec instance used for all subplots in the figure.

See also

ultraplot.figure.Figure.subplotgrid, ultraplot.gridspec.GridSpec.figure, ultraplot.gridspec.SubplotGrid.gridspec

ref

sharex

sharey

spanx

spany

subplotgrid: A SubplotGrid containing the numbered subplots in the figure. The subplots are ordered by increasing number.

See also

ultraplot.figure.Figure.gridspec, ultraplot.gridspec.SubplotGrid.figure

tight

Methods Documentation

add_axes(**kwargs)[source]

Add a non-subplot axes to the figure.

Parameters:

rect (4-tuple of float) – The (left, bottom, width, height) dimensions of the axes in figure-relative coordinates.
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.

Other Parameters:

**kwargs – Passed to the ultraplot class ultraplot.axes.CartesianAxes, ultraplot.axes.PolarAxes, ultraplot.axes.GeoAxes, or ultraplot.axes.ThreeAxes. This can include keyword arguments for projection-specific format commands.

add_subplot(**kwargs)[source]

Add a subplot axes to the figure.

Parameters:

*args (int, tuple, or SubplotSpec, optional) – The subplot location specifier. Your options are:
- A single 3-digit integer argument specifying the number of rows, number of columns, and gridspec number (using row-major indexing).
- Three positional arguments specifying the number of rows, number of columns, and gridspec number (int) or number range (2-tuple of int).
- A SubplotSpec instance generated by indexing a ultraplot GridSpec.
For integer input, the implied geometry must be compatible with the implied geometry from previous calls – for example, fig.add_subplot(331) followed by fig.add_subplot(132) is valid because the 1 row of the second input can be tiled into the 3 rows of the the first input, but fig.add_subplot(232) will raise an error because 2 rows cannot be tiled into 3 rows. For SubplotSpec input, the SubplotSpec must be derived from the GridSpec used in previous calls.

These restrictions arise because we allocate a single, unique gridspec for each figure.
number (int, optional) – The axes number used for a-b-c labeling. See format for details. By default this is incremented automatically based on the other subplots in the figure. Use e.g. number=None or number=False to ensure the subplot has no a-b-c label. Note the number corresponding to a is 1, not 0.
autoshare (bool, default: True) – Whether to automatically share the x and y axes with subplots spanning the same rows and columns based on the figure-wide sharex and sharey settings. This has no effect if rc['subplots.share'] is False or if sharex=False or sharey=False were passed to the figure.
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.

Other Parameters:

**kwargs – Passed to the ultraplot class ultraplot.axes.CartesianAxes, ultraplot.axes.PolarAxes, ultraplot.axes.GeoAxes, or ultraplot.axes.ThreeAxes. This can include keyword arguments for projection-specific format commands.

add_subplots(*args, **kwargs)[source]

Add an arbitrary grid of subplots to the figure.

Parameters:

array (ultraplot.gridspec.GridSpec or array-like of int, optional) – The subplot grid specifier. If a GridSpec, one subplot is drawn for each unique GridSpec slot. If a 2D array of integers, one subplot is drawn for each unique integer in the array. Think of this array as a “picture” of the subplot grid – for example, the array [[1, 1], [2, 3]] creates one long subplot in the top row, two smaller subplots in the bottom row. Integers must range from 1 to the number of plots, and 0 indicates an empty space – for example, [[1, 1, 1], [2, 0, 3]] creates one long subplot in the top row with two subplots in the bottom row separated by a space.
nrows, ncols (int, default: 1) – The number of rows and columns in the subplot grid. Ignored if array was passed. Use these arguments for simple subplot grids.
order ({'C', 'F'}, default: 'C') – Whether subplots are numbered in column-major ('C') or row-major ('F') order. Analogous to numpy.array ordering. This controls the order that subplots appear in the SubplotGrid returned by this function, and the order of subplot a-b-c labels (see format).
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).

To use different projections for different subplots, you have two options:
- Pass a list of projection specifications, one for each subplot. For example, uplt.subplots(ncols=2, proj=('cart', 'robin')).
- Pass a dictionary of projection specifications, where the keys are integers or tuples of integers that indicate the projection to use for the corresponding subplot number(s). If a key is not provided, the default projection 'cartesian' is used. For example, uplt.subplots(ncols=4, proj={2: 'cyl', (3, 4): 'stere'}) creates a figure with a default Cartesian axes for the first subplot, a Mercator projection for the second subplot, and a Stereographic projection for the third and fourth subplots.
proj_kw, projection_kw (dict-like, optional) – Keyword arguments passed to Basemap or cartopy Projection classes on instantiation. If dictionary of properties, applies globally. If list or dictionary of dictionaries, applies to specific subplots, as with proj. For example, uplt.subplots(ncols=2, proj='cyl', proj_kw=({'lon_0': 0}, {'lon_0': 180}) centers the projection in the left subplot on the prime meridian and in the right subplot on the international dateline.
backend ({'cartopy', 'basemap'}, default: rc['geo.backend'] = 'cartopy') – Whether to use Basemap or Projection for map projections. If string, applies to all subplots. If list or dict, applies to specific subplots, as with proj.
left, right, top, bottom (unit-spec, default: None) – The fixed space between the subplots and the figure edge. If float, units are em-widths. If string, interpreted by units. If None, the space is determined automatically based on the tick and label settings. If rc['subplots.tight'] is True or tight=True was passed to the figure, the space is determined by the tight layout algorithm.
wspace, hspace, space (unit-spec or sequence, default: None) – The fixed space between grid columns, rows, and both, respectively. If float, string, or None, this value is expanded into lists of length ncols - 1 (for wspace) or length nrows - 1 (for hspace). If a sequence, its length must match these lengths. If float, units are em-widths. If string, interpreted by units.

For elements equal to None, the space is determined automatically based on the tick and label settings. If rc['subplots.tight'] is True or tight=True was passed to the figure, the space is determined by the tight layout algorithm. For example, subplots(ncols=3, tight=True, wspace=(2, None)) fixes the space between columns 1 and 2 but lets the tight layout algorithm determine the space between columns 2 and 3.
wratios, hratios (float or sequence, optional) – Passed to GridSpec, denotes the width and height ratios for the subplot grid. Length of wratios must match the number of columns, and length of hratios must match the number of rows.
width_ratios, height_ratios – Aliases for wratios, hratios. Included for consistency with matplotlib.gridspec.GridSpec.
wpad, hpad, pad (unit-spec or sequence, optional) – The tight layout padding between columns, rows, and both, respectively. Unlike space, these control the padding between subplot content (including text, ticks, etc.) rather than subplot edges. As with space, these can be scalars or arrays optionally containing None. For elements equal to None, the default is innerpad. If float, units are em-widths. If string, interpreted by units.
wequal, hequal, equal (bool, default: rc['subplots.equalspace'] = False) – Whether to make the tight layout algorithm apply equal spacing between columns, rows, or both.
wgroup, hgroup, group (bool, default: rc['subplots.groupspace'] = True) – Whether to make the tight layout algorithm just consider spaces between adjacent subplots instead of entire columns and rows of subplots.
outerpad (unit-spec, default: rc['subplots.outerpad'] = 0.5) – The scalar tight layout padding around the left, right, top, bottom figure edges. If float, units are em-widths. If string, interpreted by units.
innerpad (unit-spec, default: rc['subplots.innerpad'] = 1.0) – The scalar tight layout padding between columns and rows. Synonymous with pad. If float, units are em-widths. If string, interpreted by units.
panelpad (unit-spec, default: rc['subplots.panelpad'] = 0.5) – The scalar tight layout padding between subplots and their panels, colorbars, and legends and between “stacks” of these objects. If float, units are em-widths. If string, interpreted by units.

Other Parameters:

refnum (int, optional) – The reference subplot number. The refwidth, refheight, and refaspect keyword args are applied to this subplot, and the aspect ratio is conserved for this subplot in the auto_layout. The default is the first subplot created in the figure.
refaspect (float or 2-tuple of float, optional) – The reference subplot aspect ratio. If scalar, this indicates the width divided by height. If 2-tuple, this indicates the (width, height). Ignored if both figwidth and figheight or both refwidth and refheight were passed. The default value is 1 or the “data aspect ratio” if the latter is explicitly fixed (as with imshow plots and GeoAxes projections; see set_aspect()).
refwidth, refheight (unit-spec, default: rc['subplots.refwidth'] = 2.5) – The width, height of the reference subplot. If float, units are inches. If string, interpreted by units. Ignored if figwidth, figheight, or figsize was passed. If you specify just one, refaspect will be respected.
ref, aspect, axwidth, axheight – Aliases for refnum, refaspect, refwidth, refheight. These may be deprecated in a future release.
figwidth, figheight (unit-spec, optional) – The figure width and height. Default behavior is to use refwidth. If float, units are inches. If string, interpreted by units. If you specify just one, refaspect will be respected.
width, height – Aliases for figwidth, figheight.
figsize (2-tuple, optional) – Tuple specifying the figure (width, height).
sharex, sharey, share ({0, False, 1, 'labels', 'labs', 2, 'limits', 'lims', 3, True, 4, 'all'}, default: rc['subplots.share'] = True) – The axis sharing “level” for the x axis, y axis, or both axes. Options are as follows:
- 0 or False: No axis sharing. This also sets the default spanx and spany values to False.
- 1 or 'labels' or 'labs': Only draw axis labels on the bottommost row or leftmost column of subplots. Tick labels still appear on every subplot.
- 2 or 'limits' or 'lims': As above but force the axis limits, scales, and tick locations to be identical. Tick labels still appear on every subplot.
- 3 or True: As above but only show the tick labels on the bottommost row and leftmost column of subplots.
- 4 or 'all': As above but also share the axis limits, scales, and tick locations between subplots not in the same row or column.
spanx, spany, span (bool or {0, 1}, default: rc['subplots.span'] = True) – Whether to use “spanning” axis labels for the x axis, y axis, or both axes. Default is False if sharex, sharey, or share are 0 or False. When True, a single, centered axis label is used for all axes with bottom and left edges in the same row or column. This can considerably redundancy in your figure. “Spanning” labels integrate with “shared” axes. For example, for a 3-row, 3-column figure, with sharey > 1 and spany == True, your figure will have 1 y axis label instead of 9 y axis labels.
alignx, aligny, align (bool or {0, 1}, default: rc['subplots.align'] = False) – Whether to “align” axis labels for the x axis, y axis, or both axes. Aligned labels always appear in the same row or column. This is ignored if spanx, spany, or span are True.
left, right, top, bottom (unit-spec, default: None) – The fixed space between the subplots and the figure edge. If float, units are em-widths. If string, interpreted by units. If None, the space is determined automatically based on the tick and label settings. If rc['subplots.tight'] is True or tight=True was passed to the figure, the space is determined by the tight layout algorithm.
wspace, hspace, space (unit-spec, default: None) – The fixed space between grid columns, rows, or both. If float, units are em-widths. If string, interpreted by units. If None, the space is determined automatically based on the font size and axis sharing settings. If rc['subplots.tight'] is True or tight=True was passed to the figure, the space is determined by the tight layout algorithm.
tight (bool, default: :rc`subplots.tight`) – Whether automatic calls to auto_layout should include tight layout adjustments. If you manually specified a spacing in the call to subplots, it will be used to override the tight layout spacing. For example, with left=1, the left margin is set to 1 em-width, while the remaining margin widths are calculated automatically.
wequal, hequal, equal (bool, default: rc['subplots.equalspace'] = False) – Whether to make the tight layout algorithm apply equal spacing between columns, rows, or both.
wgroup, hgroup, group (bool, default: rc['subplots.groupspace'] = True) – Whether to make the tight layout algorithm just consider spaces between adjacent subplots instead of entire columns and rows of subplots.
outerpad (unit-spec, default: rc['subplots.outerpad'] = 0.5) – The scalar tight layout padding around the left, right, top, bottom figure edges. If float, units are em-widths. If string, interpreted by units.
innerpad (unit-spec, default: rc['subplots.innerpad'] = 1.0) – The scalar tight layout padding between columns and rows. Synonymous with pad. If float, units are em-widths. If string, interpreted by units.
panelpad (unit-spec, default: rc['subplots.panelpad'] = 0.5) – The scalar tight layout padding between subplots and their panels, colorbars, and legends and between “stacks” of these objects. If float, units are em-widths. If string, interpreted by units.

journal (str, optional) – String corresponding to an academic journal standard used to control the figure width figwidth and, if specified, the figure height figheight. See the below table. Feel free to add to this table by submitting a pull request.

Key	Size description	Organization
`'aaas1'`	1-column	American Association for the Advancement of Science (e.g. Science)
`'aaas2'`	2-column	”
`'agu1'`	1-column	American Geophysical Union
`'agu2'`	2-column	”
`'agu3'`	full height 1-column	”
`'agu4'`	full height 2-column	”
`'ams1'`	1-column	American Meteorological Society
`'ams2'`	small 2-column	”
`'ams3'`	medium 2-column	”
`'ams4'`	full 2-column	”
`'cop1'`	1-column	Copernicus Publications (e.g. The Cryosphere, Geoscientific Model Development)
`'cop2'`	2-column	”
`'nat1'`	1-column	Nature Research
`'nat2'`	2-column	”
`'pnas1'`	1-column	Proceedings of the National Academy of Sciences
`'pnas2'`	2-column	”
`'pnas3'`	landscape page	”

**kwargs – Passed to the ultraplot class ultraplot.axes.CartesianAxes, ultraplot.axes.PolarAxes, ultraplot.axes.GeoAxes, or ultraplot.axes.ThreeAxes. This can include keyword arguments for projection-specific format commands.

Returns:

axs (SubplotGrid) – The axes instances stored in a SubplotGrid.

auto_layout(renderer=None, aspect=None, tight=None, resize=None)[source]

Automatically adjust the figure size and subplot positions. This is triggered automatically whenever the figure is drawn.

Parameters:

renderer (RendererBase, optional) – The renderer. If None a default renderer will be produced.
aspect (bool, optional) – Whether to update the figure size based on the reference subplot aspect ratio. By default, this is True. This only has an effect if the aspect ratio is fixed (e.g., due to an image plot or geographic projection).
tight (bool, optional) – Whether to update the figuer size and subplot positions according to a “tight layout”. By default, this takes on the value of tight passed to Figure. If nothing was passed, it is rc['subplots.tight'] = True.
resize (bool, optional) – If False, the current figure dimensions are fixed and automatic figure resizing is disabled. By default, the figure size may change unless both figwidth and figheight or figsize were passed to subplots, set_size_inches was called manually, or the figure was resized manually with an interactive backend.

colorbar(**kwargs)[source]

Add a colorbar along the side of the figure.

Parameters:

mappable (mappable, colormap-spec, sequence of color-spec, :py:class:``)
or sequence of `~matplotlib.artist.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.
values (sequence 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.
length (float, default: rc['colorbar.length'] = 1.0) – The colorbar length. Units are relative to the span of the rows and columns of subplots.
shrink (float, optional) – Alias for length. This is included for consistency with matplotlib.figure.Figure.colorbar.
width (unit-spec, default: rc['colorbar.width'] = 0.2) – The colorbar width. If float, units are inches. If string, interpreted by units.
loc (str, optional) – The colorbar location. Valid location keys are as follows.

Location

Valid keys

left

'left', 'l'

right

'right', 'r'

bottom

'bottom', 'b'

top

'top', 't'
space (float or str, default: None) – The fixed space between the colorbar and the subplot grid 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 (float or str, default: rc['subplots.innerpad'] = 1.0 or rc['subplots.panelpad'] = 0.5) – The tight layout padding between the colorbar and the subplot grid. Default is rc['subplots.innerpad'] for the first colorbar and rc['subplots.panelpad'] for subsequently “stacked” colorbars. If float, units are em-widths. If string, interpreted by units.
row, rows – Aliases for span for colorbars on the left or right side.
col, cols – Aliases for span for colorbars on the top or bottom side.
span (int or 2-tuple of int, default: None) – Integer(s) indicating the span of the colorbar across rows and columns of subplots. For example, fig.colorbar(loc='b', col=1) draws a colorbar beneath the leftmost column of subplots, and fig.colorbar(loc='b', cols=(1, 2)) draws a colorbar beneath the left two columns of subplots. By default the colorbar will span every subplot row and column.
align ({'center', 'top', 't', 'bottom', 'b', 'left', 'l', 'right', '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.

Other Parameters:

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.
norm (norm-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_kw (dict-like, optional) – Ignored if mappable is a ScalarMappable. These are the normalizer keyword arguments. Passed to Norm.
vmin, vmax (float, optional) – Ignored if mappable is a ScalarMappable. These are the minimum and maximum colorbar values. Passed to Norm.
label, title (str, optional) – The colorbar label. The title keyword is also accepted for consistency with legend.
reverse (bool, optional) – Whether to reverse the direction of the colorbar. This is done automatically when descending levels are used with DiscreteNorm.
rotation (float, default: 0) – The tick label rotation.
grid, edges, drawedges (bool, 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.
extendfrac (float, optional) – The length of the colorbar “extensions” relative to the length of the colorbar. This is a native matplotlib colorbar keyword.
extendsize (unit-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.
extendrect (bool, default: False) – Whether to draw colorbar “extensions” as rectangles. If False then the extensions are drawn as triangles.
locator, ticks (locator-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_kw (dict-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, ticklabels (formatter-spec, optional) – The tick label format. Passed to the Formatter constructor function.
formatter_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Formatter class.
frame, frameon (bool, default: rc['colorbar.frameon'] = True) – For inset colorbars only. Indicates whether to draw a “frame”, just like legend.
tickminor (bool, 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.
ticklen (unit-spec, default: rc['tick.len'] = 4.0) – Major tick lengths for the colorbar ticks.
ticklenratio (float, default: rc['tick.lenratio'] = 0.5) – Relative scaling of ticklen used to determine minor tick lengths.
tickwidth (unit-spec, default: linewidth) – Major tick widths for the colorbar ticks. or rc['tick.width'] = 0.6 if linewidth was not passed.
tickwidthratio (float, 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, color (optional) – Controls the line width and edge color for both the colorbar outline and the level dividers.
edgefix (bool 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.
rasterize (bool, 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.
outline (bool, None default : None) – 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.
labelrotation (str, 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.

draw(renderer)[source]

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()[source]

Modify figure-wide labels and call format for the input axes. By default the numbered subplots are used.

Parameters:

axs (sequence of Axes, optional) – The axes to format. Default is the numbered subplots.
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.

Important

leftlabelpad, toplabelpad, rightlabelpad, and bottomlabelpad keywords are actually configuration settings. We explicitly document these arguments here because it is common to change them for specific figures. But many other configuration settings can be passed to format too.

Other 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.
aspect ({'auto', 'equal'} or float, optional) – The data aspect ratio. See set_aspect() for details.
xlabel, ylabel (str, optional) – The x and y axis labels. Applied with set_xlabel and set_ylabel.
xlabel_kw, ylabel_kw (dict-like, optional) – Additional axis label settings applied with set_xlabel and set_ylabel. See also labelpad, labelcolor, labelsize, and labelweight below.
xlim, ylim (2-tuple of floats or None, optional) – The x and y axis data limits. Applied with set_xlim() and set_ylim().
xmin, ymin (float, optional) – The x and y minimum data limits. Useful if you do not want to set the maximum limits.
xmax, ymax (float, optional) – The x and y maximum data limits. Useful if you do not want to set the minimum limits.
xreverse, yreverse (bool, optional) – Whether to “reverse” the x and y axis direction. Makes the x and y axes ascend left-to-right and top-to-bottom, respectively.
xscale, yscale (scale-spec, optional) – The x and y axis scales. Passed to the Scale constructor. For example, xscale='log' applies logarithmic scaling, and xscale=('cutoff', 100, 2) applies a CutoffScale.
xscale_kw, yscale_kw (dict-like, optional) – The x and y axis scale settings. Passed to Scale.
xmargin, ymargin, margin (float, default: rc.margin = 0.05) – The default margin between plotted content and the x and y axis spines in axes-relative coordinates. This is useful if you don’t witch to explicitly set axis limits. Use the keyword margin to set both at once.
xbounds, ybounds (2-tuple of float, optional) – The x and y axis data bounds within which to draw the spines. For example, xlim=(0, 4) combined with xbounds=(2, 4) will prevent the spines from meeting at the origin. This also applies xspineloc='bottom' and yspineloc='left' by default if both spines are currently visible.
xtickrange, ytickrange (2-tuple of float, optional) – The x and y axis data ranges within which major tick marks are labelled. For example, xlim=(-5, 5) combined with xtickrange=(-1, 1) and a tick interval of 1 will only label the ticks marks at -1, 0, and 1. See AutoFormatter for details.
xwraprange, ywraprange (2-tuple of float, optional) – The x and y axis data ranges with which major tick mark values are wrapped. For example, xwraprange=(0, 3) causes the values 0 through 9 to be formatted as 0, 1, 2, 0, 1, 2, 0, 1, 2, 0. See AutoFormatter for details. This can be combined with xtickrange and ytickrange to make “stacked” line plots.
xloc, yloc (optional) – Shorthands for xspineloc, yspineloc.
xspineloc, yspineloc ({'b', 't', 'l', 'r', 'bottom', 'top', 'left', 'right', 'both', 'neither', 'none', 'zero', 'center'} or 2-tuple, optional) – The x and y spine locations. Applied with set_position. Propagates to tickloc unless specified otherwise.
xtickloc, ytickloc ({'b', 't', 'l', 'r', 'bottom', 'top', 'left', 'right', 'both', 'neither', 'none'}, optional) – Which x and y axis spines should have major and minor tick marks. Inherits from spineloc by default and propagates to ticklabelloc unless specified otherwise.
xticklabelloc, yticklabelloc ({'b', 't', 'l', 'r', 'bottom', 'top', 'left', 'right', 'both', 'neither', 'none'}, optional) – Which x and y axis spines should have major tick labels. Inherits from tickloc by default and propagates to labelloc and offsetloc unless specified otherwise.
xlabelloc, ylabelloc ({'b', 't', 'l', 'r', 'bottom', 'top', 'left', 'right'}, optional) – Which x and y axis spines should have axis labels. Inherits from ticklabelloc by default (if ticklabelloc is a single side).
xoffsetloc, yoffsetloc ({'b', 't', 'l', 'r', 'bottom', 'top', 'left', 'right'}, optional) – Which x and y axis spines should have the axis offset indicator. Inherits from ticklabelloc by default (if ticklabelloc is a single side).
xtickdir, ytickdir, tickdir ({'out', 'in', 'inout'}, optional) – Direction that major and minor tick marks point for the x and y axis. Use the keyword tickdir to control both.
xticklabeldir, yticklabeldir ({'in', 'out'}, optional) – Whether to place x and y axis tick label text inside or outside the axes. Propagates to xtickdir and ytickdir unless specified otherwise.
xrotation, yrotation (float, default: 0) – The rotation for x and y axis tick labels. for normal axes, rc['formatter.timerotation'] = 'vertical' for time x axes.
xgrid, ygrid, grid (bool, default: rc.grid = True) – Whether to draw major gridlines on the x and y axis. Use the keyword grid to toggle both.
xgridminor, ygridminor, gridminor (bool, default: rc.gridminor = False) – Whether to draw minor gridlines for the x and y axis. Use the keyword gridminor to toggle both.
xtickminor, ytickminor, tickminor (bool, default: rc['tick.minor'] = True) – Whether to draw minor ticks on the x and y axes. Use the keyword tickminor to toggle both.
xticks, yticks (optional) – Aliases for xlocator, ylocator.
xlocator, ylocator (locator-spec, optional) – Used to determine the x and y axis tick mark positions. Passed to the Locator constructor. Can be float, list of float, string, or matplotlib.ticker.Locator instance. Use [], 'null', or 'none' for no ticks.
xlocator_kw, ylocator_kw (dict-like, optional) – Keyword arguments passed to the matplotlib.ticker.Locator class.
xminorticks, yminorticks (optional) – Aliases for xminorlocator, yminorlocator.
xminorlocator, yminorlocator (optional) – As for xlocator, ylocator, but for the minor ticks.
xminorlocator_kw, yminorlocator_kw – As for xlocator_kw, ylocator_kw, but for the minor locator.
xticklabels, yticklabels (optional) – Aliases for xformatter, yformatter.
xformatter, yformatter (formatter-spec, optional) – Used to determine the x and y axis tick label string format. Passed to the Formatter constructor. Can be string, list of strings, or matplotlib.ticker.Formatter instance. Use [], 'null', or 'none' for no labels.
xformatter_kw, yformatter_kw (dict-like, optional) – Keyword arguments passed to the matplotlib.ticker.Formatter class.
xcolor, ycolor, color (color-spec, default: rc['meta.color'] = 'black') – Color for the x and y axis spines, ticks, tick labels, and axis labels. Use the keyword color to set both at once.
xgridcolor, ygridcolor, gridcolor (color-spec, default: rc['grid.color'] = 'black') – Color for the x and y axis major and minor gridlines. Use the keyword gridcolor to set both at once.
xlinewidth, ylinewidth, linewidth (color-spec, default: rc['meta.width'] = 0.6) – Line width for the x and y axis spines and major ticks. Propagates to tickwidth unless specified otherwise. Use the keyword linewidth to set both at once.
xtickcolor, ytickcolor, tickcolor (color-spec, default: rc['tick.color'] = 'black') – Color for the x and y axis ticks. Defaults are xcolor, ycolor, and color if they were passed. Use the keyword tickcolor to set both at once.
xticklen, yticklen, ticklen (unit-spec, default: rc['tick.len'] = 4.0) – Major tick lengths for the x and y axis. If float, units are points. If string, interpreted by units. Use the keyword ticklen to set both at once.
xticklenratio, yticklenratio, ticklenratio (float, default: rc['tick.lenratio'] = 0.5) – Relative scaling of xticklen and yticklen used to determine minor tick lengths. Use the keyword ticklenratio to set both at once.
xtickwidth, ytickwidth, tickwidth, (unit-spec, default: rc['tick.width'] = 0.6) – Major tick widths for the x ans y axis. Default is linewidth if it was passed. If float, units are points. If string, interpreted by units. Use the keyword tickwidth to set both at once.
xtickwidthratio, ytickwidthratio, tickwidthratio (float, default: rc['tick.widthratio'] = 0.8) – Relative scaling of xtickwidth and ytickwidth used to determine minor tick widths. Use the keyword tickwidthratio to set both at once.
xticklabelpad, yticklabelpad, ticklabelpad (unit-spec, default: rc['tick.labelpad'] = 2.0) – The padding between the x and y axis ticks and tick labels. Use the keyword ticklabelpad to set both at once. If float, units are points. If string, interpreted by units.
xticklabelcolor, yticklabelcolor, ticklabelcolor (color-spec, default: rc['tick.labelcolor'] = 'black') – Color for the x and y tick labels. Defaults are xcolor, ycolor, and color if they were passed. Use the keyword ticklabelcolor to set both at once.
xticklabelsize, yticklabelsize, ticklabelsize (unit-spec or str, default: rc['tick.labelsize'] = 'medium') – Font size for the x and y tick labels. If float, units are points. If string, interpreted by units. Use the keyword ticklabelsize to set both at once.
xticklabelweight, yticklabelweight, ticklabelweight (str, default: rc['tick.labelweight'] = 'normal') – Font weight for the x and y tick labels. Use the keyword ticklabelweight to set both at once.
xlabelpad, ylabelpad (unit-spec, default: rc['label.pad'] = 4.0) – The padding between the x and y axis bounding box and the x and y axis labels. If float, units are points. If string, interpreted by units.
xlabelcolor, ylabelcolor, labelcolor (color-spec, default: rc['label.color'] = 'black') – Color for the x and y axis labels. Defaults are xcolor, ycolor, and color if they were passed. Use the keyword labelcolor to set both at once.
xlabelsize, ylabelsize, labelsize (unit-spec or str, default: rc['label.size'] = 'medium') – Font size for the x and y axis labels. If float, units are points. If string, interpreted by units. Use the keyword labelsize to set both at once.
xlabelweight, ylabelweight, labelweight (str, default: rc['label.weight'] = 'normal') – Font weight for the x and y axis labels. Use the keyword labelweight to set both at once.
fixticks (bool, default: False) – Whether to transform the tick locators to a FixedLocator. If your axis ticks are doing weird things (for example, ticks are drawn outside of the axis spine) you can try setting this to True.
r0 (float, default: 0) – The radial origin.
theta0 ({'N', 'NW', 'W', 'SW', 'S', 'SE', 'E', 'NE'}, optional) – The zero azimuth location.
thetadir ({1, -1, 'anticlockwise', 'counterclockwise', 'clockwise'}, optional) – The positive azimuth direction. Clockwise corresponds to -1 and anticlockwise corresponds to 1.
thetamin, thetamax (float, optional) – The lower and upper azimuthal bounds in degrees. If thetamax != thetamin + 360, this produces a sector plot.
thetalim (2-tuple of float or None, optional) – Specifies thetamin and thetamax at once.
rmin, rmax (float, optional) – The inner and outer radial limits. If r0 != rmin, this produces an annular plot.
rlim (2-tuple of float or None, optional) – Specifies rmin and rmax at once.
rborder (bool, optional) – Whether to draw the polar axes border. Visibility of the “inner” radial spine and “start” and “end” azimuthal spines is controlled automatically by matplotlib.
thetagrid, rgrid, grid (bool, optional) – Whether to draw major gridlines for the azimuthal and radial axis. Use the keyword grid to toggle both.
thetagridminor, rgridminor, gridminor (bool, optional) – Whether to draw minor gridlines for the azimuthal and radial axis. Use the keyword gridminor to toggle both.
thetagridcolor, rgridcolor, gridcolor (color-spec, optional) – Color for the major and minor azimuthal and radial gridlines. Use the keyword gridcolor to set both at once.
thetalocator, rlocator (locator-spec, optional) – Used to determine the azimuthal and radial gridline positions. Passed to the Locator constructor. Can be float, list of float, string, or matplotlib.ticker.Locator instance.
thetalines, rlines – Aliases for thetalocator, rlocator.
thetalocator_kw, rlocator_kw (dict-like, optional) – The azimuthal and radial locator settings. Passed to Locator.
thetaminorlocator, rminorlocator (optional) – As for thetalocator, rlocator, but for the minor gridlines.
thetaminorticks, rminorticks (optional) – Aliases for thetaminorlocator, rminorlocator.
thetaminorlocator_kw, rminorlocator_kw – As for thetalocator_kw, rlocator_kw, but for the minor locator.
rlabelpos (float, optional) – The azimuth at which radial coordinates are labeled.
thetaformatter, rformatter (formatter-spec, optional) – Used to determine the azimuthal and radial label format. Passed to the Formatter constructor. Can be string, list of string, or matplotlib.ticker.Formatter instance. Use [], 'null', or 'none' for no labels.
thetalabels, rlabels (optional) – Aliases for thetaformatter, rformatter.
thetaformatter_kw, rformatter_kw (dict-like, optional) – The azimuthal and radial label formatter settings. Passed to Formatter.
color (color-spec, default: rc['meta.color'] = 'black') – Color for the axes edge. Propagates to labelcolor unless specified otherwise (similar to format()).
labelcolor, gridlabelcolor (color-spec, default: color or rc['grid.labelcolor'] = 'black') – Color for the gridline labels.
labelpad, gridlabelpad (unit-spec, default: rc['grid.labelpad'] = 3.0) – The padding between the axes edge and the radial and azimuthal labels. If float, units are points. If string, interpreted by units.
labelsize, gridlabelsize (unit-spec or str, default: rc['grid.labelsize'] = 'medium') – Font size for the gridline labels. If float, units are points. If string, interpreted by units.
labelweight, gridlabelweight (str, default: rc['grid.labelweight'] = 'normal') – Font weight for the gridline labels.
round (bool, default: rc['geo.round'] = True) – For polar cartopy axes only. Whether to bound polar projections with circles rather than squares. Note that outer gridline labels cannot be added to circle-bounded polar projections. When basemap is the backend this argument must be passed to Proj instead.
extent ({'globe', 'auto'}, default: rc['geo.extent'] = 'globe') – For cartopy axes only. Whether to auto adjust the map bounds based on plotted content. If 'globe' then non-polar projections are fixed with set_global, non-Gnomonic polar projections are bounded at the equator, and Gnomonic polar projections are bounded at 30 degrees latitude. If 'auto' nothing is done.
lonlim, latlim (2-tuple of float, optional) – For cartopy axes only. The approximate longitude and latitude boundaries of the map, applied with set_extent. When basemap is the backend this argument must be passed to Proj instead.
boundinglat (float, optional) – For cartopy axes only. The edge latitude for the circle bounding North Pole and South Pole-centered projections. When basemap is the backend this argument must be passed to Proj instead.
longrid, latgrid, grid (bool, default: rc.grid = True) – Whether to draw longitude and latitude gridlines. Use the keyword grid to toggle both at once.
longridminor, latgridminor, gridminor (bool, default: rc.gridminor = False) – Whether to draw “minor” longitude and latitude lines. Use the keyword gridminor to toggle both at once.
lonticklen, latticklen, ticklen (unit-spec, default: rc['tick.len'] = 4.0) – Major tick lengths for the longitudinal (x) and latitude (y) axis. If float, units are points. If string, interpreted by units. Use the keyword ticklen to set both at once.
latmax (float, default: 80) – The maximum absolute latitude for gridlines. Longitude gridlines are cut off poleward of this value (note this feature does not work in cartopy 0.18).
nsteps (int, default: rc['grid.nsteps'] = 250) – For cartopy axes only. The number of interpolation steps used to draw gridlines.
lonlines, latlines (optional) – Aliases for lonlocator, latlocator.
lonlocator, latlocator (locator-spec, optional) – Used to determine the longitude and latitude gridline locations. Passed to the Locator constructor. Can be string, float, list of float, or matplotlib.ticker.Locator instance.

For basemap or cartopy < 0.18, the defaults are 'deglon' and 'deglat', which correspond to the LongitudeLocator and LatitudeLocator locators (adapted from cartopy). For cartopy >= 0.18, the defaults are 'dmslon' and 'dmslat', which uses the same locators with dms=True. This selects gridlines at nice degree-minute-second intervals when the map extent is very small.
lonlines_kw, latlines_kw (optional) – Aliases for lonlocator_kw, latlocator_kw.
lonlocator_kw, latlocator_kw (dict-like, optional) – Keyword arguments passed to the matplotlib.ticker.Locator class.
lonminorlocator, latminorlocator, lonminorlines, latminorlines (optional) – As with lonlocator and latlocator but for the “minor” gridlines.
lonminorlines_kw, latminorlines_kw (optional) – Aliases for lonminorlocator_kw, latminorlocator_kw.
lonminorlocator_kw, latminorlocator_kw (optional) – As with lonlocator_kw, and latlocator_kw but for the “minor” gridlines.
lonlabels, latlabels, labels (str, bool, or sequence, rc['grid.labels'] = False) – Whether to add non-inline longitude and latitude gridline labels, and on which sides of the map. Use the keyword labels to set both at once. The argument must conform to one of the following options:
- A boolean. True indicates the bottom side for longitudes and the left side for latitudes, and False disables all labels.
- A string or sequence of strings indicating the side names, e.g. 'top' for longitudes or ('left', 'right') for latitudes.
- A string indicating the side names with single characters, e.g. 'bt' for longitudes or 'lr' for latitudes.
- A string matching 'neither' (no labels), 'both' (equivalent to 'bt' for longitudes and 'lr' for latitudes), or 'all' (equivalent to 'lrbt', i.e. all sides).
- A boolean 2-tuple indicating whether to draw labels on the (bottom, top) sides for longitudes, and the (left, right) sides for latitudes.
- A boolean 4-tuple indicating whether to draw labels on the (left, right, bottom, top) sides, as with the basemap drawmeridians() and drawparallels() labels keyword.
loninline, latinline, inlinelabels (bool, default: rc['grid.inlinelabels'] = False) – For cartopy axes only. Whether to add inline longitude and latitude gridline labels. Use the keyword inlinelabels to set both at once.
rotatelabels (bool, default: rc['grid.rotatelabels'] = False) – For cartopy axes only. Whether to rotate non-inline gridline labels so that they automatically follow the map boundary curvature.
labelrotation (float, optional) – The rotation angle in degrees for both longitude and latitude tick labels. Use lonlabelrotation and latlabelrotation to set them separately.
lonlabelrotation (float, optional) – The rotation angle in degrees for longitude tick labels. Works for both cartopy and basemap backends.
latlabelrotation (float, optional) – The rotation angle in degrees for latitude tick labels. Works for both cartopy and basemap backends.
labelpad (unit-spec, default: rc['grid.labelpad'] = 3.0) – For cartopy axes only. The padding between non-inline gridline labels and the map boundary. If float, units are points. If string, interpreted by units.
dms (bool, default: rc['grid.dmslabels'] = True) – For cartopy axes only. Whether the default locators and formatters should use “minutes” and “seconds” for gridline labels on small scales rather than decimal degrees. Setting this to False is equivalent to ax.format(lonlocator='deglon', latlocator='deglat') and ax.format(lonformatter='deglon', latformatter='deglat').
lonformatter, latformatter (formatter-spec, optional) – Formatter used to style longitude and latitude gridline labels. Passed to the Formatter constructor. Can be string, list of string, or matplotlib.ticker.Formatter instance.

For basemap or cartopy < 0.18, the defaults are 'deglon' and 'deglat', which correspond to SimpleFormatter presets with degree symbols and cardinal direction suffixes. For cartopy >= 0.18, the defaults are 'dmslon' and 'dmslat', which uses cartopy’s LongitudeFormatter and LatitudeFormatter formatters with dms=True. This formats gridlines that do not fall on whole degrees as “minutes” and “seconds” rather than decimal degrees. Use dms=False to disable this.
lonformatter_kw, latformatter_kw (dict-like, optional) – Keyword arguments passed to the matplotlib.ticker.Formatter class.
land, ocean, coast, rivers, lakes, borders, innerborders (bool, optional) – Toggles various geographic features. These are actually the rc.land, rc.ocean, rc.coast, rc.rivers, rc.lakes, rc.borders, and rc.innerborders settings passed to context. The style can be modified using additional rc settings.

For example, to change rc['land.color'], use ax.format(landcolor='green'), and to change rc['land.zorder'], use ax.format(landzorder=4).
reso ({'lo', 'med', 'hi', 'x-hi', 'xx-hi'}, optional) – For cartopy axes only. The resolution of geographic features. When basemap is the backend this must be passed to Proj instead.
color (color-spec, default: rc['meta.color'] = 'black') – The color for the axes edge. Propagates to labelcolor unless specified otherwise (similar to format()).
gridcolor (color-spec, default: rc['grid.color'] = 'black') – The color for the gridline labels.
labelcolor (color-spec, default: color or rc['grid.labelcolor'] = 'black') – The color for the gridline labels (gridlabelcolor is also allowed).
labelsize (unit-spec or str, default: rc['grid.labelsize'] = 'medium') – The font size for the gridline labels (gridlabelsize is also allowed). If float, units are points. If string, interpreted by units.
labelweight (str, default: rc['grid.labelweight'] = 'normal') – The font weight for the gridline labels (gridlabelweight is also allowed).
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.

legend(**kwargs)[source]

Add a legend along the side of the figure.

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 (str, optional) – The legend location. Valid location keys are as follows.

Location

Valid keys

left

'left', 'l'

right

'right', 'r'

bottom

'bottom', 'b'

top

'top', 't'
space (float or str, default: None) – The fixed space between the legend and the subplot grid 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 (float or str, default: rc['subplots.innerpad'] = 1.0 or rc['subplots.panelpad'] = 0.5) – The tight layout padding between the legend and the subplot grid. Default is rc['subplots.innerpad'] for the first legend and rc['subplots.panelpad'] for subsequently “stacked” legends. If float, units are em-widths. If string, interpreted by units.
row, rows – Aliases for span for legends on the left or right side.
col, cols – Aliases for span for legends on the top or bottom side.
span (int or 2-tuple of int, default: None) – Integer(s) indicating the span of the legend across rows and columns of subplots. For example, fig.legend(loc='b', col=1) draws a legend beneath the leftmost column of subplots, and fig.legend(loc='b', cols=(1, 2)) draws a legend beneath the left two columns of subplots. By default the legend will span every subplot row and column.
align ({'center', 'top', 't', 'bottom', 'b', 'left', 'l', 'right', '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'.
width (unit-spec, optional) – 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.

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.

save(filename, **kwargs)[source]

Save the figure.

Parameters:

path (path-like, optional) – The file path. User paths are expanded with os.path.expanduser.
**kwargs – Passed to savefig

savefig(**kwargs)[source]

Save the figure.

Parameters:

path (path-like, optional) – The file path. User paths are expanded with os.path.expanduser.
**kwargs – Passed to savefig

set(*, agg_filter=<UNSET>, alpha=<UNSET>, animated=<UNSET>, canvas=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, constrained_layout=<UNSET>, constrained_layout_pads=<UNSET>, dpi=<UNSET>, edgecolor=<UNSET>, facecolor=<UNSET>, figheight=<UNSET>, figwidth=<UNSET>, frameon=<UNSET>, gid=<UNSET>, in_layout=<UNSET>, label=<UNSET>, layout_engine=<UNSET>, linewidth=<UNSET>, mouseover=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, rasterized=<UNSET>, size_inches=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, tight_layout=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, zorder=<UNSET>)

Set multiple properties at once.

Supported properties are

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 and two offsets from the bottom left corner of the image

alpha

float or None

animated

bool

canvas

FigureCanvasBase

clip_box

BboxBase or None

clip_on

bool

clip_path

Patch or (Path, Transform) or None

constrained_layout

unknown

constrained_layout_pads

unknown

dpi

float

edgecolor

:mpltype:`color`

facecolor

:mpltype:`color`

figheight

float

figure

unknown

figwidth

float

frameon

bool

gid

str

in_layout

bool

label

object

layout_engine

{‘constrained’, ‘compressed’, ‘tight’, ‘none’, LayoutEngine, None}

linewidth

number

mouseover

bool

path_effects

list of AbstractPathEffect

picker

None or bool or float or callable

rasterized

bool

size_inches

unknown

sketch_params

(scale: float, length: float, randomness: float)

snap

bool or None

tight_layout

unknown

transform

Transform

url

str

visible

bool

zorder

float

set_canvas(**kwargs)[source]

Set the figure canvas. Add monkey patches for the instance-level draw and print_figure methods.

Parameters:: canvas (FigureCanvasBase) – The figure canvas.

See also

matplotlib.figure.Figure.set_canvas

set_constrained_layout(constrained)[source]

[Deprecated] Set whether constrained_layout is used upon drawing.

If None, rc['figure.constrained_layout.use'] = False value will be used.

When providing a dict containing the keys w_pad, h_pad the default constrained_layout paddings will be overridden. These pads are in inches and default to 3.0/72.0. w_pad is the width padding and h_pad is the height padding.

Parameters:: constrained (bool or dict or None)

Notes

Deprecated since version 3.6: Use set_layout_engine(‘constrained’) instead.

set_size_inches(**kwargs)[source]

Set the figure size. If this is being called manually or from an interactive backend, update the default layout with this fixed size. If the figure size is unchanged or this is an internal call, do not update the default layout.

Parameters:

*args (float) – The width and height passed as positional arguments or a 2-tuple.
forward (bool, optional) – Whether to update the canvas.
internal (bool, optional) – Whether this is an internal resize.
eps (float, optional) – The deviation from the current size in inches required to treat this as a user-triggered figure resize that fixes the layout.

set_tight_layout(tight)[source]

[Deprecated] Set whether and how Figure.tight_layout is called when drawing.

Parameters:: tight (bool or dict with keys "pad", "w_pad", "h_pad", "rect" or None) – If a bool, sets whether to call Figure.tight_layout upon drawing. If None, use rc['figure.autolayout'] = False instead. If a dict, pass it as kwargs to Figure.tight_layout, overriding the default paddings.

Notes

Deprecated since version 3.6: Use set_layout_engine instead.

subplot(*args, **kwargs)[source]

Add a subplot axes to the figure.

Parameters:

*args (int, tuple, or SubplotSpec, optional) – The subplot location specifier. Your options are:
- A single 3-digit integer argument specifying the number of rows, number of columns, and gridspec number (using row-major indexing).
- Three positional arguments specifying the number of rows, number of columns, and gridspec number (int) or number range (2-tuple of int).
- A SubplotSpec instance generated by indexing a ultraplot GridSpec.
For integer input, the implied geometry must be compatible with the implied geometry from previous calls – for example, fig.add_subplot(331) followed by fig.add_subplot(132) is valid because the 1 row of the second input can be tiled into the 3 rows of the the first input, but fig.add_subplot(232) will raise an error because 2 rows cannot be tiled into 3 rows. For SubplotSpec input, the SubplotSpec must be derived from the GridSpec used in previous calls.

These restrictions arise because we allocate a single, unique gridspec for each figure.
number (int, optional) – The axes number used for a-b-c labeling. See format for details. By default this is incremented automatically based on the other subplots in the figure. Use e.g. number=None or number=False to ensure the subplot has no a-b-c label. Note the number corresponding to a is 1, not 0.
autoshare (bool, default: True) – Whether to automatically share the x and y axes with subplots spanning the same rows and columns based on the figure-wide sharex and sharey settings. This has no effect if rc['subplots.share'] is False or if sharex=False or sharey=False were passed to the figure.
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.

Other Parameters:

**kwargs – Passed to the ultraplot class ultraplot.axes.CartesianAxes, ultraplot.axes.PolarAxes, ultraplot.axes.GeoAxes, or ultraplot.axes.ThreeAxes. This can include keyword arguments for projection-specific format commands.

subplots(*args, **kwargs)[source]

Add an arbitrary grid of subplots to the figure.

Parameters:

array (ultraplot.gridspec.GridSpec or array-like of int, optional) – The subplot grid specifier. If a GridSpec, one subplot is drawn for each unique GridSpec slot. If a 2D array of integers, one subplot is drawn for each unique integer in the array. Think of this array as a “picture” of the subplot grid – for example, the array [[1, 1], [2, 3]] creates one long subplot in the top row, two smaller subplots in the bottom row. Integers must range from 1 to the number of plots, and 0 indicates an empty space – for example, [[1, 1, 1], [2, 0, 3]] creates one long subplot in the top row with two subplots in the bottom row separated by a space.
nrows, ncols (int, default: 1) – The number of rows and columns in the subplot grid. Ignored if array was passed. Use these arguments for simple subplot grids.
order ({'C', 'F'}, default: 'C') – Whether subplots are numbered in column-major ('C') or row-major ('F') order. Analogous to numpy.array ordering. This controls the order that subplots appear in the SubplotGrid returned by this function, and the order of subplot a-b-c labels (see format).
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).

To use different projections for different subplots, you have two options:
- Pass a list of projection specifications, one for each subplot. For example, uplt.subplots(ncols=2, proj=('cart', 'robin')).
- Pass a dictionary of projection specifications, where the keys are integers or tuples of integers that indicate the projection to use for the corresponding subplot number(s). If a key is not provided, the default projection 'cartesian' is used. For example, uplt.subplots(ncols=4, proj={2: 'cyl', (3, 4): 'stere'}) creates a figure with a default Cartesian axes for the first subplot, a Mercator projection for the second subplot, and a Stereographic projection for the third and fourth subplots.
proj_kw, projection_kw (dict-like, optional) – Keyword arguments passed to Basemap or cartopy Projection classes on instantiation. If dictionary of properties, applies globally. If list or dictionary of dictionaries, applies to specific subplots, as with proj. For example, uplt.subplots(ncols=2, proj='cyl', proj_kw=({'lon_0': 0}, {'lon_0': 180}) centers the projection in the left subplot on the prime meridian and in the right subplot on the international dateline.
backend ({'cartopy', 'basemap'}, default: rc['geo.backend'] = 'cartopy') – Whether to use Basemap or Projection for map projections. If string, applies to all subplots. If list or dict, applies to specific subplots, as with proj.
left, right, top, bottom (unit-spec, default: None) – The fixed space between the subplots and the figure edge. If float, units are em-widths. If string, interpreted by units. If None, the space is determined automatically based on the tick and label settings. If rc['subplots.tight'] is True or tight=True was passed to the figure, the space is determined by the tight layout algorithm.
wspace, hspace, space (unit-spec or sequence, default: None) – The fixed space between grid columns, rows, and both, respectively. If float, string, or None, this value is expanded into lists of length ncols - 1 (for wspace) or length nrows - 1 (for hspace). If a sequence, its length must match these lengths. If float, units are em-widths. If string, interpreted by units.

For elements equal to None, the space is determined automatically based on the tick and label settings. If rc['subplots.tight'] is True or tight=True was passed to the figure, the space is determined by the tight layout algorithm. For example, subplots(ncols=3, tight=True, wspace=(2, None)) fixes the space between columns 1 and 2 but lets the tight layout algorithm determine the space between columns 2 and 3.
wratios, hratios (float or sequence, optional) – Passed to GridSpec, denotes the width and height ratios for the subplot grid. Length of wratios must match the number of columns, and length of hratios must match the number of rows.
width_ratios, height_ratios – Aliases for wratios, hratios. Included for consistency with matplotlib.gridspec.GridSpec.
wpad, hpad, pad (unit-spec or sequence, optional) – The tight layout padding between columns, rows, and both, respectively. Unlike space, these control the padding between subplot content (including text, ticks, etc.) rather than subplot edges. As with space, these can be scalars or arrays optionally containing None. For elements equal to None, the default is innerpad. If float, units are em-widths. If string, interpreted by units.
wequal, hequal, equal (bool, default: rc['subplots.equalspace'] = False) – Whether to make the tight layout algorithm apply equal spacing between columns, rows, or both.
wgroup, hgroup, group (bool, default: rc['subplots.groupspace'] = True) – Whether to make the tight layout algorithm just consider spaces between adjacent subplots instead of entire columns and rows of subplots.
outerpad (unit-spec, default: rc['subplots.outerpad'] = 0.5) – The scalar tight layout padding around the left, right, top, bottom figure edges. If float, units are em-widths. If string, interpreted by units.
innerpad (unit-spec, default: rc['subplots.innerpad'] = 1.0) – The scalar tight layout padding between columns and rows. Synonymous with pad. If float, units are em-widths. If string, interpreted by units.
panelpad (unit-spec, default: rc['subplots.panelpad'] = 0.5) – The scalar tight layout padding between subplots and their panels, colorbars, and legends and between “stacks” of these objects. If float, units are em-widths. If string, interpreted by units.

Other Parameters:

refnum (int, optional) – The reference subplot number. The refwidth, refheight, and refaspect keyword args are applied to this subplot, and the aspect ratio is conserved for this subplot in the auto_layout. The default is the first subplot created in the figure.
refaspect (float or 2-tuple of float, optional) – The reference subplot aspect ratio. If scalar, this indicates the width divided by height. If 2-tuple, this indicates the (width, height). Ignored if both figwidth and figheight or both refwidth and refheight were passed. The default value is 1 or the “data aspect ratio” if the latter is explicitly fixed (as with imshow plots and GeoAxes projections; see set_aspect()).
refwidth, refheight (unit-spec, default: rc['subplots.refwidth'] = 2.5) – The width, height of the reference subplot. If float, units are inches. If string, interpreted by units. Ignored if figwidth, figheight, or figsize was passed. If you specify just one, refaspect will be respected.
ref, aspect, axwidth, axheight – Aliases for refnum, refaspect, refwidth, refheight. These may be deprecated in a future release.
figwidth, figheight (unit-spec, optional) – The figure width and height. Default behavior is to use refwidth. If float, units are inches. If string, interpreted by units. If you specify just one, refaspect will be respected.
width, height – Aliases for figwidth, figheight.
figsize (2-tuple, optional) – Tuple specifying the figure (width, height).
sharex, sharey, share ({0, False, 1, 'labels', 'labs', 2, 'limits', 'lims', 3, True, 4, 'all'}, default: rc['subplots.share'] = True) – The axis sharing “level” for the x axis, y axis, or both axes. Options are as follows:
- 0 or False: No axis sharing. This also sets the default spanx and spany values to False.
- 1 or 'labels' or 'labs': Only draw axis labels on the bottommost row or leftmost column of subplots. Tick labels still appear on every subplot.
- 2 or 'limits' or 'lims': As above but force the axis limits, scales, and tick locations to be identical. Tick labels still appear on every subplot.
- 3 or True: As above but only show the tick labels on the bottommost row and leftmost column of subplots.
- 4 or 'all': As above but also share the axis limits, scales, and tick locations between subplots not in the same row or column.
spanx, spany, span (bool or {0, 1}, default: rc['subplots.span'] = True) – Whether to use “spanning” axis labels for the x axis, y axis, or both axes. Default is False if sharex, sharey, or share are 0 or False. When True, a single, centered axis label is used for all axes with bottom and left edges in the same row or column. This can considerably redundancy in your figure. “Spanning” labels integrate with “shared” axes. For example, for a 3-row, 3-column figure, with sharey > 1 and spany == True, your figure will have 1 y axis label instead of 9 y axis labels.
alignx, aligny, align (bool or {0, 1}, default: rc['subplots.align'] = False) – Whether to “align” axis labels for the x axis, y axis, or both axes. Aligned labels always appear in the same row or column. This is ignored if spanx, spany, or span are True.
left, right, top, bottom (unit-spec, default: None) – The fixed space between the subplots and the figure edge. If float, units are em-widths. If string, interpreted by units. If None, the space is determined automatically based on the tick and label settings. If rc['subplots.tight'] is True or tight=True was passed to the figure, the space is determined by the tight layout algorithm.
wspace, hspace, space (unit-spec, default: None) – The fixed space between grid columns, rows, or both. If float, units are em-widths. If string, interpreted by units. If None, the space is determined automatically based on the font size and axis sharing settings. If rc['subplots.tight'] is True or tight=True was passed to the figure, the space is determined by the tight layout algorithm.
tight (bool, default: :rc`subplots.tight`) – Whether automatic calls to auto_layout should include tight layout adjustments. If you manually specified a spacing in the call to subplots, it will be used to override the tight layout spacing. For example, with left=1, the left margin is set to 1 em-width, while the remaining margin widths are calculated automatically.
wequal, hequal, equal (bool, default: rc['subplots.equalspace'] = False) – Whether to make the tight layout algorithm apply equal spacing between columns, rows, or both.
wgroup, hgroup, group (bool, default: rc['subplots.groupspace'] = True) – Whether to make the tight layout algorithm just consider spaces between adjacent subplots instead of entire columns and rows of subplots.
outerpad (unit-spec, default: rc['subplots.outerpad'] = 0.5) – The scalar tight layout padding around the left, right, top, bottom figure edges. If float, units are em-widths. If string, interpreted by units.
innerpad (unit-spec, default: rc['subplots.innerpad'] = 1.0) – The scalar tight layout padding between columns and rows. Synonymous with pad. If float, units are em-widths. If string, interpreted by units.
panelpad (unit-spec, default: rc['subplots.panelpad'] = 0.5) – The scalar tight layout padding between subplots and their panels, colorbars, and legends and between “stacks” of these objects. If float, units are em-widths. If string, interpreted by units.

journal (str, optional) – String corresponding to an academic journal standard used to control the figure width figwidth and, if specified, the figure height figheight. See the below table. Feel free to add to this table by submitting a pull request.

Key	Size description	Organization
`'aaas1'`	1-column	American Association for the Advancement of Science (e.g. Science)
`'aaas2'`	2-column	”
`'agu1'`	1-column	American Geophysical Union
`'agu2'`	2-column	”
`'agu3'`	full height 1-column	”
`'agu4'`	full height 2-column	”
`'ams1'`	1-column	American Meteorological Society
`'ams2'`	small 2-column	”
`'ams3'`	medium 2-column	”
`'ams4'`	full 2-column	”
`'cop1'`	1-column	Copernicus Publications (e.g. The Cryosphere, Geoscientific Model Development)
`'cop2'`	2-column	”
`'nat1'`	1-column	Nature Research
`'nat2'`	2-column	”
`'pnas1'`	1-column	Proceedings of the National Academy of Sciences
`'pnas2'`	2-column	”
`'pnas3'`	landscape page	”

**kwargs – Passed to the ultraplot class ultraplot.axes.CartesianAxes, ultraplot.axes.PolarAxes, ultraplot.axes.GeoAxes, or ultraplot.axes.ThreeAxes. This can include keyword arguments for projection-specific format commands.

Returns:

axs (SubplotGrid) – The axes instances stored in a SubplotGrid.

subplots_adjust(left=None, bottom=None, right=None, top=None, wspace=None, hspace=None)

Adjust the subplot layout parameters.

Unset parameters are left unmodified; initial values are given by rc['figure.subplot.[name]'].

Parameters:

left (float, optional) – The position of the left edge of the subplots, as a fraction of the figure width.
right (float, optional) – The position of the right edge of the subplots, as a fraction of the figure width.
bottom (float, optional) – The position of the bottom edge of the subplots, as a fraction of the figure height.
top (float, optional) – The position of the top edge of the subplots, as a fraction of the figure height.
wspace (float, optional) – The width of the padding between subplots, as a fraction of the average Axes width.
hspace (float, optional) – The height of the padding between subplots, as a fraction of the average Axes height.

tight_layout(*, pad=1.08, h_pad=None, w_pad=None, rect=None)[source]

Adjust the padding between and around subplots.

To exclude an artist on the Axes from the bounding box calculation that determines the subplot parameters (i.e. legend, or annotation), set a.set_in_layout(False) for that artist.

Parameters:

pad (float, default: 1.08) – Padding between the figure edge and the edges of subplots, as a fraction of the font size.
h_pad, w_pad (float, default: *pad*) – Padding (height/width) between edges of adjacent subplots, as a fraction of the font size.
rect (tuple (left, bottom, right, top), default: (0, 0, 1, 1)) – A rectangle in normalized figure coordinates into which the whole subplots area (including labels) will fit.

See also

Figure.set_layout_engine, pyplot.tight_layout