SubplotGrid¶
- class SubplotGrid(sequence=None, **kwargs)[source]¶
Bases:
collections.abc.MutableSequence
,list
List-like object used to store subplots returned by
subplots
. 1D indexing uses the underlying list ofAxes
while 2D indexing uses thegridspec
. See__getitem__
for details.- Parameters
sequence (sequence) – A sequence of
proplot.axes.Axes
subplots or their children.
Attributes Summary
The
GridSpec
associated with the grid.The shape of the
GridSpec
associated with the grid.Methods Summary
altx
(*args, **kwargs)Add an axes locked to the same location with a distinct x axis for every axes in the grid.
alty
(*args, **kwargs)Add an axes locked to the same location with a distinct y axis for every axes in the grid.
dualx
(*args, **kwargs)Add an axes locked to the same location whose x axis denotes equivalent coordinates in alternate units for every axes in the grid.
dualy
(*args, **kwargs)Add an axes locked to the same location whose y axis denotes equivalent coordinates in alternate units for every axes in the grid.
format
(*args, **kwargs)Call the
format
command for every axes in the grid.insert
(key, value)S.insert(index, value) -- insert value before index
inset
(*args, **kwargs)Add an inset axes for every axes in the grid.
inset_axes
(*args, **kwargs)Add an inset axes for every axes in the grid.
panel
(*args, **kwargs)Add a panel along the edge of the axes for every axes in the grid.
panel_axes
(*args, **kwargs)Add a panel along the edge of the axes for every axes in the grid.
twinx
(*args, **kwargs)Add an axes locked to the same location with a distinct y axis for every axes in the grid.
twiny
(*args, **kwargs)Add an axes locked to the same location with a distinct x axis for every axes in the grid.
Attributes Documentation
- gridspec¶
The
GridSpec
associated with the grid. This is used to resolve 2D indexing. See__getitem__
for details.
Methods Documentation
- altx(*args, **kwargs)¶
Add an axes locked to the same location with a distinct x axis for every axes in the grid. This is an alias and possibly more intuitive name for
twiny
, which generates two x axes with a shared (“twin”) y axes.- Parameters
xlim, xmin, xmax, xreverse, xscale, xlabel, xtickdir, xgrid, xgridminor, xtickminor, xticklabeldir, xtickrange, xwraprange, xrotation, xformatter, xticklabels, xticks, xlocator, xminorticks, xminorlocator, xbounds, xmargin, xcolor, xlinewidth, xticklen, xgridcolor, xlabel_kw, xscale_kw, xlocator_kw, xformatter_kw, xminorlocator_kw (optional) – Passed to
Axes.format
.lim, min, max, reverse, scale, label, tickdir, grid, gridminor, tickminor, ticklabeldir, tickrange, wraprange, rotation, formatter, ticklabels, ticks, locator, minorticks, minorlocator, bounds, margin, color, linewidth, ticklen, gridcolor, label_kw, scale_kw, locator_kw, formatter_kw, minorlocator_kw (optional) – Prepended with
'x'
and passed toAxes.format
.
- Returns
CartesianAxes
– The new axes.
Note
This enforces the following default settings:
Places the old x axis on the bottom and the new x axis on the top.
Makes the old top spine invisible and the new bottom, left, and right spines invisible.
Adjusts the x axis tick, tick label, and axis label positions according to the visible spine positions.
Syncs the old and new y axis limits and scales, and makes the new y axis labels invisible.
- alty(*args, **kwargs)¶
Add an axes locked to the same location with a distinct y axis for every axes in the grid. This is an alias and possibly more intuitive name for
twinx
, which generates two y axes with a shared (“twin”) x axes.- Parameters
ylim, ymin, ymax, yreverse, yscale, ylabel, ytickdir, ygrid, ygridminor, ytickminor, yticklabeldir, ytickrange, ywraprange, yrotation, yformatter, yticklabels, yticks, ylocator, yminorticks, yminorlocator, ybounds, ymargin, ycolor, ylinewidth, yticklen, ygridcolor, ylabel_kw, yscale_kw, ylocator_kw, yformatter_kw, yminorlocator_kw (optional) – Passed to
Axes.format
.lim, min, max, reverse, scale, label, tickdir, grid, gridminor, tickminor, ticklabeldir, tickrange, wraprange, rotation, formatter, ticklabels, ticks, locator, minorticks, minorlocator, bounds, margin, color, linewidth, ticklen, gridcolor, label_kw, scale_kw, locator_kw, formatter_kw, minorlocator_kw (optional) – Prepended with
'y'
and passed toAxes.format
.
- Returns
CartesianAxes
– The new axes.
Note
This enforces the following default settings:
Places the old y axis on the left and the new y axis on the right.
Makes the old right spine invisible and the new left, bottom, and top spines invisible.
Adjusts the y axis tick, tick label, and axis label positions according to the visible spine positions.
Syncs the old and new x axis limits and scales, and makes the new x axis labels invisible.
- dualx(*args, **kwargs)¶
Add an axes locked to the same location whose x axis denotes equivalent coordinates in alternate units for every axes in the grid. This is an alternative to
matplotlib.axes.Axes.secondary_xaxis
with additional convenience features.- Parameters
funcscale (
callable()
,2-tuple
ofcallables
, orscale-spec
) – The scale used to transform units from the parent axis to the secondary axis. This can be aFuncScale
itself or a function, (function, function) tuple, or an axis scale specification interpreted by theScale
constructor function, any of which will be used to build aFuncScale
and applied to the dual axis (seeFuncScale
for details).xlim, xmin, xmax, xreverse, xscale, xlabel, xtickdir, xgrid, xgridminor, xtickminor, xticklabeldir, xtickrange, xwraprange, xrotation, xformatter, xticklabels, xticks, xlocator, xminorticks, xminorlocator, xbounds, xmargin, xcolor, xlinewidth, xticklen, xgridcolor, xlabel_kw, xscale_kw, xlocator_kw, xformatter_kw, xminorlocator_kw (optional) – Passed to
Axes.format
.lim, min, max, reverse, scale, label, tickdir, grid, gridminor, tickminor, ticklabeldir, tickrange, wraprange, rotation, formatter, ticklabels, ticks, locator, minorticks, minorlocator, bounds, margin, color, linewidth, ticklen, gridcolor, label_kw, scale_kw, locator_kw, formatter_kw, minorlocator_kw (optional) – Prepended with
'x'
and passed toAxes.format
.
- Returns
CartesianAxes
– The new axes.
Note
This enforces the following default settings:
Places the old x axis on the bottom and the new x axis on the top.
Makes the old top spine invisible and the new bottom, left, and right spines invisible.
Adjusts the x axis tick, tick label, and axis label positions according to the visible spine positions.
Syncs the old and new y axis limits and scales, and makes the new y axis labels invisible.
- dualy(*args, **kwargs)¶
Add an axes locked to the same location whose y axis denotes equivalent coordinates in alternate units for every axes in the grid. This is an alternative to
matplotlib.axes.Axes.secondary_yaxis
with additional convenience features.- Parameters
funcscale (
callable()
,2-tuple
ofcallables
, orscale-spec
) – The scale used to transform units from the parent axis to the secondary axis. This can be aFuncScale
itself or a function, (function, function) tuple, or an axis scale specification interpreted by theScale
constructor function, any of which will be used to build aFuncScale
and applied to the dual axis (seeFuncScale
for details).ylim, ymin, ymax, yreverse, yscale, ylabel, ytickdir, ygrid, ygridminor, ytickminor, yticklabeldir, ytickrange, ywraprange, yrotation, yformatter, yticklabels, yticks, ylocator, yminorticks, yminorlocator, ybounds, ymargin, ycolor, ylinewidth, yticklen, ygridcolor, ylabel_kw, yscale_kw, ylocator_kw, yformatter_kw, yminorlocator_kw (optional) – Passed to
Axes.format
.lim, min, max, reverse, scale, label, tickdir, grid, gridminor, tickminor, ticklabeldir, tickrange, wraprange, rotation, formatter, ticklabels, ticks, locator, minorticks, minorlocator, bounds, margin, color, linewidth, ticklen, gridcolor, label_kw, scale_kw, locator_kw, formatter_kw, minorlocator_kw (optional) – Prepended with
'y'
and passed toAxes.format
.
- Returns
CartesianAxes
– The new axes.
Note
This enforces the following default settings:
Places the old y axis on the left and the new y axis on the right.
Makes the old right spine invisible and the new left, bottom, and top spines invisible.
Adjusts the y axis tick, tick label, and axis label positions according to the visible spine positions.
Syncs the old and new x axis limits and scales, and makes the new x axis labels invisible.
- format(*args, **kwargs)[source]¶
Call the
format
command for every axes in the grid.- Parameters
title (
str
, optional) – The axes title.abc (
bool
orstr
, optional) – The “a-b-c” subplot label style. Must contain the charactera
orA
, for example'a.'
, or'A'
. IfTrue
then the default style of'a'
is used. Thea
orA
is replaced with the alphabetic character matching thenumber
. Ifnumber
is greater than 26, the characters loop around to a, …, z, aa, …, zz, aaa, …, zzz, etc.abcloc, titleloc (
str
, optional) – Strings indicating the location for the a-b-c label and main title. The following locations are valid (defaults arerc['abc.loc']
='left'
andrc['title.loc']
='center'
):Location
Valid keys
center above axes
'center'
,'c'
left above axes
'left'
,'l'
right above axes
'right'
,'r'
lower center inside axes
'lower center'
,'lc'
upper center inside axes
'upper center'
,'uc'
upper right inside axes
'upper right'
,'ur'
upper left inside axes
'upper left'
,'ul'
lower left inside axes
'lower left'
,'ll'
lower right inside axes
'lower right'
,'lr'
abcborder, titleborder (
bool
, optional) – Whether to draw a white border around titles and a-b-c labels positioned inside the axes. This can help them stand out on top of artists plotted inside the axes. Defaults arerc['abc.border']
=True
andrc['title.border']
=True
.abcbbox, titlebbox (
bool
, optional) – Whether to draw a white bbox around titles and a-b-c labels positioned inside the axes. This can help them stand out on top of artists plotted inside the axes. Defaults arerc['abc.bbox']
=False
andrc['title.bbox']
=False
.abc_kw, title_kw (dict-like, optional) – Additional settings used to update the a-b-c label and title with
text.update()
.titlepad (
float
, optional) – The padding for the inner and outer titles and a-b-c labels in arbitrary units (default is points). Default isrc['title.pad']
=5.0
.titleabove (
bool
, optional) – Whether to try to put outer titles and a-b-c labels above panels, colorbars, or legends that are above the axes. Default isrc['title.above']
=True
.abctitlepad (
float
, optional) – The horizontal padding between the a-b-c label and title when they are in the same location. Default isrc['abc.titlepad']
=4.0
.ltitle, ctitle, rtitle, ultitle, uctitle, urtitle, lltitle, lctitle, lrtitle (
str
, optional) – Additional titles in specific positions. This works as an alternative to theax.format(title='Title', titleloc=loc)
workflow and permits adding more than one title-like label to a single axes.a, alpha, fc, facecolor, ec, edgecolor, lw, linewidth, ls, linestyle (optional) – Additional settings applied to the background patch, and their shorthands. Defaults are
rc['axes.alpha']
,rc['axes.facecolor']
,rc['axes.edgecolor']
,rc['axes.linewidth']
, and'-'
, respectively.**kwargs – Passed to the projection-specific
format
command for each axes. Valid only if every axes in the grid belongs to the same class.
- Other Parameters
rowlabels, collabels, llabels, tlabels, rlabels, blabels – Aliases for
leftlabels
andtoplabels
, and forleftlabels
,toplabels
,rightlabels
, andbottomlabels
, respectively.leftlabels, toplabels, rightlabels, bottomlabels (sequence of
str
, optional) – Labels for the subplots lying along the left, top, right, and bottom edges of the figure. The length of each list must match the number of subplots along the corresponding edge.leftlabelpad, toplabelpad, rightlabelpad, bottomlabelpad (
float
, optional) – The padding between the labels and the axes content in arbitrary units (default is points). Defaults arerc['leftlabel.pad']
,rc['toplabel.pad']
,rc['rightlabel.pad']
, andrc['bottomlabel.pad']
leftlabels_kw, toplabels_kw, rightlabels_kw, bottomlabels_kw (dict-like, optional) – Additional settings used to update the labels with
text.update()
.figtitle – Alias for
suptitle
.suptitle (
str
, optional) – The figure “super” title, centered between the left edge of the lefmost column of subplots and the right edge of the rightmost column of subplots, and automatically offset above figure titles. This is an improvement on matplotlib’s “super” title, which just centers the text between figure edges.suptitlepad (
float
, optional) – The padding between the super title and the axes content in arbitrary units (default is points). Default isrc['suptitle.pad']
.suptitle_kw (optional) – Additional settings used to update the super title with
text.update()
.rc_mode (
int
, optional) – The context mode passed tocontext
.rc_kw (dict-like, optional) – An alternative to passing extra keyword arguments. See below.
**kwargs – Passed to
proplot.config.Configurator.context
and used to update the axes-relevantrc
settings. For example,abcstyle='A.'
modifies therc['abc.style']
setting,titleloc='left'
modifies therc['title.loc']
setting,gridminor=True
modifies therc.gridminor
setting, andgridbelow=True
modifies therc['grid.below']
setting. Many of the keyword arguments documented above are actually applied by updating therc
settings then retrieving the updated settings.
- inset(*args, **kwargs)¶
Add an inset axes for every axes in the grid. This is similar to
matplotlib.axes.Axes.inset_axes
.- Parameters
bounds (
4-tuple
offloat
) – The (left, bottom, width, height) coordinates for the axes.transform (
{'data', 'axes', 'figure'}
orTransform
, optional) – The transform used to interpret the bounds. Can be aTransform
instance or a string representing thetransData
,transAxes
, ortransFigure
transforms. Default is'axes'
, i.e.bounds
is in axes-relative coordinates. Default is to use the same projection as the current axes.proj, projection (
str
,cartopy.crs.Projection
, orBasemap
, optional) – The map projection specification(s). If'cart'
or'cartesian'
(the default), aCartesianAxes
is created. If'polar'
, aPolarAxes
is created. Otherwise, the argument is interpreted byProj
, and the result is used to make aGeoAxes
(in this case the argument can be acartopy.crs.Projection
instance, aBasemap
instance, or a projection name listed in this table).proj_kw, projection_kw (dict-like, optional) – Keyword arguments passed to
Basemap
or cartopyProjection
classes on instantiation.basemap (
bool
or dict-like, optional) – Whether to useBasemap
orProjection
for map projections. Default isrc.basemap
=False
.zorder (
float
, optional) – The zorder of the axes, should be greater than the zorder of elements in the parent axes. Default is4
.zoom (
bool
, optional) – Whether to draw lines indicating the inset zoom usingindicate_inset_zoom
. The lines will automatically adjust whenever the parent axes or inset axes limits are changed. Default isTrue
.zoom_kw (
dict
, optional) – Passed toindicate_inset_zoom
.
- Returns
proplot.axes.Axes
– The inset axes.- Other Parameters
**kwargs – Passed to
CartesianAxes
.
- inset_axes(*args, **kwargs)¶
Add an inset axes for every axes in the grid. This is similar to
matplotlib.axes.Axes.inset_axes
.- Parameters
bounds (
4-tuple
offloat
) – The (left, bottom, width, height) coordinates for the axes.transform (
{'data', 'axes', 'figure'}
orTransform
, optional) – The transform used to interpret the bounds. Can be aTransform
instance or a string representing thetransData
,transAxes
, ortransFigure
transforms. Default is'axes'
, i.e.bounds
is in axes-relative coordinates. Default is to use the same projection as the current axes.proj, projection (
str
,cartopy.crs.Projection
, orBasemap
, optional) – The map projection specification(s). If'cart'
or'cartesian'
(the default), aCartesianAxes
is created. If'polar'
, aPolarAxes
is created. Otherwise, the argument is interpreted byProj
, and the result is used to make aGeoAxes
(in this case the argument can be acartopy.crs.Projection
instance, aBasemap
instance, or a projection name listed in this table).proj_kw, projection_kw (dict-like, optional) – Keyword arguments passed to
Basemap
or cartopyProjection
classes on instantiation.basemap (
bool
or dict-like, optional) – Whether to useBasemap
orProjection
for map projections. Default isrc.basemap
=False
.zorder (
float
, optional) – The zorder of the axes, should be greater than the zorder of elements in the parent axes. Default is4
.zoom (
bool
, optional) – Whether to draw lines indicating the inset zoom usingindicate_inset_zoom
. The lines will automatically adjust whenever the parent axes or inset axes limits are changed. Default isTrue
.zoom_kw (
dict
, optional) – Passed toindicate_inset_zoom
.
- Returns
proplot.axes.Axes
– The inset axes.- Other Parameters
**kwargs – Passed to
CartesianAxes
.
- panel(*args, **kwargs)¶
Add a panel along the edge of the axes for every axes in the grid.
- Parameters
side (
str
, optional) – The panel location. Valid location keys are as follows.Location
Valid keys
left
'left'
,'l'
right
'right'
,'r'
bottom
'bottom'
,'b'
top
'top'
,'t'
width (
unit-spec
, optional) – The panel width. Default isrc['subplots.panelwidth']
=0.5
. If float, units are inches. If string, interpreted byunits
.space (
unit-spec
, optional) – The fixed space between the panel and the subplot edge. If float, units are em-widths. If string, interpreted byunits
. When the tight layout algorithm is active for the figure, this is adjusted automatically usingpad
. Otherwise, a suitable default is selected.pad (
unit-spec
, optional) – The tight layout padding between the panel and the subplot. If float, units are em-widths. If string, interpreted byunits
.share (
bool
, optional) – Whether to enable axis sharing between the x and y axes of the main subplot and the panel long axes for each panel in the stack. Sharing between the panel short axis and other panel short axes is determined by figure-widesharex
andsharey
settings.
- Returns
proplot.axes.CartesianAxes
– The panel axes.
- panel_axes(*args, **kwargs)¶
Add a panel along the edge of the axes for every axes in the grid.
- Parameters
side (
str
, optional) – The panel location. Valid location keys are as follows.Location
Valid keys
left
'left'
,'l'
right
'right'
,'r'
bottom
'bottom'
,'b'
top
'top'
,'t'
width (
unit-spec
, optional) – The panel width. Default isrc['subplots.panelwidth']
=0.5
. If float, units are inches. If string, interpreted byunits
.space (
unit-spec
, optional) – The fixed space between the panel and the subplot edge. If float, units are em-widths. If string, interpreted byunits
. When the tight layout algorithm is active for the figure, this is adjusted automatically usingpad
. Otherwise, a suitable default is selected.pad (
unit-spec
, optional) – The tight layout padding between the panel and the subplot. If float, units are em-widths. If string, interpreted byunits
.share (
bool
, optional) – Whether to enable axis sharing between the x and y axes of the main subplot and the panel long axes for each panel in the stack. Sharing between the panel short axis and other panel short axes is determined by figure-widesharex
andsharey
settings.
- Returns
proplot.axes.CartesianAxes
– The panel axes.
- twinx(*args, **kwargs)¶
Add an axes locked to the same location with a distinct y axis for every axes in the grid. This builds upon
matplotlib.axes.Axes.twinx
.- Parameters
ylim, ymin, ymax, yreverse, yscale, ylabel, ytickdir, ygrid, ygridminor, ytickminor, yticklabeldir, ytickrange, ywraprange, yrotation, yformatter, yticklabels, yticks, ylocator, yminorticks, yminorlocator, ybounds, ymargin, ycolor, ylinewidth, yticklen, ygridcolor, ylabel_kw, yscale_kw, ylocator_kw, yformatter_kw, yminorlocator_kw (optional) – Passed to
Axes.format
.lim, min, max, reverse, scale, label, tickdir, grid, gridminor, tickminor, ticklabeldir, tickrange, wraprange, rotation, formatter, ticklabels, ticks, locator, minorticks, minorlocator, bounds, margin, color, linewidth, ticklen, gridcolor, label_kw, scale_kw, locator_kw, formatter_kw, minorlocator_kw (optional) – Prepended with
'y'
and passed toAxes.format
.
- Returns
CartesianAxes
– The new axes.
Note
This enforces the following default settings:
Places the old y axis on the left and the new y axis on the right.
Makes the old right spine invisible and the new left, bottom, and top spines invisible.
Adjusts the y axis tick, tick label, and axis label positions according to the visible spine positions.
Syncs the old and new x axis limits and scales, and makes the new x axis labels invisible.
- twiny(*args, **kwargs)¶
Add an axes locked to the same location with a distinct x axis for every axes in the grid. This builds upon
matplotlib.axes.Axes.twiny
.- Parameters
xlim, xmin, xmax, xreverse, xscale, xlabel, xtickdir, xgrid, xgridminor, xtickminor, xticklabeldir, xtickrange, xwraprange, xrotation, xformatter, xticklabels, xticks, xlocator, xminorticks, xminorlocator, xbounds, xmargin, xcolor, xlinewidth, xticklen, xgridcolor, xlabel_kw, xscale_kw, xlocator_kw, xformatter_kw, xminorlocator_kw (optional) – Passed to
Axes.format
.lim, min, max, reverse, scale, label, tickdir, grid, gridminor, tickminor, ticklabeldir, tickrange, wraprange, rotation, formatter, ticklabels, ticks, locator, minorticks, minorlocator, bounds, margin, color, linewidth, ticklen, gridcolor, label_kw, scale_kw, locator_kw, formatter_kw, minorlocator_kw (optional) – Prepended with
'x'
and passed toAxes.format
.
- Returns
CartesianAxes
– The new axes.
Note
This enforces the following default settings:
Places the old x axis on the bottom and the new x axis on the top.
Makes the old top spine invisible and the new bottom, left, and right spines invisible.
Adjusts the x axis tick, tick label, and axis label positions according to the visible spine positions.
Syncs the old and new y axis limits and scales, and makes the new y axis labels invisible.