matplotlib.layout_engine#

Classes to layout elements in aFigure.

Figures have alayout_engine property that holds a subclass ofLayoutEngine defined here (orNone for no layout). At draw timefigure.get_layout_engine().execute() is called, the goal of which isusually to rearrange Axes on the figure to produce a pleasing layout. This islike adraw callback but with two differences. First, when printing wedisable the layout engine for the final draw. Second, it is useful to know thelayout engine while the figure is being created. In particular, colorbars aremade differently with different layout engines (for historical reasons).

Matplotlib has two built-in layout engines:

• TightLayoutEngine was the first layout engine added to Matplotlib.See alsoTight layout guide.

• ConstrainedLayoutEngine is more modern and generally gives better results.See alsoConstrained layout guide.

Third parties can create their own layout engine by subclassingLayoutEngine.

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

Implements theconstrained_layout geometry management. SeeConstrained layout guide for details.

Initializeconstrained_layout settings.

Parameters:

h_pad, w_padfloat

Padding around the Axes elements in inches.Default torcParams["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 theaxes. These are evenly spread between the gaps between the Axes.A value of 0.2 for a three-column layout would have a spaceof 0.1 of the figure width between each column.If h/wspace < h/w_pad, then the pads are used instead.Default torcParams["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 isremoved. This is useful for simple grids of fixed-aspect Axes (e.g.a grid of images). SeeGrids of fixed aspect-ratio Axes: "compressed" layout.

propertyadjust_compatible#

Return a boolean if the layout engine is compatible withsubplots_adjust.

propertycolorbar_gridspec#

Return a boolean if the layout engine creates colorbars using agridspec.

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 inches.Default torcParams["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 theaxes. These are evenly spread between the gaps between the Axes.A value of 0.2 for a three-column layout would have a spaceof 0.1 of the figure width between each column.If h/wspace < h/w_pad, then the pads are used instead.Default torcParams["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.

classmatplotlib.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 timewithset_layout_engine. Once attached to a figure, thelayout 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, soset_layout_engine should be called before anycolorbars are created.

Currently, there are two properties ofLayoutEngine classes that areconsulted while manipulating the figure:

• engine.colorbar_gridspec tellsFigure.colorbar whether to make the

  axes using the gridspec method (seecolorbar.make_axes_gridspec) ornot (seecolorbar.make_axes);

• engine.adjust_compatible stopsFigure.subplots_adjust from being

  run if it is not compatible with the layout engine.

To implement a customLayoutEngine:

1. override_adjust_compatible and_colorbar_gridspec

2. overrideLayoutEngine.set to updateself._params

3. overrideLayoutEngine.execute with your implementation

propertyadjust_compatible#

Return a boolean if the layout engine is compatible withsubplots_adjust.

propertycolorbar_gridspec#

Return a boolean if the layout engine creates colorbars using agridspec.

execute(fig)[source]#

Execute the layout on the figure given byfig.

get()[source]#

Return copy of the parameters for the layout engine.

set(**kwargs)[source]#

Set the parameters for the layout engine.

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

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

The purpose of thisLayoutEngine is to act as a placeholder when the user removesa layout engine to ensure an incompatibleLayoutEngine cannot be set later.

Parameters:

adjust_compatible, colorbar_gridspecbool

Allow the PlaceHolderLayoutEngine to mirror the behavior of whateverlayout engine it is replacing.

propertyadjust_compatible#

Return a boolean if the layout engine is compatible withsubplots_adjust.

propertycolorbar_gridspec#

Return a boolean if the layout engine creates colorbars using agridspec.

execute(fig)[source]#

Do nothing.

get()[source]#

Return copy of the parameters for the layout engine.

set(**kwargs)[source]#

Set the parameters for the layout engine.

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

Implements thetight_layout geometry management. SeeTight layout guide for details.

Initialize tight_layout engine.

Parameters:

padfloat, default: 1.08

Padding between the figure edge and the edges of subplots, as afraction of the font size.

h_pad, w_padfloat

Padding (height/width) between edges of adjacent subplots.Defaults topad.

recttuple (left, bottom, right, top), default: (0, 0, 1, 1).

rectangle in normalized figure coordinates that the subplots(including labels) will fit into.

propertyadjust_compatible#

Return a boolean if the layout engine is compatible withsubplots_adjust.

propertycolorbar_gridspec#

Return a boolean if the layout engine creates colorbars using agridspec.

execute(fig)[source]#

Execute tight_layout.

This decides the subplot parameters given the padding thatwill allow the Axes labels to not be covered by other labelsand Axes.

Parameters:

figFigure to perform layout on.

See also

figure.Figure.tight_layout

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]#

Set the pads for tight_layout.

Parameters:

padfloat

Padding between the figure edge and the edges of subplots, as afraction of the font size.

w_pad, h_padfloat

Padding (width/height) between edges of adjacent subplots.Defaults topad.

recttuple (left, bottom, right, top)

rectangle in normalized figure coordinates that the subplots(including labels) will fit into.