CartesianAxes¶

class CartesianAxes(*args, **kwargs)[source]¶

Bases: proplot.axes.shared._SharedAxes, proplot.axes.plot.PlotAxes

Axes subclass for plotting in ordinary Cartesian coordinates. Adds the format method and overrides several existing methods.

Attributes Summary

name

Methods Summary

`altx`(**kwargs)	Add an axes locked to the same location with a distinct x axis.
`alty`(**kwargs)	Add an axes locked to the same location with a distinct y axis.
`draw`([renderer])	Draw everything (plot lines, axes, labels)
`dualx`(funcscale, **kwargs)	Add an axes locked to the same location whose x axis denotes equivalent coordinates in alternate units.
`dualy`(funcscale, **kwargs)	Add an axes locked to the same location whose y axis denotes equivalent coordinates in alternate units.
`format`(**kwargs)	Modify the x and y axis labels, tick locations, tick labels, axis scales, spine settings, and more.
`get_tightbbox`(renderer, args, *kwargs)	Return the tight bounding box of the axes, including axis and their decorators (xlabel, title, etc).
`twinx`()	Add an axes locked to the same location with a distinct y axis.
`twiny`()	Add an axes locked to the same location with a distinct x axis.

Attributes Documentation

name = 'rectilinear'¶

Methods Documentation

altx(**kwargs)[source]¶

Add an axes locked to the same location with a distinct x axis. 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 to Axes.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(**kwargs)[source]¶

Add an axes locked to the same location with a distinct y axis. 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 to Axes.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.

draw(renderer=None, *args, **kwargs)[source]¶: Draw everything (plot lines, axes, labels)

dualx(funcscale, **kwargs)[source]¶

Add an axes locked to the same location whose x axis denotes equivalent coordinates in alternate units. This is an alternative to matplotlib.axes.Axes.secondary_xaxis with additional convenience features.

Parameters

funcscale (callable(), 2-tuple of callables, or scale-spec) – The scale used to transform units from the parent axis to the secondary axis. This can be a FuncScale itself or a function, (function, function) tuple, or an axis scale specification interpreted by the Scale constructor function, any of which will be used to build a FuncScale and applied to the dual axis (see FuncScale 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 to Axes.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(funcscale, **kwargs)[source]¶

Add an axes locked to the same location whose y axis denotes equivalent coordinates in alternate units. This is an alternative to matplotlib.axes.Axes.secondary_yaxis with additional convenience features.

Parameters

funcscale (callable(), 2-tuple of callables, or scale-spec) – The scale used to transform units from the parent axis to the secondary axis. This can be a FuncScale itself or a function, (function, function) tuple, or an axis scale specification interpreted by the Scale constructor function, any of which will be used to build a FuncScale and applied to the dual axis (see FuncScale 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 to Axes.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(**kwargs)[source]¶

Modify the x and y axis labels, tick locations, tick labels, axis scales, spine settings, and more. Additional keyword arguments are passed to Axes.format and context.

Parameters

aspect ({'auto', 'equal'}, optional) – The aspect ratio mode. See set_aspect for details.
xlabel, ylabel (str, optional) – The x and y axis labels. Applied with set_xlabel and set_ylabel.
xlabelpad, ylabelpad (unit-spec, optional) – The padding between the x and y axis bounding box and the x and y axis labels. Default is rc['label.pad'] = 4.0. If float, units are points. If string, interpreted by units.
xlabel_kw, ylabel_kw (dict-like, optional) – Additional settings used to update the axis labels with text.update().
xlim, ylim (2-tuple of floats or None, optional) – The x and y axis data limits. Applied with set_xlim and set_ylim.
xmin, ymin (float, optional) – The x and y minimum data limits. Useful if you do not want to set the maximum limits.
xmax, ymax (float, optional) – The x and y maximum data limits. Useful if you do not want to set the minimum limits.
xreverse, yreverse (bool, optional) – Whether to “reverse” the x and y axis direction. Makes the x and y axes ascend left-to-right and top-to-bottom, respectively.
xscale, yscale (scale-spec, optional) – The x and y axis scales. Passed to the Scale constructor. For example, xscale='log' applies logarithmic scaling, and xscale=('cutoff', 100, 2) applies a CutoffScale.
xscale_kw, yscale_kw (dict-like, optional) – The x and y axis scale settings. Passed to Scale.
xspineloc, yspineloc ({'both', 'bottom', 'top', 'left', 'right', 'neither', 'center', 'zero'}, optional) – The x and y axis spine locations.
xloc, yloc (optional) – Aliases for xspineloc, yspineloc.
xtickloc, ytickloc ({'both', 'bottom', 'top', 'left', 'right', 'neither'}, optional) – Which x and y axis spines should have major and minor tick marks.
xtickminor, ytickminor, tickminor (bool, optional) – Whether to draw minor ticks on the x and y axes.
xtickdir, ytickdir, tickdir ({'out', 'in', 'inout'}) – Direction that major and minor tick marks point for the x and y axis. Use tickdir to control both.
xticklabeldir, yticklabeldir ({'in', 'out'}) – Whether to place x and y axis tick label text inside or outside the axes.
xticklabelpad, yticklabelpad (unit-spec, optional) – The padding between the x and y axis ticks and tick labels. Default is rc['tick.labelpad']. If float, units are points. If string, interpreted by units.
xgrid, ygrid, grid (bool, optional) – Whether to draw major gridlines on the x and y axis. Use grid to toggle both.
xgridminor, ygridminor, gridminor (bool, optional) – Whether to draw minor gridlines for the x and y axis. Use gridminor to toggle both.
xlocator, ylocator (locator-spec, optional) – Used to determine the x and y axis tick mark positions. Passed to the Locator constructor. Can be float, list of float, string, or matplotlib.ticker.Locator instance. Use [], 'null', or 'none' for no ticks.
xticks, yticks (optional) – Aliases for xlocator, ylocator.
xlocator_kw, ylocator_kw (dict-like, optional) – Keyword arguments passed to the matplotlib.ticker.Locator class.
xminorlocator, yminorlocator (optional) – As for xlocator, ylocator, but for the minor ticks.
xminorticks, yminorticks (optional) – Aliases for xminorlocator, yminorlocator.
xminorlocator_kw, yminorlocator_kw – As for xlocator_kw, ylocator_kw, but for the minor locator.
xformatter, yformatter (formatter-spec, optional) – Used to determine the x and y axis tick label string format. Passed to the Formatter constructor. Can be string, list of strings, or matplotlib.ticker.Formatter instance. Use [], 'null', or 'none' for no labels.
xticklabels, yticklabels (optional) – Aliases for xformatter, yformatter.
xformatter_kw, yformatter_kw (dict-like, optional) – Keyword arguments passed to the matplotlib.ticker.Formatter class.
xrotation, yrotation (float, optional) – The rotation for x and y axis tick labels. Default is 0 for normal axes, rc['formatter.timerotation'] = 'vertical' for time x axes.
xbounds, ybounds (2-tuple of float, optional) – The x and y axis data bounds within which to draw the spines. For example, the axis range (0, 4) with bounds (1, 4) will prevent the spines from meeting at the origin.
xtickrange, ytickrange (2-tuple of float, optional) – The x and y axis data ranges within which major tick marks are labelled. For example, the tick range (-1, 1) with axis range (-5, 5) and a tick interval of 1 will only label the ticks marks at -1, 0, and 1. See AutoFormatter for details.
xwraprange, ywraprange (2-tuple of float, optional) – The x and y axis data ranges with which major tick mark values are wrapped. For example, the wrap range (0, 3) causes the values 0 through 9 to be formatted as 0, 1, 2, 0, 1, 2, 0, 1, 2, 0. See AutoFormatter for details.
xmargin, ymargin, margin (float, optional) – The default margin between plotted content and the x and y axis spines. Value is proportional to the width, height of the axes. Use this if you want whitespace between plotted content and the spines, but don’t want to explicitly set xlim or ylim.
xticklen, yticklen, ticklen (float or str, optional) – Tick lengths for the x and y axis. Default is rc.ticklen. If float, units are points. If string, interpreted by units. Minor tick lengths are scaled according to rc['tick.lenratio'] = 0.5. Use ticklen and ticklenratio to set both at once.
xlinewidth, ylinewidth, linewidth (color-spec, optional) – Line width for the x and y axis spines and major ticks. Use linewidth to set both at once.
xcolor, ycolor, color (color-spec, optional) – Color for the x and y axis spines, ticks, tick labels, and axis labels. Use color to set both at once.
xgridcolor, ygridcolor, gridcolor (color-spec, optional) – Color for the x and y axis major and minor gridlines. Use gridcolor to set both at once.
fixticks (bool, optional) – Whether to always transform the tick locators to a FixedLocator instance. Default is False. If your axis ticks are doing weird things (for example, ticks drawn outside of the axis spine), try setting this to True.

Other Parameters

title (str, optional) – The axes title.
abc (bool or str, optional) – The “a-b-c” subplot label style. Must contain the character a or A, for example 'a.', or 'A'. If True then the default style of 'a' is used. The a or A is replaced with the alphabetic character matching the number. If number 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 are rc['abc.loc'] = 'left' and rc['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 are rc['abc.border'] = True and rc['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 are rc['abc.bbox'] = False and rc['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 is rc['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 is rc['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 is rc['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 the ax.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.
rowlabels, collabels, llabels, tlabels, rlabels, blabels – Aliases for leftlabels and toplabels, and for leftlabels, toplabels, rightlabels, and bottomlabels, 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 are rc['leftlabel.pad'], rc['toplabel.pad'], rc['rightlabel.pad'], and rc['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 is rc['suptitle.pad'].
suptitle_kw (optional) – Additional settings used to update the super title with text.update().
rc_mode (int, optional) – The context mode passed to context.
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-relevant rc settings. For example, abcstyle='A.' modifies the rc['abc.style'] setting, titleloc='left' modifies the rc['title.loc'] setting, gridminor=True modifies the rc.gridminor setting, and gridbelow=True modifies the rc['grid.below'] setting. Many of the keyword arguments documented above are actually applied by updating the rc settings then retrieving the updated settings.