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
) andrcParams["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
) andrcParams["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:
- fig
Figure
to perform layout on.
- fig
- 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
) andrcParams["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
) andrcParams["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 engineexecute
function is called at draw time bydraw
, 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
tellsFigure.colorbar
whether to make theaxes using the gridspec method (see
colorbar.make_axes_gridspec
) or not (seecolorbar.make_axes
);
engine.adjust_compatible
stopsFigure.subplots_adjust
from beingrun 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._paramsoverride
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.
- 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 incompatibleLayoutEngine
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.
- 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.