Module plottools.subplots

Enhanced subplots with margins.

Patches matplotlib to provide the following features:

Figure margins

Subplot positions can be adjusted by margins given in multiples of the current font size:

fig.subplots_adjust(leftm=5.0, bottomm=2.0, rightm=2.0, topm=1.0)  # in fontsize units!
gs = fig.add_gridspec(3, 3, leftm=5.0, bottomm=2.0, rightm=2.0, topm=2.5)
gs.update(leftm=5.0, bottomm=2.0, rightm=2.0, topm=2.5)

That is, - leftm specifies the distance of the leftmost axes from the left margin of the figure, - bottomm specifies the distance of the bottom axes from the bottom margin of the figure, - rightm specifies the distance of the rightmost axes from the right margin of the figure, and - topm specifies the distance of the top axes from the top margin of the figure, all as multiples of the font size.

This way, margins do not need to be adjusted when changing the size of a figure!

For figures without any margins you can use the nomargins keyword:

fig.subplots_adjust(nomargins=True)

This sets all margins to zero.

Grid specs

plt.subplots() can be called with width_ratios and height_ratios.

Further, figure.add_gridspec() is made available for older matplotlib versions that do not have this function yet.

To merge several subplots into a single axes, call fig.merge().

To replace an axes by subplots, call ax.subplots().

fig.merge() and ax.subplots() can be arbitrarily combined.

To expand, shrink or move an axes, use expand().

Axes member functions

Figure member functions

  • merge(): merge several axes into a single one.

Install/uninstall subplots functions

You usually do not need to call these functions. Upon loading the subplots module, install_subplots() is called automatically.

Todo

  • default figure margins

Functions

def merge(fig, axs, remove=True)

Merge several axes into a single one.

Add new axes to the figure at the position and size of the common bounding box of all axes in axs. All axes in axs are then removed. This way you do not need to use gridspec explicitly.

Parameters

fig : matplotlib.figure
The figure that contains the axes.
axs : array of axis objects
The axes that should be combined.
remove : bool
If True remove the orignal axes axs.

Returns

ax : axes object
A single axes covering the area of all the axes objects in axs.

See Also

subplots()

Example

With gridspec you would do

fig = plt.figure()
gs = fig.add_gridspec(3, 3)
ax1 = fig.add_subplot(gs[1:,:2])  # merge 2x2 bottom left subplots
ax2 = fig.add_subplot(gs[0,0])    # first in top row
ax3 = fig.add_subplot(gs[0,1])    # second in top row
ax4 = fig.add_subplot(gs[0,2])    # third in top row
ax5 = fig.add_subplot(gs[1,2])    # last in second row
ax6 = fig.add_subplot(gs[2,2])    # last in bottom row

with merge() this simplifies to

fig, axs = plt.subplots(3, 3)     # axs contains 3x3 axes objects
ax1 = fig.merge(axs[1:3,0:2])     # merge 2x2 bottom left subplots into a single one.
ax2 = axs[0,0]                    # first in top row
ax3 = axs[0,1]                    # second in top row
# ...
def subplots(ax, nrows, ncols, **kwargs)

Replace axes by subplots.

Replace axes by all plots of a subgridspec at that axes. This way you do not need to use subgridspec() explicitly.

Parameters

ax : matplotlib.axes
Axes that should be replaced by subplots.
nrows : int
Number of rows of the new subgrid.
ncols : int
Number of columns of the new subgrid.
kwargs : dict
Further arguments for matplotlib.gridspec.GridSpecFromSubplotSpec, e.g. wspace, hspace, height_ratios, width_ratios.

Returns

axs : array of matplotlib axes
Axes of the new subgrid.

See Also

merge()

Example

With gridspec you would do

fig = plt.figure()
gs = fig.add_gridspec(3, 3)
sgs = gs[0,2].subgridspec(2, 1)
ax1 = fig.add_subplot(gs[0,0])
# ... 8 more for all the subplots on gs
subax1 = fig.add_subplot(sgs[0])
subax2 = fig.add_subplot(sgs[1])

As usual, this requires a lot of calls to fig.add_subplot(). With subplots() this simplifies to

fig, axs = plt.subplots(3, 3)     # axs contains 3x3 axes objects
subaxs = axs[0,2].subplots(2, 1)  # replace axs[0,2] by two new subplots

and you can use the axes in axs and subaxs right away.

def expand(ax, left=None, right=None, bottom=None, top=None)

Expand size and modify position of Axes.

Note: only works with savefig(), not with plt show()!

Parameters

ax : Axes object
The axes to be turned into polar projection.
left : float
Move left edge of Axes to the left (in figure coordinates, can be negative for right shift).
right : float
Move right edge of Axes to the right (in figure coordinates, can be negative for left shift).
bottom : float
Move bottom edge of Axes downwards (in figure coordinates, can be negative for upward shift).
top : float
Move top edge of Axes to upwards (in figure coordinates, can be negative for downward shift).
def make_polar(ax, shiftx=0, shifty=0)

Turn an axes into one with polar projection.

Creates a new axes with polar projection at the position of the given axes.

Parameters

ax : Axes object
The axes to be turned into polar projection.
shiftx : float
Horizontally shift the axes relative to ax figure coordinates.
shifty : float
Vertically shift the axes relative to ax in figure coordinates.

Returns

ax : axes object
An axes with polar projection at the position of the given axes.

Example

fig, axs = plt.subplots(2, 3)
axp = axs[1, 2].make_polar()
axp.plot(theta, r)   # this is a polar plot!
def install_subplots()

Install functions of the subplots module in matplotlib.

Patches a few matplotlib functions (plt.figure(), plt.subplots(), figure.add_gridspec(), gridspec.update()). Each figure gets an resize event handler installed, that applies the supplied margins whenever a figure is resized.

See Also

uninstall_subplots()

def uninstall_subplots()

Uninstall all code of the subplots module from matplotlib.

See Also

install_subplots()

def demo()

Run a demonstration of the subplots module.