GridSpec

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

Bases: 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, default: None) – The fixed space between the subplots and the figure edge. If float, units are em-widths. If string, interpreted by units. If None, the space is determined automatically based on the tick and label settings. If rc['subplots.tight'] is True or tight=True was passed to the figure, the space is determined by the tight layout algorithm.
wspace, hspace, space (unit-spec or sequence, default: None) – 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. If float, units are em-widths. If string, interpreted by units.

For elements equal to None, the space is determined automatically based on the tick and label settings. If rc['subplots.tight'] is True or tight=True was passed to the figure, the space is determined by the tight layout algorithm. 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 columns, and length of hratios must match the number of rows.
width_ratios, height_ratios – Aliases for wratios, hratios. Included for consistency with matplotlib.gridspec.GridSpec.
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. For elements equal to None, the default is innerpad. If float, units are em-widths. If string, interpreted by units.
wequal, hequal, equal (bool, default: rc['subplots.equalspace'] = False) – Whether to make the tight layout algorithm apply equal spacing between columns, rows, or both.
wgroup, hgroup, group (bool, default: rc['subplots.groupspace'] = True) – Whether to make the tight layout algorithm just consider spaces between adjacent subplots instead of entire columns and rows of subplots.
outerpad (unit-spec, default: rc['subplots.outerpad'] = 0.5) – The scalar tight layout padding around the left, right, top, bottom figure edges. If float, units are em-widths. If string, interpreted by units.
innerpad (unit-spec, default: rc['subplots.innerpad'] = 1.0) – The scalar tight layout padding between columns and rows. Synonymous with pad. If float, units are em-widths. If string, interpreted by units.
panelpad (unit-spec, default: rc['subplots.panelpad'] = 0.5) – The scalar tight layout padding between subplots and their panels, colorbars, and legends and between “stacks” of these objects. If float, units are em-widths. If string, interpreted by units.

Important

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). This also means that each GridSpec is Figure-specific, i.e. it can only be used once (if you are working with GridSpec instances manually and want the same geometry for multiple figures, you must create a copy with GridSpec.copy before working on the subsequent figure).

Attributes Summary

`bottom`
`figure`	The `ultraplot.figure.Figure` uniquely associated with this `GridSpec`.
`gridheight`
`gridwidth`
`hpad`
`hpad_panel`
`hpad_total`
`hratios`
`hratios_panel`
`hratios_total`
`hspace`
`hspace_panel`
`hspace_total`
`left`
`ncols`
`ncols_panel`
`ncols_total`
`nrows`
`nrows_panel`
`nrows_total`
`panelheight`
`panelwidth`
`right`
`spaceheight`
`spacewidth`
`top`
`wpad`
`wpad_panel`
`wpad_total`
`wratios`
`wratios_panel`
`wratios_total`
`wspace`
`wspace_panel`
`wspace_total`

Methods Summary

`copy`(**kwargs)	Return a copy of the `GridSpec` with the `Figure`-specific "panel slots" removed.
`get_geometry`()	Return the number of "unhidden" non-panel rows and columns in the grid (see `GridSpec` for details).
`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 "hidden" panel rows and columns in the grid (see `GridSpec` for details).
`get_subplot_params`()	Return the `SubplotParams` for the GridSpec.
`get_total_geometry`()	Return the total number of "unhidden" and "hidden" rows and columns in the grid (see `GridSpec` for details).
`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 ultraplot.figure.Figure uniquely associated with this GridSpec. On assignment the gridspec parameters and figure size are updated.

See also

ultraplot.gridspec.SubplotGrid.figure, ultraplot.figure.Figure.gridspec

gridheight

gridwidth

hpad

hpad_panel

hpad_total

hratios

hratios_panel

hratios_total

hspace

hspace_panel

hspace_total

left

ncols

ncols_panel

ncols_total

nrows

nrows_panel

nrows_total

panelheight

panelwidth

right

spaceheight

spacewidth

top

wpad

wpad_panel

wpad_total

wratios

wratios_panel

wratios_total

wspace

wspace_panel

wspace_total

Methods Documentation

copy(**kwargs)[source]

Return a copy of the GridSpec with the Figure-specific “panel slots” removed. This can be useful if you want to draw multiple figures with the same geometry. Properties are inherited from this GridSpec by default but can be changed by passing keyword arguments.

Parameters:

left, right, top, bottom (unit-spec, default: None) – The fixed space between the subplots and the figure edge. If float, units are em-widths. If string, interpreted by units. If None, the space is determined automatically based on the tick and label settings. If rc['subplots.tight'] is True or tight=True was passed to the figure, the space is determined by the tight layout algorithm.
wspace, hspace, space (unit-spec or sequence, default: None) – 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. If float, units are em-widths. If string, interpreted by units.

For elements equal to None, the space is determined automatically based on the tick and label settings. If rc['subplots.tight'] is True or tight=True was passed to the figure, the space is determined by the tight layout algorithm. 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 columns, and length of hratios must match the number of rows.
width_ratios, height_ratios – Aliases for wratios, hratios. Included for consistency with matplotlib.gridspec.GridSpec.
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. For elements equal to None, the default is innerpad. If float, units are em-widths. If string, interpreted by units.
wequal, hequal, equal (bool, default: rc['subplots.equalspace'] = False) – Whether to make the tight layout algorithm apply equal spacing between columns, rows, or both.
wgroup, hgroup, group (bool, default: rc['subplots.groupspace'] = True) – Whether to make the tight layout algorithm just consider spaces between adjacent subplots instead of entire columns and rows of subplots.
outerpad (unit-spec, default: rc['subplots.outerpad'] = 0.5) – The scalar tight layout padding around the left, right, top, bottom figure edges. If float, units are em-widths. If string, interpreted by units.
innerpad (unit-spec, default: rc['subplots.innerpad'] = 1.0) – The scalar tight layout padding between columns and rows. Synonymous with pad. If float, units are em-widths. If string, interpreted by units.
panelpad (unit-spec, default: rc['subplots.panelpad'] = 0.5) – The scalar tight layout padding between subplots and their panels, colorbars, and legends and between “stacks” of these objects. If float, units are em-widths. If string, interpreted by units.