subplots

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

Return a figure and an arbitrary grid of subplots. This command is analogous to matplotlib.pyplot.subplots, except the subplots are stored in a SubplotGrid.

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 ultraplot.figure.Figure.format or the projection-specific format command for each axes.

Returns:

fig (ultraplot.figure.Figure) – The figure instance.
axs (ultraplot.gridspec.SubplotGrid) – The axes instances stored in a SubplotGrid.