GridSpec¶

class GridSpec(nrows=1, ncols=1, **kwargs)[source]¶

Bases: matplotlib.gridspec.GridSpec

A GridSpec subclass that permits variable spacing between successive rows and columns and hides “panel slots” from indexing.

Parameters

nrows (int, optional) – The number of rows in the subplot grid.
ncols (int, optional) – The number of columns in the subplot grid.

Other Parameters

left, right, top, bottom (unit-spec, optional) – The fixed space between the subplots and the figure edge. Default is None. If float, units are em-widths. If string, interpreted by units. If None, the space is determined automatically based on the font size and axis sharing settings. If rc['subplots.tight'] is True, the space is determined by the tight layout algorithm.
wspace, hspace, space (unit-spec or sequence, optional) – The fixed space between grid columns, rows, and both, respectively. If float, string, or None, this value is expanded into lists of length ncols - 1 (for wspace) or length nrows - 1 (for hspace). If a sequence, its length must match these lengths. Default is None. If float, units are em-widths. If string, interpreted by units.

For sequence elements equal to None, the space is determined automatically based on the font size and axis settings. If rc['subplots.tight'] is True, the space is determined by the tight layout algorithm. Otherwise, a sensible default value is chosen. For example, subplots(ncols=3, tight=True, wspace=(2, None)) fixes the space between columns 1 and 2 but lets the tight layout algorithm determine the space between columns 2 and 3.
wratios, hratios (float or sequence, optional) – Passed to GridSpec, denotes the width and height ratios for the subplot grid. Length of wratios must match the number of rows, and length of hratios must match the number of columns.
width_ratios, height_ratios – Aliases for wratios, hratios. Included for consistency with the matplotlib.pyplot.subplots command.
wpad, hpad, pad (unit-spec or sequence, optional) – The tight layout padding between columns, rows, and both, respectively. Unlike space, these control the padding between subplot content (including text, ticks, etc.) rather than subplot edges. As with space, these can be scalars or arrays optionally containing None. Default is innerpad. If float, units are em-widths. If string, interpreted by units.
wequal, hequal, equal (bool, optional) – Whether to make the tight layout algorithm apply equal spacing between columns, rows, or both. Default is False. Ignored if rc.tight is False.
outerpad (unit-spec, optional) – The tight layout padding around the left, right, top, and bottom edges of the figure. Default is rc['subplots.outerpad'] = 0.5. If float, units are em-widths. If string, interpreted by units.
innerpad (unit-spec, optional) – The scalar tight layout padding between columns and rows. Synonymous with pad. Default is rc['subplots.innerpad'] = 1.0. If float, units are em-widths. If string, interpreted by units.
panelpad (unit-spec, optional) – The tight layout padding between subplots and axes panels and between “stacked” panels. Default is rc['subplots.panelpad'] = 0.5. If float, units are em-widths. If string, interpreted by units.

Note

Adding axes panels, axes or figure colorbars, and axes or figure legends quietly augments the gridspec geometry by inserting “panel slots”. However subsequently indexing the gridspec with gs[num] or gs[row, col] will ignore the “panel slots”. This permits adding new subplots by passing gs[num] or gs[row, col] to add_subplot even in the presence of panels. See __getitem__ for details.

Attributes Summary

`bottom`
`figure`	The `proplot.figure.Figure` instance uniquely associated with this `GridSpec`.
`hpad`
`hratios`
`hspace`
`left`
`ncols`
`nrows`
`panelheight`
`panelwidth`
`right`
`spaceheight`
`spacewidth`
`subplotheight`
`subplotwidth`
`top`
`wpad`
`wratios`
`wspace`

Methods Summary

`get_geometry`()	Return the total number of rows and columns in the grid.
`get_grid_positions`([figure])	Return the subplot grid positions allowing for variable inter-subplot spacing and using physical units for the spacing terms.
`get_height_ratios`()	Return the height ratios.
`get_panel_geometry`()	Return the number of rows and columns allocated for "panel" subplots and not available with `gridspec[...]` indexing.
`get_subplot_geometry`()	Return the number of rows and columns allocated for "main" subplots and available with `gridspec[...]` indexing.
`get_subplot_params`()	Return the `SubplotParams` for the GridSpec.
`get_width_ratios`()	Return the width ratios.
`locally_modified_subplot_params`()	Return a list of the names of the subplot parameters explicitly set in the GridSpec.
`set_height_ratios`()	Set the relative heights of the rows.
`set_width_ratios`()	Set the relative widths of the columns.
`subgridspec`()
`tight_layout`()	Adjust subplot parameters to give specified padding.
`update`(**kwargs)	Update the gridspec with arbitrary initialization keyword arguments and update the subplot positions.

Attributes Documentation

bottom¶

figure¶: The proplot.figure.Figure instance uniquely associated with this GridSpec. On assignment the gridspec parameters and figure size are updated.

hpad¶

hratios¶

hspace¶

left¶

ncols¶

nrows¶

panelheight¶

panelwidth¶

right¶

spaceheight¶

spacewidth¶

subplotheight¶

subplotwidth¶

top¶

wpad¶

wratios¶

wspace¶

Methods Documentation

get_geometry()[source]¶: Return the total number of rows and columns in the grid.

get_grid_positions(figure=None)[source]¶: Return the subplot grid positions allowing for variable inter-subplot spacing and using physical units for the spacing terms.

Note

The physical units for positioning grid cells are converted from em-widths to inches when the GridSpec is instantiated. This means that subsequent changes to rc['font.size'] will have no effect on the spaces. This is consistent with rc['font.size'] having no effect on already-instantiated figures.

get_height_ratios()¶

Return the height ratios.

This is None if no height ratios have been set explicitly.

get_panel_geometry()[source]¶: Return the number of rows and columns allocated for “panel” subplots and not available with gridspec[...] indexing.

get_subplot_geometry()[source]¶: Return the number of rows and columns allocated for “main” subplots and available with gridspec[...] indexing.

get_subplot_params()¶

Return the SubplotParams for the GridSpec.

In order of precedence the values are taken from

non-None attributes of the GridSpec
the provided figure
rc['figure.subplot.*']

get_width_ratios()¶

Return the width ratios.

This is None if no width ratios have been set explicitly.

locally_modified_subplot_params()¶

Return a list of the names of the subplot parameters explicitly set in the GridSpec.

This is a subset of the attributes of SubplotParams.

set_height_ratios()¶

Set the relative heights of the rows.

height_ratios must be of length nrows. Each row gets a relative height of height_ratios[i] / sum(height_ratios).

set_width_ratios()¶

Set the relative widths of the columns.

width_ratios must be of length ncols. Each column gets a relative width of width_ratios[i] / sum(width_ratios).

subgridspec()¶

tight_layout()¶

Adjust subplot parameters to give specified padding.

Parameters

pad (float) – Padding between the figure edge and the edges of subplots, as a fraction of the font-size.
h_pad, w_pad (float, optional) – Padding (height/width) between edges of adjacent subplots. Defaults to pad.
rect (tuple of 4 floats, optional) – (left, bottom, right, top) rectangle in normalized figure coordinates that the whole subplots area (including labels) will fit into. Default is (0, 0, 1, 1).

update(**kwargs)[source]¶

Update the gridspec with arbitrary initialization keyword arguments and update the subplot positions.

Parameters

left, right, top, bottom (unit-spec, optional) – The fixed space between the subplots and the figure edge. Default is None. If float, units are em-widths. If string, interpreted by units. If None, the space is determined automatically based on the font size and axis sharing settings. If rc['subplots.tight'] is True, the space is determined by the tight layout algorithm.
wspace, hspace, space (unit-spec or sequence, optional) – The fixed space between grid columns, rows, and both, respectively. If float, string, or None, this value is expanded into lists of length ncols - 1 (for wspace) or length nrows - 1 (for hspace). If a sequence, its length must match these lengths. Default is None. If float, units are em-widths. If string, interpreted by units.

For sequence elements equal to None, the space is determined automatically based on the font size and axis settings. If rc['subplots.tight'] is True, the space is determined by the tight layout algorithm. Otherwise, a sensible default value is chosen. For example, subplots(ncols=3, tight=True, wspace=(2, None)) fixes the space between columns 1 and 2 but lets the tight layout algorithm determine the space between columns 2 and 3.
wratios, hratios (float or sequence, optional) – Passed to GridSpec, denotes the width and height ratios for the subplot grid. Length of wratios must match the number of rows, and length of hratios must match the number of columns.
width_ratios, height_ratios – Aliases for wratios, hratios. Included for consistency with the matplotlib.pyplot.subplots command.
wpad, hpad, pad (unit-spec or sequence, optional) – The tight layout padding between columns, rows, and both, respectively. Unlike space, these control the padding between subplot content (including text, ticks, etc.) rather than subplot edges. As with space, these can be scalars or arrays optionally containing None. Default is innerpad. If float, units are em-widths. If string, interpreted by units.
wequal, hequal, equal (bool, optional) – Whether to make the tight layout algorithm apply equal spacing between columns, rows, or both. Default is False. Ignored if rc.tight is False.
outerpad (unit-spec, optional) – The tight layout padding around the left, right, top, and bottom edges of the figure. Default is rc['subplots.outerpad'] = 0.5. If float, units are em-widths. If string, interpreted by units.
innerpad (unit-spec, optional) – The scalar tight layout padding between columns and rows. Synonymous with pad. Default is rc['subplots.innerpad'] = 1.0. If float, units are em-widths. If string, interpreted by units.
panelpad (unit-spec, optional) – The tight layout padding between subplots and axes panels and between “stacked” panels. Default is rc['subplots.panelpad'] = 0.5. If float, units are em-widths. If string, interpreted by units.