subplots

subplots(array=None, ncols=1, nrows=1, order='C', ref=1, refaspect=1, refwidth=None, refheight=None, axwidth=None, axheight=None, aspect=None, figwidth=None, figheight=None, figsize=None, width=None, height=None, journal=None, hspace=None, wspace=None, space=None, hratios=None, wratios=None, width_ratios=None, height_ratios=None, wequal=None, hequal=None, equal=None, left=None, bottom=None, right=None, top=None, basemap=None, proj=None, projection=None, proj_kw=None, projection_kw=None, **kwargs)[source]

Create a figure with a single subplot or arbitrary grids of subplots, analogous to matplotlib.pyplot.subplots. The subplots can be drawn with arbitrary projections.

Parameters

  • array (2d array-like of int, optional) – Array specifying complex grid of subplots. Think of this array 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.

    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.

  • ncols, nrows (int, optional) – Number of columns, rows. Ignored if array 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 to numpy.array ordering. This controls the order that subplots appear in the SubplotsContainer returned by this function, and the order of subplot a-b-c labels (see format).

  • ref (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 tight layout adjustment. If you did not specify width_ratios and height_ratios, the refwidth, refheight, and refaspect settings will apply to all subplots – not just the ref subplot.

  • refaspect (float or length-2 list of floats, optional) – The reference subplot aspect ratio, in numeric form (width divided by height) or as a (width, height) tuple. Ignored if both width and height or both refwidth and refheight were passed.

  • refwidth, refheight (float or str, optional) – The width, height of the reference subplot. Units are interpreted by units. Default is rc[‘subplots.refwidth’] = '20em'. Ignored if width, height, or figsize was passed.

  • aspect, axwidth, axheight – Aliases for refaspect, refwidth, refheight. This will be deprecated in the next major release.

  • figwidth, figheight (float or str, optional) – The figure width and height. If you specify just one, the aspect ratio refaspect of the reference subplot ref will be preserved.

  • figsize (length-2 tuple, optional) – Tuple specifying the figure (width, height).

  • width, height – Aliases for figwidth, figheight. This will be deprecated in the next major release.

  • wspace, hspace, space (float or str or list thereof, optional) – Passed to GridSpec, denotes the spacing 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 list, the list must match these lengths. Default is None. Units are interpreted by units.

    For list elements equal to None, the space is determined automatically. If rc[‘subplots.tight’] is True, the space is determined by the tight layout algorithm. Otherwise, a sensible default value is chosen. For example, subplots(ncols=3, tight=True, wspace=('2em', None)) fixes the space between the first 2 columns but uses the tight layout algorithm between the last 2 columns.

  • wequal, hequal, equal (bool, optional) – Whether to make the tight layout algorithm apply equal spacing between columns, rows, or both. Default is False.

  • left, right, top, bottom (float or str, optional) – Passed to GridSpec, denotes the amount of padding between the subplots and the figure edge. Units are interpreted by units. Default is None.

    If None, the space is determined automatically. If rc[‘subplots.tight’] is True, the space is determined by the tight layout algorithm. Otherwise, a sensible default value is chosen.

  • wratios, hratios (float or list thereof, optional) – Passed to GridSpec, denotes the width and height ratios for the subplot grid. Length of wratios must match the number of rows, and length of hratios must match the number of columns.

  • width_ratios, height_ratios – Aliases for wratios, hratios. Included for consistency with the matplotlib.pyplot.subplots command.

  • journal (str, optional) – String name corresponding to an academic journal standard that is used to control the figure width figwidth and, if specified, the figure height figheight. See the below table.

    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

    ”

    'nat1'

    1-column

    Nature Research

    'nat2'

    2-column

    ”

    'pnas1'

    1-column

    Proceedings of the National Academy of Sciences

    'pnas2'

    2-column

    ”

    'pnas3'

    landscape page

    ”

  • proj, projection (str, cartopy.crs.Projection, Basemap, list thereof, or dict thereof, optional) – The map projection specification(s). If '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, pplt.subplots(ncols=2, proj=('cartesian', '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(s). If a key is not provided, the default projection 'cartesian' is used. For example, pplt.subplots(ncols=4, proj={2: 'merc', (3, 4): 'stere'}) creates a figure with a 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, list of dict, or dict of dicts, optional) – Keyword arguments passed to Basemap or cartopy Projection classes on instantiation. If dictionary of properties, applies globally. If list of dictionaries or dictionary of dictionaries, these apply to specific subplots, as with proj. For example, pplt.subplots(ncols=2, proj_kw={1: {'lon_0': 0}, 2: {'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, list of bool, or dict of bool, optional) – Passed to Proj, determines whether projection string names like 'pcarree' are used to create BasemapAxes or CartopyAxes. Default is rc.basemap = False. If boolean, applies to all subplots. If list or dict, applies to specific subplots, as with proj.

Other Parameters

**kwargs – Passed to proplot.figure.Figure.

Returns

See also

proplot.figure.Figure, proplot.axes.Axes, SubplotsContainer, matplotlib.figure.Figure

References

For academic journal figure size recommendations, see the Nature AAAS, PNAS, AGU, and AMS web pages.