Subplots

Automatic figure size

By default, ProPlot automatically determines the suitable figure size given the geometry of your subplot grid and the size of a “reference” subplot. ProPlot can also determine the suitable figure height given a fixed figure width, and figure width given a fixed figure height.

This algorithm is controlled by the following subplots keyword arguments:

  • ref sets the reference subplot number (default is 1, i.e. the subplot in the upper left corner).

  • aspect sets the reference subplot aspect ratio (default is 1). You can also use the built-in matplotlib set_aspect method.

  • axwidth and axheight set the physical dimensions of the reference subplot (default is axwidth=2). If one is specified, the other is calculated to satisfy aspect. If both are specified, aspect is ignored. The dimensions of the figure are determined automatically.

  • width and height set the physical dimensions of the figure. If one is specified, the other is calculated to satisfy aspect and the subplot spacing. If both are specified (or if the matplotlib figsize parameter is specified), aspect is ignored.

  • journal constrains the physical dimensions of the figure so it meets requirements for submission to an academic journal. For example, figures created with journal='nat1' are sized as single-column Nature figures. See this table for the list of available journal specifications (feel free to add to this table by submitting a PR).

The below examples demonstrate the default behavior of the automatic figure sizing algorithm, and how it can be controlled with subplots keyword arguments.

Important

The automatic figure size algorithm has the following notable properties:

  • For very simple subplot grids (i.e. subplots created with the ncols and nrows arguments), the arguments aspect, axwidth, and axheight apply to every subplot in the figure – not just the reference subplot.

  • When the reference subplot aspect ratio has been fixed (e.g. with ax.set_aspect(1)) or is set to 'equal' (as with map projections and imshow images), the fixed aspect ratio is used and the subplots aspect parameter is ignored. This is critical for getting the figure size right when working with grids of images and grids of projections.

  • When colorbars and panels are present in the figure, their physical widths are preserved during figure resizing. ProPlot specifies their widths in physical units to help avoid colorbars that look “too skinny” or “too fat”.

  1. [1]:
  1. import proplot as plot
  2. import numpy as np
  4. # Auto sized grid of cartopy projections
  5. fig, axs = plot.subplots(ncols=2, nrows=3, proj='robin')
  6. axs.format(
  7.     land=True, landcolor='k',
  8.     suptitle='Auto figure sizing with grid of cartopy projections'
  9. )
  11. # Auto sized grid of images
  12. state = np.random.RandomState(51423)
  13. fig, axs = plot.subplots(ncols=3, nrows=2, axwidth=1.7)
  14. colors = state.rand(15, 12, 3).cumsum(axis=2)
  15. colors /= colors.max()
  16. axs.imshow(colors)
  17. axs.format(
  18.     suptitle='Auto figure sizing with grid of images'
  19. )

_images/subplots_2_0.svg

_images/subplots_2_1.svg

  1. [2]:
  1. import proplot as plot
  3. # Change the reference subplot width
  4. suptitle = 'Effect of subplot width on figure size'
  5. for axwidth in ('4cm', '6cm'):
  6.     fig, axs = plot.subplots(ncols=2, axwidth=axwidth,)
  7.     axs[0].format(
  8.         suptitle=suptitle,
  9.         title=f'axwidth = {axwidth}', titleweight='bold',
  10.         titleloc='uc', titlecolor='red9',
  11.     )
  13. # Change the reference subplot aspect ratio
  14. for aspect in (1, (3, 2)):
  15.     fig, axs = plot.subplots(ncols=2, nrows=2, axwidth=1.6, aspect=aspect)
  16.     axs[0].format(
  17.         suptitle='Effect of subplot aspect ratio on figure size',
  18.         title=f'aspect = {aspect}', titleweight='bold',
  19.         titleloc='uc', titlecolor='red9',
  20.     )

_images/subplots_3_0.svg

_images/subplots_3_1.svg

_images/subplots_3_2.svg

_images/subplots_3_3.svg

  1. [3]:
  1. import proplot as plot
  3. # Change the reference subplot in presence of unequal width/height ratios
  4. for ref in (1, 2):
  5.     fig, axs = plot.subplots(
  6.         ref=ref, nrows=3, ncols=3, wratios=(3, 2, 2),
  7.         axwidth=1.1,
  8.     )
  9.     axs[ref - 1].format(
  10.         suptitle='Effect of reference subplot on figure size',
  11.         title='reference', titleweight='bold',
  12.         titleloc='uc', titlecolor='red9'
  13.     )
  15. # Change the reference subplot in a complex grid
  16. for ref in (1, 2):
  17.     fig, axs = plot.subplots(
  18.         [[1, 2], [1, 3]],
  19.         ref=ref, axwidth=1.8, span=False
  20.     )
  21.     axs[ref - 1].format(
  22.         suptitle='Effect of reference subplot on figure size',
  23.         title='reference', titleweight='bold',
  24.         titleloc='uc', titlecolor='red9'
  25.     )

_images/subplots_4_0.svg

_images/subplots_4_1.svg

_images/subplots_4_2.svg

_images/subplots_4_3.svg

Automatic subplot spacing

In addition to automatic figure sizing, by default ProPlot applies a tight layout algorithm to every figure. This algorithm automatically adjusts the space between subplot rows and columns and the figure edge to accommodate labels. It can be disabled by passing tight=False to subplots. While matplotlib has its own tight layout algorithm, ProPlot’s algorithm may change the figure size to accommodate the correct spacing and permits variable spacing between subsequent subplot rows and columns (see the new GridSpec class for details).

The tight layout algorithm can also be overridden. When you use any of the spacing arguments left, right, top, bottom, wspace, or hspace, that value is always respected. For example:

  • left='2em' fixes the left margin width, while the right, bottom, and top margin widths are determined automatically.

  • wspace='1em' fixes the spaces between subplot columns, while the spaces between subplot rows are determined automatically.

  • wspace=('3em', None) fixes the space between the first two columns of a three-column plot, while the space between the second two columns is determined automatically.

The below examples demonstrate how the tight layout algorithm permits variable spacing between subplot rows and columns.

  1. [4]:
  1. import proplot as plot
  3. # Automatic spacing for all margins and between all columns and rows
  4. fig, axs = plot.subplots(nrows=3, ncols=3, axwidth=1.1, share=0)
  6. # Formatting that stress-tests the algorithm
  7. axs[4].format(
  8.     title='title\ntitle\ntitle',
  9.     suptitle='Tight layout with variable row-column spacing'
  10. )
  11. axs[1].format(ylabel='ylabel\nylabel\nylabel')
  12. axs[:4:2].format(xlabel='xlabel\nxlabel\nxlabel')
  13. axs.format(
  14.     rowlabels=['Row 1', 'Row 2', 'Row 3'],
  15.     collabels=['Column 1', 'Column 2', 'Column 3']
  16. )

_images/subplots_6_0.svg

  1. [5]:
  1. import proplot as plot
  3. # Manual spacing for certain margins and between certain columns and rows
  4. fig, axs = plot.subplots(
  5.     ncols=4, nrows=3, axwidth=1.1, span=False,
  6.     bottom='5em', right='5em',  # margin spacing overrides
  7.     wspace=(0, 0, None), hspace=(0, None),  # column and row spacing overrides
  8. )
  10. # Formatting that stress-tests the algorithm
  11. axs.format(
  12.     xlim=(-1.5, 1.5), ylim=(-1.5, 1.5), xlocator=1, ylocator=1,
  13.     suptitle='Tight layout with user overrides',
  14.     rowlabels=['Row 1', 'Row 2', 'Row 3'],
  15.     collabels=['Column 1', 'Column 2', 'Column 3', 'Column 4']
  16. )
  17. axs[0, :].format(xtickloc='top')
  18. axs[2, :].format(xtickloc='both')
  19. axs[:, 1].format(ytickloc='neither')
  20. axs[:, 2].format(ytickloc='right')
  21. axs[:, 3].format(ytickloc='both')
  22. axs[-1, :].format(title='Title\nTitle\nTitle', xlabel='xlabel')
  23. axs[:, 0].format(ylabel='ylabel\nylabel')

_images/subplots_7_0.svg

Axis sharing

Redundant labels are a common problem for figures with lots of subplots. To address this, matplotlib.pyplot.subplots includes sharex and sharey keywords that permit sharing axis limits, ticks, and tick labels between like rows and columns of subplots. ProPlot expands upon this feature by (1) adding an option for sharing labels in the same row or column of the GridSpec, controlled by the spanx and spany keywords, and (2) adding four axis-sharing “levels,” controlled by the sharex and sharey keywords. The axis-sharing levels are defined as follows:

  • Level 0 disables axis sharing.

  • Level 1 shares duplicate x and y axis labels, but nothing else.

  • Level 2 is the same as 1, but the x and y axis limits, ticks, and scales are also shared.

  • Level 3 is the same as 2, but the x and y tick labels are also shared.

Axis and label sharing works for arbitrarily complex grids of subplots. The below examples demonstrate the effect of various axis and label sharing settings on the appearance of simple subplot grids.

  1. [6]:
  1. import proplot as plot
  2. import numpy as np
  3. N = 50
  4. M = 40
  5. state = np.random.RandomState(51423)
  6. colors = plot.Colors('grays_r', M, left=0.1, right=0.8)
  7. datas = []
  8. for scale in (1, 3, 7, 0.2):
  9.     data = scale * (state.rand(N, M) - 0.5).cumsum(axis=0)[N // 2:, :]
  10.     datas.append(data)
  12. # Same plot with different sharing and spanning settings
  13. for share in (0, 1, 2, 3):
  14.     fig, axs = plot.subplots(
  15.         ncols=4, aspect=1, axwidth=1.06,
  16.         sharey=share, spanx=share // 2
  17.     )
  18.     for ax, data in zip(axs, datas):
  19.         on = ['off', 'on'][share // 2]
  20.         ax.plot(data, cycle=colors)
  21.         ax.format(
  22.             suptitle=f'Sharing level {share}, spanning labels {on}',
  23.             grid=False, xlabel='spanning', ylabel='shared'
  24.         )

_images/subplots_9_0.svg

_images/subplots_9_1.svg

_images/subplots_9_2.svg

_images/subplots_9_3.svg

  1. [7]:
  1. import proplot as plot
  2. import numpy as np
  3. plot.rc.reset()
  4. plot.rc.cycle = 'Set3'
  5. state = np.random.RandomState(51423)
  6. titles = ['With redundant labels', 'Without redundant labels']
  8. # Same plot with and without default sharing settings
  9. for mode in (0, 1):
  10.     fig, axs = plot.subplots(
  11.         nrows=4, ncols=4, share=3 * mode,
  12.         span=1 * mode, axwidth=1
  13.     )
  14.     for ax in axs:
  15.         ax.plot((state.rand(100, 20) - 0.4).cumsum(axis=0))
  16.     axs.format(
  17.         xlabel='xlabel', ylabel='ylabel', suptitle=titles[mode],
  18.         abc=True, abcloc='ul',
  19.         grid=False, xticks=25, yticks=5
  20.     )

_images/subplots_10_0.svg

_images/subplots_10_1.svg

A-b-c subplot labels

ProPlot can be used to add “a-b-c” labels to subplots. This is possible because subplots assigns unique numbers to each subplot. If you passed an array to subplots, the subplot numbers correspond to the numbers in the array. If you used the ncols and nrows keyword arguments, the number order is row-major by default but can be switched to column-major by passing order='F' to subplots. The number order also determines the subplot order in the SubplotsContainer returned by subplots.

To turn on “a-b-c” labels, set [rc.abc](https://proplot.readthedocs.io/en/latest/configuration.html?highlight=abc#rc-proplot) to True or pass abc=True to format (see the format command for details). To change the label style, modify [rc[‘abc.style’]](https://proplot.readthedocs.io/en/latest/configuration.html?highlight=abc.style#rc-proplot) or pass e.g. abcstyle='A.' to format. You can also modify the “a-b-c” label location, weight, and size with the [rc[‘abc.loc’]](https://proplot.readthedocs.io/en/latest/configuration.html?highlight=abc.loc#rc-proplot), [rc[‘abc.weight’]](https://proplot.readthedocs.io/en/latest/configuration.html?highlight=abc.weight#rc-proplot), and [rc[‘abc.size’]](https://proplot.readthedocs.io/en/latest/configuration.html?highlight=abc.size#rc-proplot) settings.

  1. [8]:
  1. import proplot as plot
  2. fig, axs = plot.subplots(nrows=8, ncols=8, axwidth=0.7, space=0)
  3. axs.format(
  4.     abc=True, abcloc='ur', xlabel='x axis', ylabel='y axis',
  5.     xticks=[], yticks=[], suptitle='Subplot labels demo'
  6. )

_images/subplots_12_0.svg

Arbitrary physical units

ProPlot supports arbitrary physical units for controlling the figure width and height, the reference subplot axwidth and axheight, the gridspec spacing values left, right, bottom, top, wspace, and hspace, and in a few other places, e.g. panel and colorbar widths. This feature is powered by the units function.

If a sizing argument is numeric, the units are inches or points; if it is string, the units are converted to inches or points by units. A table of acceptable units is found in the units documentation. They include centimeters, millimeters, pixels, em-heights), en-heights), and points).

  1. [9]:
  1. import proplot as plot
  2. import numpy as np
  3. with plot.rc.context(fontsize='12px'):
  4.     fig, axs = plot.subplots(
  5.         ncols=3, width='15cm', height='3in',
  6.         wspace=('10pt', '20pt'), right='10mm'
  7.     )
  8.     cmap = plot.Colormap('Mono')
  9.     cb = fig.colorbar(
  10.         cmap, loc='b', extend='both', label='colorbar',
  11.         width='2em', extendsize='3em', shrink=0.8,
  12.     )
  13.     pax = axs[2].panel('r', width='5en')
  14.     pax.format(xlim=(0, 1))
  15. axs.format(
  16.     suptitle='Arguments with arbitrary units',
  17.     xlabel='x axis', ylabel='y axis',
  18.     xlim=(0, 1), ylim=(0, 1),
  19. )

_images/subplots_14_0.svg