subplots¶
- subplots(*args, **kwargs)[source]¶
Create a figure with a single subplot or an arbitrary grid of subplots. Uses
figure
andproplot.figure.Figure.subplots
. This command is analogous tomatplotlib.pyplot.subplots
.- Parameters
array (
2d array-like
ofint
, optional) – Array specifying complex grid of subplots. Think of this as a “picture” of your figure. 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, and0
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.ncols, nrows (
int
, optional) – The number of columns, rows in the subplot grid. Ignored ifarray
was passed. Use these arguments for simpler subplot grids.order (
{'C', 'F'}
, optional) – Whether subplots are numbered in column-major ('C'
) or row-major ('F'
) order. Analogous tonumpy.array
ordering. This controls the order that subplots appear in theSubplotGrid
returned by this function, and the order of subplot a-b-c labels (seeformat
).proj, projection (
str
,cartopy.crs.Projection
, orBasemap
, optional) – The map projection specification(s). If'cart'
or'cartesian'
(the default), aCartesianAxes
is created. If'polar'
, aPolarAxes
is created. Otherwise, the argument is interpreted byProj
, and the result is used to make aGeoAxes
(in this case the argument can be acartopy.crs.Projection
instance, aBasemap
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,
pplt.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,pplt.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 cartopyProjection
classes on instantiation. If dictionary of properties, applies globally. If list or dictionary of dictionaries, applies to specific subplots, as withproj
. For example,pplt.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.basemap (
bool
or dict-like, optional) – Whether to useBasemap
orProjection
for map projections. Default isrc.basemap
=False
. If boolean, applies to all subplots. If list or dict, applies to specific subplots, as withproj
.left, right, top, bottom (
float
orstr
, optional) – The fixed space between the subplots and the figure edge. Default isNone
. If float, units are em-widths. If string, interpreted byunits
. IfNone
, the space is determined automatically based on the font size and axis sharing settings. Ifrc['subplots.tight']
isTrue
, the space is determined by the tight layout algorithm.wspace, hspace, space (
float
orstr
orlist thereof
, optional) – The fixed space between grid columns, rows, and both, respectively. If float, string, orNone
, this value is expanded into lists of lengthncols - 1
(forwspace
) or lengthnrows - 1
(forhspace
). If list, the list must match these lengths. Default isNone
. If float, units are em-widths. If string, interpreted byunits
.For list elements equal to
None
, the space is determined automatically based on the font size and axis settings. Ifrc['subplots.tight']
isTrue
, the space is determined by the tight layout algorithm. Otherwise, a sensible default value is chosen. 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
orlist thereof
, optional) – Passed toGridSpec
, denotes the width and height ratios for the subplot grid. Length ofwratios
must match the number of rows, and length ofhratios
must match the number of columns.width_ratios, height_ratios – Aliases for
wratios
,hratios
. Included for consistency with thematplotlib.pyplot.subplots
command.wpad, hpad, pad (
float
orstr
orlist thereof
, optional) – The tight layout padding between columns, rows, and both, respectively. Unlikespace
, these control the padding between subplot content (including text, ticks, etc.) rather than subplot edges. As withspace
, these can be scalars or arrays optionally containingNone
. Default isinnerpad
. If float, units are em-widths. If string, interpreted byunits
.wequal, hequal, equal (
bool
, optional) – Whether to make the tight layout algorithm apply equal spacing between columns, rows, or both. Default isFalse
. Ignored ifrc.tight
isFalse
.outerpad (
float
orstr
, optional) – The tight layout padding around the left, right, top, and bottom edges of the figure. Default isrc['subplots.outerpad']
=0.5
. If float, units are em-widths. If string, interpreted byunits
.innerpad (
float
orstr
, optional) – The scalar tight layout padding between columns and rows. Synonymous withpad
. Default isrc['subplots.innerpad']
=1.0
. If float, units are em-widths. If string, interpreted byunits
.panelpad (
float
orstr
, optional) – The tight layout padding between subplots and axes panels and between “stacked” panels. Default isrc['subplots.panelpad']
=0.5
. If float, units are em-widths. If string, interpreted byunits
.
- Other Parameters
refnum (
int
, optional) – The reference subplot number. Therefwidth
,refheight
, andrefaspect
keyword args are applied to this subplot, and the aspect ratio is conserved for this subplot in theauto_layout
. The default is the first subplot created in the figure.refaspect (
float
orlength-2 list
offloats
, optional) – The reference subplot aspect ratio. If scalar, this indicates the width divided by height. If 2-tuple, indicates the (width, height). Ignored if bothfigwidth
andfigheight
or bothrefwidth
andrefheight
were passed.refwidth, refheight (
float
orstr
, optional) – The width, height of the reference subplot. Default isrc['subplots.refwidth']
=2.5
. If float, units are inches. If string, interpreted byunits
. Ignored iffigwidth
,figheight
, orfigsize
was passed.ref, aspect, axwidth, axheight – Aliases for
refnum
,refaspect
,refwidth
,refheight
. These may be deprecated in a future release.figwidth, figheight (
float
orstr
, optional) – The figure width and height. If float, units are inches. If string, interpreted byunits
. If you specify just one, the aspect ratiorefaspect
of the reference subplot will be preserved.width, height – Aliases for
figwidth
,figheight
.figsize (
length-2 tuple
, optional) – Tuple specifying the figure(width, height)
.sharex, sharey, share (
{0, False, 1, 'labels', 'labs', 2, 'limits', 'lims', 3, True, 4, 'all'}
, optional) – The axis sharing “level” for the x axis, y axis, or both axes. Default isrc['subplots.share']
=True
. Options are as follows:0
orFalse
: No axis sharing. This also sets the defaultspanx
andspany
values toFalse
.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
orTrue
: 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}
, optional) – Whether to use “spanning” axis labels for the x axis, y axis, or both axes. Default isFalse
ifsharex
,sharey
, orshare
are0
orFalse
,rc['subplots.span']
=True
otherwise. WhenTrue
, 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
andspany=1
, your figure will have 1 ylabel instead of 9.alignx, aligny, align (
bool
or{0, 1}
, optional) – 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 Only has an effect whenspanx
,spany
, orspan
areFalse
. Default isrc['subplots.align']
=False
.left, right, top, bottom (
float
orstr
, optional) – The fixed space between the subplots and the figure edge. Default isNone
. If float, units are em-widths. If string, interpreted byunits
. IfNone
, the space is determined automatically based on the font size and axis sharing settings. Ifrc['subplots.tight']
isTrue
, the space is determined by the tight layout algorithm.wspace, hspace, space (
float
ortr
, optional) – The fixed space between grid columns, rows, or both. Default isNone
. If float, units are em-widths. If string, interpreted byunits
. IfNone
, the space is determined automatically based on the font size and axis sharing settings. Ifrc['subplots.tight']
isTrue
, the space is determined by the tight layout algorithm.tight (
bool
, optional) – Whether to haveauto_layout
include tight layout adjustments. Default isrc['subplots.tight']
=True
. If you manually specified a spacing in the call tosubplots
, it will be used to override the tight layout spacing. For example, withleft=1
, the left margin is set to 1 em-width, while the remaining margin widths are calculated automatically.wequal, hequal, equal (
bool
, optional) – Whether to make the tight layout algorithm apply equal spacing between columns, rows, or both. Default isFalse
. Ignored ifrc.tight
isFalse
.outerpad (
float
orstr
, optional) – The tight layout padding around the left, right, top, and bottom edges of the figure. Default isrc['subplots.outerpad']
=0.5
. If float, units are em-widths. If string, interpreted byunits
.innerpad (
float
orstr
, optional) – The scalar tight layout padding between columns and rows. Synonymous withpad
. Default isrc['subplots.innerpad']
=1.0
. If float, units are em-widths. If string, interpreted byunits
.panelpad (
float
orstr
, optional) – The tight layout padding between subplots and axes panels and between “stacked” panels. Default isrc['subplots.panelpad']
=0.5
. If float, units are em-widths. If string, interpreted byunits
.includepanels (
bool
, optional) – Whether to include panels when aligning figure “super titles” along the top of the subplot grid and when aligning thespanx
x axis labels andspany
y axis labels along the sides of the subplot grid. Default isFalse
.mathtext_fallback (
bool
orstr
, optional) – Apply thisrc['mathtext.fallback']
value when drawing the figure. IfTrue
or string, unavailable glyphs are replaced with a glyph from a fallback font (Computer Modern by default). Otherwise, they are replaced with the “¤” dummy character. For details see this mathtext tutorial.journal (
str
, optional) – String corresponding to an academic journal standard used to control the figure widthfigwidth
and, if specified, the figure heightfigheight
. 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
'agu2'
2-column
”
'agu3'
full height 1-column
”
'agu4'
full height 2-column
”
'ams1'
1-column
'ams2'
small 2-column
”
'ams3'
medium 2-column
”
'ams4'
full 2-column
”
'nat1'
1-column
'nat2'
2-column
”
'pnas1'
1-column
'pnas2'
2-column
”
'pnas3'
landscape page
”
**kwargs – Passed to
matplotlib.figure.Figure
.
- Returns
fig (
proplot.figure.Figure
) – The figure instance.axs (
proplot.figure.SubplotGrid
) – The axes instances stored in aSubplotGrid
.