subplots(array=None, ncols=1, nrows=1, ref=1, order='C', aspect=1, figsize=None, width=None, height=None, journal=None, axwidth=None, axheight=None, hspace=None, wspace=None, space=None, hratios=None, wratios=None, width_ratios=None, height_ratios=None, left=None, bottom=None, right=None, top=None, basemap=False, 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.

  • 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 is not None. 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 axes appear in the axs list, and the order of subplot a-b-c labeling (see format).

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

  • width, height (float or str, optional) – The figure width and height. Units are interpreted by units.

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


    Size description




    American Association for the Advancement of Science (e.g. Science)





    American Geophysical Union




    full height 1-column


    full height 2-column



    American Meteorological Society


    small 2-column


    medium 2-column


    full 2-column



    Nature Research





    Proceedings of the National Academy of Sciences




    landscape page

  • ref (int, optional) – The reference axes number. The axwidth, axheight, and aspect keyword args are applied to this axes, and aspect ratio is conserved for this axes in tight layout adjustment.

  • axwidth, axheight (float or str, optional) – Sets the average width, height of your axes. Units are interpreted by units. Default is rc[‘subplots.axwidth’] = '18em'.

    These arguments are convenient where you don’t care about the figure dimensions and just want your axes to have enough “room”.

  • aspect (float or length-2 list of floats, optional) – The (average) axes aspect ratio, in numeric form (width divided by height) or as (width, height) tuple. If you do not provide the hratios or wratios keyword args, all axes will have identical aspect ratios.

  • hratios, wratios – Aliases for height_ratios, width_ratios.

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

  • 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 or string, expanded into lists of length ncols-1 (for wspace) or length nrows-1 (for hspace).

    Units are interpreted by units for each element of the list. By default, these are determined by the “tight layout” algorithm.

  • left, right, top, bottom (float or str, optional) – Passed to GridSpec, denotes the width of padding between the subplots and the figure edge. Units are interpreted by units. By default, these are determined by the “tight layout” algorithm.

  • proj, projection (str or dict-like, optional) – The map projection name. The argument is interpreted as follows.

    • If string, this projection is used for all subplots. For valid names, see the Proj documentation.

    • If list of string, these are the projections to use for each subplot in their array order.

    • If dict-like, keys are integers or tuple integers that indicate the projection to use for each subplot. If a key is not provided, that subplot will be a XYAxes. For example, in a 4-subplot figure, proj={2:'merc', (3,4):'stere'} draws a Cartesian axes for the first subplot, a Mercator projection for the second subplot, and a Stereographic projection for the second and third 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 dictionary of dictionaries of properties, applies to specific subplots, as with proj.

    For example, with ncols=2 and proj_kw={1:{'lon_0':0}, 2:{'lon_0':180}}, the projection in the left subplot is centered on the prime meridian, and the projection in the right subplot is centered on the international dateline.

  • basemap (bool or dict-like, optional) – Whether to use Basemap or Projection for map projections. Default is False. If boolean, applies to all subplots. If dictionary, values apply to specific subplots, as with proj.

Other Parameters

**kwargs – Passed to Figure.