`matplotlib.layout_engine`#

Classes to layout elements in a Figure.

Figures have a layout_engine property that holds a subclass of LayoutEngine defined here (or None for no layout). At draw time figure.get_layout_engine().execute() is called, the goal of which is usually to rearrange Axes on the figure to produce a pleasing layout. This is like a draw callback, however when printing we disable the layout engine for the final draw and it is useful to know the layout engine while the figure is being created, in particular to deal with colorbars.

Matplotlib supplies two layout engines, TightLayoutEngine and ConstrainedLayoutEngine. Third parties can create their own layout engine by subclassing LayoutEngine.

class matplotlib.layout_engine.ConstrainedLayoutEngine(*, h_pad=None, w_pad=None, hspace=None, wspace=None, rect=(0, 0, 1, 1), compress=False, **kwargs)[source]#

Implements the constrained_layout geometry management. See Constrained Layout Guide for details.

Initialize constrained_layout settings.

Parameters:

h_pad, w_padfloat: Padding around the axes elements in figure-normalized units. Default to rcParams["figure.constrained_layout.h_pad"] (default: 0.04167) and rcParams["figure.constrained_layout.w_pad"] (default: 0.04167).
hspace, wspacefloat: Fraction of the figure to dedicate to space between the axes. These are evenly spread between the gaps between the axes. A value of 0.2 for a three-column layout would have a space of 0.1 of the figure width between each column. If h/wspace < h/w_pad, then the pads are used instead. Default to rcParams["figure.constrained_layout.hspace"] (default: 0.02) and rcParams["figure.constrained_layout.wspace"] (default: 0.02).
recttuple of 4 floats: Rectangle in figure coordinates to perform constrained layout in (left, bottom, width, height), each from 0-1.
compressbool: Whether to shift Axes so that white space in between them is removed. This is useful for simple grids of fixed-aspect Axes (e.g. a grid of images). See Grids of fixed aspect-ratio Axes: "compressed" layout.

property adjust_compatible#: Return a boolean if the layout engine is compatible with subplots_adjust.

property colorbar_gridspec#: Return a boolean if the layout engine creates colorbars using a gridspec.

execute(fig)[source]#

Perform constrained_layout and move and resize axes accordingly.

Parameters:

figFigure to perform layout on.

get()[source]#: Return copy of the parameters for the layout engine.

set(*, h_pad=None, w_pad=None, hspace=None, wspace=None, rect=None)[source]#

Set the pads for constrained_layout.

Parameters:

h_pad, w_padfloat: Padding around the axes elements in figure-normalized units. Default to rcParams["figure.constrained_layout.h_pad"] (default: 0.04167) and rcParams["figure.constrained_layout.w_pad"] (default: 0.04167).
hspace, wspacefloat: Fraction of the figure to dedicate to space between the axes. These are evenly spread between the gaps between the axes. A value of 0.2 for a three-column layout would have a space of 0.1 of the figure width between each column. If h/wspace < h/w_pad, then the pads are used instead. Default to rcParams["figure.constrained_layout.hspace"] (default: 0.02) and rcParams["figure.constrained_layout.wspace"] (default: 0.02).
recttuple of 4 floats: Rectangle in figure coordinates to perform constrained layout in (left, bottom, width, height), each from 0-1.

class matplotlib.layout_engine.LayoutEngine(**kwargs)[source]#

Base class for Matplotlib layout engines.

A layout engine can be passed to a figure at instantiation or at any time with set_layout_engine. Once attached to a figure, the layout engine execute function is called at draw time by draw, providing a special draw-time hook.

Note

However, note that layout engines affect the creation of colorbars, so set_layout_engine should be called before any colorbars are created.

Currently, there are two properties of LayoutEngine classes that are consulted while manipulating the figure:

engine.colorbar_gridspec tells Figure.colorbar whether to make the
axes using the gridspec method (see colorbar.make_axes_gridspec) or not (see colorbar.make_axes);
engine.adjust_compatible stops Figure.subplots_adjust from being
run if it is not compatible with the layout engine.

To implement a custom LayoutEngine:

override _adjust_compatible and _colorbar_gridspec
override LayoutEngine.set to update self._params
override LayoutEngine.execute with your implementation

property adjust_compatible#: Return a boolean if the layout engine is compatible with subplots_adjust.

property colorbar_gridspec#: Return a boolean if the layout engine creates colorbars using a gridspec.

execute(fig)[source]#: Execute the layout on the figure given by fig.

get()[source]#: Return copy of the parameters for the layout engine.

set(**kwargs)[source]#

class matplotlib.layout_engine.PlaceHolderLayoutEngine(adjust_compatible, colorbar_gridspec, **kwargs)[source]#

This layout engine does not adjust the figure layout at all.

The purpose of this LayoutEngine is to act as a place holder when the user removes a layout engine to ensure an incompatible LayoutEngine can not be set later.

Parameters:

adjust_compatible, colorbar_gridspecbool: Allow the PlaceHolderLayoutEngine to mirror the behavior of whatever layout engine it is replacing.

property adjust_compatible#: Return a boolean if the layout engine is compatible with subplots_adjust.

property colorbar_gridspec#: Return a boolean if the layout engine creates colorbars using a gridspec.

execute(fig)[source]#: Execute the layout on the figure given by fig.

get()[source]#: Return copy of the parameters for the layout engine.

set(**kwargs)[source]#

class matplotlib.layout_engine.TightLayoutEngine(*, pad=1.08, h_pad=None, w_pad=None, rect=(0, 0, 1, 1), **kwargs)[source]#

Implements the tight_layout geometry management. See Tight Layout guide for details.

Initialize tight_layout engine.

Parameters:

padfloat, 1.08: Padding between the figure edge and the edges of subplots, as a fraction of the font size.
h_pad, w_padfloat: Padding (height/width) between edges of adjacent subplots. Defaults to pad.
recttuple (left, bottom, right, top), default: (0, 0, 1, 1).: rectangle in normalized figure coordinates that the subplots (including labels) will fit into.

property adjust_compatible#: Return a boolean if the layout engine is compatible with subplots_adjust.

property colorbar_gridspec#: Return a boolean if the layout engine creates colorbars using a gridspec.

execute(fig)[source]#

Execute tight_layout.

This decides the subplot parameters given the padding that will allow the axes labels to not be covered by other labels and axes.

Parameters:

figFigure to perform layout on.
See also: `.figure.Figure.tight_layout` and `.pyplot.tight_layout`.

get()[source]#: Return copy of the parameters for the layout engine.

set(*, pad=None, w_pad=None, h_pad=None, rect=None)[source]#

matplotlib.layout_engine#

`matplotlib.layout_engine`#