PlotAxes

class PlotAxes(*args, **kwargs)[source]

Bases: Axes

The second lowest-level Axes subclass used by ultraplot. Implements all plotting overrides.

Parameters:

*args – Passed to matplotlib.axes.Axes.
title (str or sequence, optional) – The axes title. Can optionally be a sequence strings, in which case the title will be selected from the sequence according to number.
abc (bool or str or sequence, default: rc.abc = False) – 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. Can also be a sequence of strings, in which case the “a-b-c” label will be selected sequentially from the list. For example axs.format(abc = ["X", "Y"]) for a two-panel figure, and axes[3:5].format(abc = ["X", "Y"]) for a two-panel subset of a larger figure.

abcloc, titleloc (str, default: rc['abc.loc'] = 'left', rc['title.loc'] = 'center') – Strings indicating the location for the a-b-c label and main title. The following locations are valid:

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'`
left of y axis	`'outer left'`, `'ol'`
right of y axis	`'outer right'`, `'or'`

abcborder, titleborder (bool, default: rc['abc.border'] = True and rc['title.border'] = True) – 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.
abcbbox, titlebbox (bool, default: rc['abc.bbox'] = False and rc['title.bbox'] = False) – 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.
abcpad (float or unit-spec, default: rc['abc.pad']) – Horizontal offset to shift the a-b-c label position. Positive values move the label right, negative values move it left. This is separate from abctitlepad, which controls spacing between abc and title when co-located. If float, units are points. If string, interpreted by units.
abc_kw, title_kw (dict-like, optional) – Additional settings used to update the a-b-c label and title with text.update().
titlepad (float, default: rc['title.pad'] = 5.0) – The padding for the inner and outer titles and a-b-c labels. If float, units are points. If string, interpreted by units.
titleabove (bool, default: rc['title.above'] = True) – Whether to try to put outer titles and a-b-c labels above panels, colorbars, or legends that are above the axes.
abctitlepad (float, default: rc['abc.titlepad'] = 4.0) – The horizontal padding between a-b-c labels and titles in the same location. If float, units are points. If string, interpreted by units.
ltitle, ctitle, rtitle, ultitle, uctitle, urtitle, lltitle, lctitle, lrtitle (str or sequence, :py:class:`optional `) – Shorthands for the below keywords. lefttitle, centertitle, righttitle, upperlefttitle, uppercentertitle, upperrighttitle : str or sequence, optional
lowerlefttitle, lowercentertitle, lowerrighttitle (str or sequence, optional) – Additional titles in specific positions (see title for details). This works as an alternative to the ax.format(title='Title', titleloc=loc) workflow and permits adding more than one title-like label for a single axes.
a, alpha, fc, facecolor, ec, edgecolor, lw, linewidth, ls, linestyle (**default* *) – rc['axes.alpha'] = None (default: 1.0), rc['axes.facecolor'] = 'white' (default: white), rc['axes.edgecolor'] = 'black' (default: black), rc['axes.linewidth'] = 0.6 (default: 0.6), - Additional settings applied to the background patch, and their shorthands. Their defaults values are the 'axes' properties.

Other Parameters:

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 – Remaining keyword arguments are passed to matplotlib.axes.Axes.n Keyword arguments that match the name of an rc setting are passed to ultraplot.config.Configurator.context and used to update the axes. If the setting name has “dots” you can simply omit the dots. For example, abc='A.' modifies the rc.abc 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 internally applied by retrieving settings passed to context.

Methods Summary

`area`(args, *kwargs)	Plot individual, grouped, or overlaid shading patches.
`areax`(args, *kwargs)	Plot individual, grouped, or overlaid shading patches.
`bar`(**kwargs)	Plot individual, grouped, or stacked bars.
`barbs`(**kwargs)	Plot wind barbs.
`barh`(**kwargs)	Plot individual, grouped, or stacked bars.
`beeswarm`(args, *kwargs)	Beeswarm plot with SHAP-style feature value coloring.
`box`(args, *kwargs)	Plot vertical boxes and whiskers with a nice default style.
`boxes`(*[, new_obj, message])
`boxh`(args, *kwargs)	Plot horizontal boxes and whiskers with a nice default style.
`boxplot`(**kwargs)	Plot vertical boxes and whiskers with a nice default style.
`boxploth`(args, *kwargs)	Plot horizontal boxes and whiskers with a nice default style.
`contour`(**kwargs)	Plot contour lines.
`contourf`(**kwargs)	Plot filled contours.
`curved_quiver`(x, y, u, v[, linewidth, ...])	Draws curved vector field arrows (streamlines with arrows) for 2D vector fields.
`fill_between`(**kwargs)	Plot individual, grouped, or overlaid shading patches.
`fill_betweenx`(**kwargs)	Plot individual, grouped, or overlaid shading patches.
`graph`(g[, layout, nodes, edges, labels, ...])	Plot a networkx graph with flexible node, edge, and label options.
`heatmap`(*args[, aspect])	Plot grid boxes with formatting suitable for heatmaps.
`hexbin`(**kwargs)	Plot a 2D hexagonally binned histogram.
`hist`(**kwargs)	Plot vertical histograms.
`hist2d`(**kwargs)	Plot a standard 2D histogram.
`histh`(args, *kwargs)	Plot horizontal histograms.
`hlines`(args, *kwargs)	Plot horizontal lines.
`imshow`(**kwargs)	Plot an image.
`line`(args, *kwargs)	Plot standard lines.
`linex`(args, *kwargs)	Plot standard lines.
`loglog`(args, *kwargs)	Plot loglog
`lollipop`(args, *kwargs)	Plot individual or group lollipop graphs.
`lollipoph`(args, *kwargs)	Plot individual or group lollipop graphs.
`matshow`(**kwargs)	Plot a matrix.
`parametric`(x, y, c, *[, interp, scalex, scaley])	Plot a parametric line.
`pcolor`(**kwargs)	Plot irregular grid boxes.
`pcolorfast`(**kwargs)	Plot grid boxes quickly.
`pcolormesh`(**kwargs)	Plot regular grid boxes.
`pie`(**kwargs)	Plot a pie chart.
`plot`(**kwargs)	Plot standard lines.
`plotx`(args, *kwargs)	Plot standard lines.
`quiver`(**kwargs)	Plot quiver arrows.
`ridgeline`(data, **kwargs)	Create a vertical ridgeline plot (also known as a joyplot).
`ridgelineh`(data, **kwargs)	Create a horizontal ridgeline plot (also known as a joyplot).
`scatter`(**kwargs)	Plot markers with flexible keyword arguments.
`scatterx`(args, *kwargs)	Plot markers with flexible keyword arguments.
`semilogx`(args, *kwargs)	Plot semilogx
`semilogy`(args, *kwargs)	Plot semilogy
`set`(*[, adjustable, agg_filter, alpha, ...])	Set multiple properties at once.
`spy`(**kwargs)	Plot a sparcity pattern.
`stem`(**kwargs)	Plot stem lines.
`stemx`(args, *kwargs)	Plot stem lines.
`step`(**kwargs)	Plot step lines.
`stepx`(args, *kwargs)	Plot step lines.
`stream`(args, *kwargs)	Plot streamlines.
`streamplot`(**kwargs)	Plot streamlines.
`tricontour`(**kwargs)	Plot contour lines on a triangular grid.
`tricontourf`(**kwargs)	Plot filled contours on a triangular grid.
`tripcolor`(**kwargs)	Plot triangular grid boxes.
`violin`(args, *kwargs)	Plot vertical violins with a nice default style matching this matplotlib example.
`violinh`(args, *kwargs)	Plot horizontal violins with a nice default style matching this matplotlib example.
`violinplot`(**kwargs)	Plot vertical violins with a nice default style matching this matplotlib example.
`violinploth`(args, *kwargs)	Plot horizontal violins with a nice default style matching this matplotlib example.
`violins`(*[, new_obj, message])
`vlines`(args, *kwargs)	Plot vertical lines.

Methods Documentation

area(*args, **kwargs)[source]

Plot individual, grouped, or overlaid shading patches.

Parameters:

*args (y2 or x, y2, or x, y1, y2) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only y coordinates are passed, try to infer the x coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the x coordinates are np.arange(0, y2.shape[0]).
- If only x and y2 coordinates are passed, set the y1 coordinates to zero. This draws elements originating from the zero line.
- If both y1 and y2 are provided, draw elements between these points. If either are 2D, draw elements by iterating over each column.
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
stack, stacked (bool, default: False) – Whether to “stack” area patches from successive columns of y data or plot area patches on top of each other.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

where (ndarray, optional) – A boolean mask for the points that should be shaded. See this matplotlib example.
cycle (cycle-spec, optional) – The cycle specifer, passed to the Cycle constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use cycle=False, cycle='none', or cycle=() (analogous to disabling ticks with e.g. xformatter='none'). To restore the default property cycler, use cycle=True.
cycle_kw (dict-like, optional) – Passed to Cycle.
lw, linewidth, linewidths (unit-spec, default: rc['patch.linewidth'] = 0.6) – The edge width of the patch(es). If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: '-') – The edge style of the patch(es).
ec, edgecolor, edgecolors (color-spec, default: 'none') – The edge color of the patch(es).
fc, facecolor, facecolors, fillcolor, fillcolors (color-spec, optional) – The face color of the patch(es). The property cycle is used by default.
a, alpha, alphas (float, optional) – The opacity of the patch(es). Inferred from facecolor and edgecolor by default.
negpos (bool, default: False) – Whether to shade patches where y2 >= y1 with poscolor and where y2 < y1 with negcolor. If True this function will return a length-2 silent list of handles.
negcolor, poscolor (color-spec, default: rc.negcolor = 'blue7', rc.poscolor = 'red7') – Colors to use for the negative and positive patches. Ignored if negpos is False.
edgefix (bool or float, default: rc.edgefix = True) – Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). See this github repo for a demonstration of the problem. If True, a small default linewidth of 0.3 is used to cover up the white lines. If float (e.g. edgefix=0.5), this specific linewidth is used to cover up the white lines. This feature is automatically disabled when the patches have transparency.
inbounds (bool, default: rc['axes.inbounds'] = True) – Whether to restrict the default y (x) axis limits to account for only in-bounds data when the x (y) axis limits have been locked. See also rc['axes.inbounds'] and rc['cmap.inbounds'].
label, value (float or str, optional) – The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally used with 1D positional arguments.
labels, values (sequence of float or sequence of str, optional) – The legend labels or colorbar coordinates used for each plotted element. Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to fill_between.

areax(*args, **kwargs)[source]

Plot individual, grouped, or overlaid shading patches.

Parameters:

*args (x2 or y, x2, or y, x1, x2) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only x coordinates are passed, try to infer the y coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the y coordinates are np.arange(0, x2.shape[0]).
- If only y and x2 coordinates are passed, set the x1 coordinates to zero. This draws elements originating from the zero line.
- If both x1 and x2 are provided, draw elements between these points. If either are 2D, draw elements by iterating over each column.
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
stack, stacked (bool, default: False) – Whether to “stack” area patches from successive columns of x data or plot area patches on top of each other.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

where (ndarray, optional) – A boolean mask for the points that should be shaded. See this matplotlib example.
cycle (cycle-spec, optional) – The cycle specifer, passed to the Cycle constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use cycle=False, cycle='none', or cycle=() (analogous to disabling ticks with e.g. xformatter='none'). To restore the default property cycler, use cycle=True.
cycle_kw (dict-like, optional) – Passed to Cycle.
lw, linewidth, linewidths (unit-spec, default: rc['patch.linewidth'] = 0.6) – The edge width of the patch(es). If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: '-') – The edge style of the patch(es).
ec, edgecolor, edgecolors (color-spec, default: 'none') – The edge color of the patch(es).
fc, facecolor, facecolors, fillcolor, fillcolors (color-spec, optional) – The face color of the patch(es). The property cycle is used by default.
a, alpha, alphas (float, optional) – The opacity of the patch(es). Inferred from facecolor and edgecolor by default.
negpos (bool, default: False) – Whether to shade patches where y2 >= y1 with poscolor and where y2 < y1 with negcolor. If True this function will return a length-2 silent list of handles.
negcolor, poscolor (color-spec, default: rc.negcolor = 'blue7', rc.poscolor = 'red7') – Colors to use for the negative and positive patches. Ignored if negpos is False.
edgefix (bool or float, default: rc.edgefix = True) – Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). See this github repo for a demonstration of the problem. If True, a small default linewidth of 0.3 is used to cover up the white lines. If float (e.g. edgefix=0.5), this specific linewidth is used to cover up the white lines. This feature is automatically disabled when the patches have transparency.
inbounds (bool, default: rc['axes.inbounds'] = True) – Whether to restrict the default y (x) axis limits to account for only in-bounds data when the x (y) axis limits have been locked. See also rc['axes.inbounds'] and rc['cmap.inbounds'].
label, value (float or str, optional) – The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally used with 1D positional arguments.
labels, values (sequence of float or sequence of str, optional) – The legend labels or colorbar coordinates used for each plotted element. Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to fill_betweenx.

bar(**kwargs)[source]

Plot individual, grouped, or stacked bars.

Parameters:

*args (y or x, y) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only y coordinates are passed, try to infer the x coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the x coordinates are np.arange(0, y.shape[0]).
- If the y coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with boxplot, violinplot, or when using means=True or medians=True).
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
width (float or array-like, default: 0.8) – The width(s) of the bars. Can be passed as a third positional argument. If absolute_width is True (the default) these are in units relative to the x coordinate step size. Otherwise these are in x coordinate units.
bottom (float or array-like, default: 0) – The coordinate(s) of the bottom edge of the bars. Can be passed as a fourth positional argument.
absolute_width (bool, default: False) – Whether to make the width units absolute. If True, this restores the default matplotlib behavior.
stack, stacked (bool, default: False) – Whether to “stack” bars from successive columns of y data or plot bars side-by-side in groups.
bar_labels (bool, default rc[``”bar.bar_labels”``]) – Whether to show the height values for vertical bars or width values for horizontal bars.
bar_labels_kw (dict, default None) – Keywords to format the bar_labels, see bar_label().
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

cycle (cycle-spec, optional) – The cycle specifer, passed to the Cycle constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use cycle=False, cycle='none', or cycle=() (analogous to disabling ticks with e.g. xformatter='none'). To restore the default property cycler, use cycle=True.
cycle_kw (dict-like, optional) – Passed to Cycle.
lw, linewidth, linewidths (unit-spec, default: rc['patch.linewidth'] = 0.6) – The edge width of the patch(es). If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: '-') – The edge style of the patch(es).
ec, edgecolor, edgecolors (color-spec, default: 'none') – The edge color of the patch(es).
fc, facecolor, facecolors, fillcolor, fillcolors (color-spec, optional) – The face color of the patch(es). The property cycle is used by default.
a, alpha, alphas (float, optional) – The opacity of the patch(es). Inferred from facecolor and edgecolor by default.
negpos (bool, default: False) – Whether to shade bars where height >= 0 with poscolor and where height < 0 with negcolor. If True this function will return a length-2 silent list of handles.
negcolor, poscolor (color-spec, default: rc.negcolor = 'blue7', rc.poscolor = 'red7') – Colors to use for the negative and positive bars. Ignored if negpos is False.
edgefix (bool or float, default: rc.edgefix = True) – Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). See this github repo for a demonstration of the problem. If True, a small default linewidth of 0.3 is used to cover up the white lines. If float (e.g. edgefix=0.5), this specific linewidth is used to cover up the white lines. This feature is automatically disabled when the patches have transparency.
mean, means (bool, default: False) – Whether to plot the means of each column for 2D y coordinates. Means are calculated with numpy.nanmean. If no other arguments are specified, this also sets barstd=True (and boxstd=True for violin plots).
median, medians (bool, default: False) – Whether to plot the medians of each column for 2D y coordinates. Medians are calculated with numpy.nanmedian. If no other arguments arguments are specified, this also sets barstd=True (and boxstd=True for violin plots).
bars (bool, default: None) – Shorthand for barstd, barstds.
barstd, barstds (bool, float, or 2-tuple of float, optional) – Valid only if mean or median is True. Standard deviation multiples for thin error bars with optional whiskers (i.e., caps). If scalar, then +/- that multiple is used. If True, the default standard deviation range of +/-3 is used.
barpctile, barpctiles (bool, float, or 2-tuple of float, optional) – Valid only if mean or median is True. As with barstd, but instead using percentiles for the error bars. If scalar, that percentile range is used (e.g., 90 shows the 5th to 95th percentiles). If True, the default percentile range of 0 to 100 is used.
bardata (array-like, optional) – Valid only if mean and median are False. If shape is 2 x N, these are the lower and upper bounds for the thin error bars. If shape is N, these are the absolute, symmetric deviations from the central points.
boxes (bool, default: None) – Shorthand for boxstd, boxstds.
boxstd, boxstds, boxpctile, boxpctiles, boxdata (optional) – As with barstd, barpctile, and bardata, but for thicker error bars representing a smaller interval than the thin error bars. If boxstds is True, the default standard deviation range of +/-1 is used. If boxpctiles is True, the default percentile range of 25 to 75 is used (i.e., the interquartile range). When “boxes” and “bars” are combined, this has the effect of drawing miniature box-and-whisker plots.
capsize (float, default: rc['errorbar.capsize'] = 3.0) – The cap size for thin error bars in points.
barz, barzorder, boxz, boxzorder (float, default: 2.5) – The “zorder” for the thin and thick error bars.
barc, barcolor, boxc, boxcolor (color-spec, default: rc['boxplot.whiskerprops.color'] = 'black') – Colors for the thin and thick error bars.
barlw, barlinewidth, boxlw, boxlinewidth (float, default: rc['boxplot.whiskerprops.linewidth'] = 1.0) – Line widths for the thin and thick error bars, in points. The default for boxes is 4 times rc['boxplot.whiskerprops.linewidth'].
boxm, boxmarker (bool or marker-spec, default: 'o') – Whether to draw a small marker in the middle of the box denoting the mean or median position. Ignored if boxes is False.
boxms, boxmarkersize (size-spec, default: (2 * boxlinewidth) ** 2) – The marker size for the boxmarker marker in points ** 2.
boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor (color-spec, default: 'w') – Color, face color, and edge color for the boxmarker marker.
inbounds (bool, default: rc['axes.inbounds'] = True) – Whether to restrict the default y (x) axis limits to account for only in-bounds data when the x (y) axis limits have been locked. See also rc['axes.inbounds'] and rc['cmap.inbounds'].
label, value (float or str, optional) – The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally used with 1D positional arguments.
labels, values (sequence of float or sequence of str, optional) – The legend labels or colorbar coordinates used for each plotted element. Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to bar.

barbs(**kwargs)[source]

Plot wind barbs.

Parameters:

*args (u, v or x, y, u, v) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only u and v coordinates are passed, try to infer the x and y coordinates from the DataFrame indices and columns or the DataArray coordinates. Otherwise, the y coordinates are np.arange(0, y.shape[0]) and the x coordinates are np.arange(0, y.shape[1]).
- For pcolor and pcolormesh, calculate coordinate edges using edges or :func:`~ultraplot.utils.edges2d` if centers were provided. For all other methods, calculate coordinate centers if edges were provided.
- If the x or y coordinates are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. If the u and v coordinates are pint.Quantity, pass the magnitude to the plotting command. A pint.Quantity embedded in an xarray.DataArray is also supported.
c, color, colors (array-like or color-spec, optional) – The colors of the wind barbs passed as either a keyword argument or a fifth positional argument. This can be a single color or a color array to be scaled by cmap and norm.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.
transpose (bool, default: False) – Whether to transpose the input data. This should be used when passing datasets with column-major dimension order (x, y). Otherwise row-major dimension order (y, x) is expected.
order ({'C', 'F'}, default: 'C') – Alternative to transpose. 'C' corresponds to the default C-cyle row-major ordering (equivalent to transpose=False). 'F' corresponds to Fortran-style column-major ordering (equivalent to transpose=True).
globe (bool, default: False) – For ultraplot.axes.GeoAxes only. Whether to enforce global coverage. When set to True this does the following:
1. Interpolates input data to the North and South poles by setting the data values at the poles to the mean from latitudes nearest each pole.
2. Makes meridional coverage “circular”, i.e. the last longitude coordinate equals the first longitude coordinate plus 360°.
3. When basemap is the backend, cycles 1D longitude vectors to fit within the map edges. For example, if the central longitude is 90°, the data is shifted so that it spans -90° to 270°.

Other Parameters:

cmap (colormap-spec, default: rc['cmap.sequential'] = 'Fire' or rc['cmap.diverging'] = 'BuRd') – The colormap specifer, passed to the Colormap constructor function. If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then rc['cmap.diverging'] is used. Otherwise rc['cmap.sequential'] is used.
cmap_kw (dict-like, optional) – Passed to Colormap.
c, color, colors (color-spec or sequence of color-spec, optional) – The color(s) used to create a DiscreteColormap. If not passed, cmap is used.
norm (norm-spec, default: Normalize or DivergingNorm) – The data value normalizer, passed to the Norm constructor function. If discrete is True then 1) this affects the default level-generation algorithm (e.g. norm='log' builds levels in log-space) and 2) this is passed to DiscreteNorm to scale the colors before they are discretized (if norm is not already a DiscreteNorm). If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then DivergingNorm is used. Otherwise Normalize is used.
norm_kw (dict-like, optional) – Passed to Norm.
extend ({'neither', 'both', 'min', 'max'}, default: 'neither') – Direction for drawing colorbar “extensions” indicating out-of-bounds data on the end of the colorbar.
discrete (bool, default: rc['cmap.discrete'] = None) – If False, then DiscreteNorm is not applied to the colormap. Instead, for non-contour plots, the number of levels will be roughly controlled by rc['cmap.lut']. This has a similar effect to using levels=large_number but it may improve rendering speed. Default is True only for contouring commands like contourf and pseudocolor commands like pcolor.
sequential, diverging, cyclic, qualitative (bool, default: None) – Boolean arguments used if cmap is not passed. Set these to True to use the default rc['cmap.sequential'], rc['cmap.diverging'], rc['cmap.cyclic'], and rc['cmap.qualitative'] colormaps. The diverging option also applies DivergingNorm as the default continuous normalizer.
vmin, vmax (float, optional) – The minimum and maximum color scale values used with the norm normalizer. If discrete is False these are the absolute limits, and if discrete is True these are the approximate limits used to automatically determine levels or values lists at “nice” intervals. If levels or values were already passed as lists, these are ignored, and vmin and vmax are set to the minimum and maximum of the lists. If robust was passed, the default vmin and vmax are some percentile range of the data values. Otherwise, the default vmin and vmax are the minimum and maximum of the data values.
N – Shorthand for levels.
levels (int or sequence of float, default: rc['cmap.levels'] = 11) – The number of level edges or a sequence of level edges. If the former, locator is used to generate this many level edges at “nice” intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing levels fail with contour plots).
values (int or sequence of float, default: None) – The number of level centers or a sequence of level centers. If the former, locator is used to generate this many level centers at “nice” intervals. If the latter, levels are inferred using edges. This will override any levels input.
center_levels (bool, default False) – If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented.
robust (bool, float, or 2-tuple, default: rc['cmap.robust'] = False) – If True and vmin or vmax were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, 90 corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers.
inbounds (bool, default: rc['cmap.inbounds'] = True) – If True and vmin or vmax were not provided, when axis limits have been explicitly restricted with set_xlim() or set_ylim(), out-of-bounds data is ignored. See also rc['cmap.inbounds'] and rc['axes.inbounds'].
locator (locator-spec, default: matplotlib.ticker.MaxNLocator) – The locator used to determine level locations if levels or values were not already passed as lists. Passed to the Locator constructor. Default is MaxNLocator with levels integer levels.
locator_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Locator class.
symmetric (bool, default: False) – If True, the normalization range or discrete colormap levels are symmetric about zero.
positive (bool, default: False) – If True, the normalization range or discrete colormap levels are positive with a minimum at zero.
negative (bool, default: False) – If True, the normaliation range or discrete colormap levels are negative with a minimum at zero.
nozero (bool, default: False) – If True, 0 is removed from the level list. This is mainly useful for single-color contour plots.
**kwargs – Passed to matplotlib.axes.Axes.barbs

barh(**kwargs)[source]

Plot individual, grouped, or stacked bars.

Parameters:

*args (x or y, x) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only x coordinates are passed, try to infer the y coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the y coordinates are np.arange(0, x.shape[0]).
- If the x coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with boxplot, violinplot, or when using means=True or medians=True).
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
width (float or array-like, default: 0.8) – The width(s) of the bars. Can be passed as a third positional argument. If absolute_width is True (the default) these are in units relative to the y coordinate step size. Otherwise these are in y coordinate units.
left (float or array-like, default: 0) – The coordinate(s) of the left edge of the bars. Can be passed as a fourth positional argument.
absolute_width (bool, default: False) – Whether to make the width units absolute. If True, this restores the default matplotlib behavior.
stack, stacked (bool, default: False) – Whether to “stack” bars from successive columns of x data or plot bars side-by-side in groups.
bar_labels (bool, default rc[``”bar.bar_labels”``]) – Whether to show the height values for vertical bars or width values for horizontal bars.
bar_labels_kw (dict, default None) – Keywords to format the bar_labels, see bar_label().
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

cycle (cycle-spec, optional) – The cycle specifer, passed to the Cycle constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use cycle=False, cycle='none', or cycle=() (analogous to disabling ticks with e.g. xformatter='none'). To restore the default property cycler, use cycle=True.
cycle_kw (dict-like, optional) – Passed to Cycle.
lw, linewidth, linewidths (unit-spec, default: rc['patch.linewidth'] = 0.6) – The edge width of the patch(es). If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: '-') – The edge style of the patch(es).
ec, edgecolor, edgecolors (color-spec, default: 'none') – The edge color of the patch(es).
fc, facecolor, facecolors, fillcolor, fillcolors (color-spec, optional) – The face color of the patch(es). The property cycle is used by default.
a, alpha, alphas (float, optional) – The opacity of the patch(es). Inferred from facecolor and edgecolor by default.
negpos (bool, default: False) – Whether to shade bars where height >= 0 with poscolor and where height < 0 with negcolor. If True this function will return a length-2 silent list of handles.
negcolor, poscolor (color-spec, default: rc.negcolor = 'blue7', rc.poscolor = 'red7') – Colors to use for the negative and positive bars. Ignored if negpos is False.
edgefix (bool or float, default: rc.edgefix = True) – Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). See this github repo for a demonstration of the problem. If True, a small default linewidth of 0.3 is used to cover up the white lines. If float (e.g. edgefix=0.5), this specific linewidth is used to cover up the white lines. This feature is automatically disabled when the patches have transparency.
mean, means (bool, default: False) – Whether to plot the means of each column for 2D x coordinates. Means are calculated with numpy.nanmean. If no other arguments are specified, this also sets barstd=True (and boxstd=True for violin plots).
median, medians (bool, default: False) – Whether to plot the medians of each column for 2D x coordinates. Medians are calculated with numpy.nanmedian. If no other arguments arguments are specified, this also sets barstd=True (and boxstd=True for violin plots).
bars (bool, default: None) – Shorthand for barstd, barstds.
barstd, barstds (bool, float, or 2-tuple of float, optional) – Valid only if mean or median is True. Standard deviation multiples for thin error bars with optional whiskers (i.e., caps). If scalar, then +/- that multiple is used. If True, the default standard deviation range of +/-3 is used.
barpctile, barpctiles (bool, float, or 2-tuple of float, optional) – Valid only if mean or median is True. As with barstd, but instead using percentiles for the error bars. If scalar, that percentile range is used (e.g., 90 shows the 5th to 95th percentiles). If True, the default percentile range of 0 to 100 is used.
bardata (array-like, optional) – Valid only if mean and median are False. If shape is 2 x N, these are the lower and upper bounds for the thin error bars. If shape is N, these are the absolute, symmetric deviations from the central points.
boxes (bool, default: None) – Shorthand for boxstd, boxstds.
boxstd, boxstds, boxpctile, boxpctiles, boxdata (optional) – As with barstd, barpctile, and bardata, but for thicker error bars representing a smaller interval than the thin error bars. If boxstds is True, the default standard deviation range of +/-1 is used. If boxpctiles is True, the default percentile range of 25 to 75 is used (i.e., the interquartile range). When “boxes” and “bars” are combined, this has the effect of drawing miniature box-and-whisker plots.
capsize (float, default: rc['errorbar.capsize'] = 3.0) – The cap size for thin error bars in points.
barz, barzorder, boxz, boxzorder (float, default: 2.5) – The “zorder” for the thin and thick error bars.
barc, barcolor, boxc, boxcolor (color-spec, default: rc['boxplot.whiskerprops.color'] = 'black') – Colors for the thin and thick error bars.
barlw, barlinewidth, boxlw, boxlinewidth (float, default: rc['boxplot.whiskerprops.linewidth'] = 1.0) – Line widths for the thin and thick error bars, in points. The default for boxes is 4 times rc['boxplot.whiskerprops.linewidth'].
boxm, boxmarker (bool or marker-spec, default: 'o') – Whether to draw a small marker in the middle of the box denoting the mean or median position. Ignored if boxes is False.
boxms, boxmarkersize (size-spec, default: (2 * boxlinewidth) ** 2) – The marker size for the boxmarker marker in points ** 2.
boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor (color-spec, default: 'w') – Color, face color, and edge color for the boxmarker marker.
inbounds (bool, default: rc['axes.inbounds'] = True) – Whether to restrict the default y (x) axis limits to account for only in-bounds data when the x (y) axis limits have been locked. See also rc['axes.inbounds'] and rc['cmap.inbounds'].
label, value (float or str, optional) – The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally used with 1D positional arguments.
labels, values (sequence of float or sequence of str, optional) – The legend labels or colorbar coordinates used for each plotted element. Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to barh.

beeswarm(*args, **kwargs)[source]

Beeswarm plot with SHAP-style feature value coloring.

Parameters:

data (array-like) – The data to be plotted. It is assumed the shape of data is (N, M) where N is the number of points and M is the number of features.
levels (array-like, optional) – The levels to use for the beeswarm plot. If not provided, the levels are automatically determined based on the data.
n_bins (int or array-like, default: 50) – Number of bins to use to reduce the overlap between points.
Bins are used to determine how crowded the points are for each level of the y coordinate.

s, size, ms, markersizefloat or array-like or unit-spec, optional
The marker size area(s). If this is an array matching the shape of x and y, the units are scaled by smin and smax. If this contains unit string(s), it is processed by units and represents the width rather than area.

c, color, colors, mc, markercolor, markercolors, fc, facecolor, facecolorsarray-like or color-spec, optional
The marker color(s). If this is an array matching the shape of x and y, the colors are generated using cmap, norm, vmin, and vmax. Otherwise, this should be a valid matplotlib color.

smin, smaxfloat, optional
The minimum and maximum marker size area in units points ** 2. Ignored if absolute_size is True. Default value for smin is 1 and for smax is the square of rc['lines.markersize'] = 6.0.

area_sizebool, default: True
Whether the marker sizes s are scaled by area or by radius. The default True is consistent with matplotlib. When absolute_size is True, the s units are points ** 2 if area_size is True and points if area_size is False.

absolute_sizebool, default: True or False
Whether s should be taken to represent “absolute” marker sizes in units points or points ** 2 or “relative” marker sizes scaled by smin and smax. Default is True if s is scalar and False if s is array-like or smin or smax were passed.

vmin, vmaxfloat, optional
The minimum and maximum color scale values used with the norm normalizer. If discrete is False these are the absolute limits, and if discrete is True these are the approximate limits used to automatically determine levels or values lists at “nice” intervals. If levels or values were already passed as lists, these are ignored, and vmin and vmax are set to the minimum and maximum of the lists. If robust was passed, the default vmin and vmax are some percentile range of the data values. Otherwise, the default vmin and vmax are the minimum and maximum of the data values.

datadict-like, optional
A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles,
legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

cmap (colormap-spec, default: rc['cmap.sequential'] = 'Fire' or rc['cmap.diverging'] = 'BuRd') – The colormap specifer, passed to the Colormap constructor function. If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then rc['cmap.diverging'] is used. Otherwise rc['cmap.sequential'] is used.
cmap_kw (dict-like, optional) – Passed to Colormap.
c, color, colors (color-spec or sequence of color-spec, optional) – The color(s) used to create a DiscreteColormap. If not passed, cmap is used.
norm (norm-spec, default: Normalize or DivergingNorm) – The data value normalizer, passed to the Norm constructor function. If discrete is True then 1) this affects the default level-generation algorithm (e.g. norm='log' builds levels in log-space) and 2) this is passed to DiscreteNorm to scale the colors before they are discretized (if norm is not already a DiscreteNorm). If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then DivergingNorm is used. Otherwise Normalize is used.
norm_kw (dict-like, optional) – Passed to Norm.
extend ({'neither', 'both', 'min', 'max'}, default: 'neither') – Direction for drawing colorbar “extensions” indicating out-of-bounds data on the end of the colorbar.
discrete (bool, default: rc['cmap.discrete'] = None) – If False, then DiscreteNorm is not applied to the colormap. Instead, for non-contour plots, the number of levels will be roughly controlled by rc['cmap.lut']. This has a similar effect to using levels=large_number but it may improve rendering speed. Default is True only for contouring commands like contourf and pseudocolor commands like pcolor.
sequential, diverging, cyclic, qualitative (bool, default: None) – Boolean arguments used if cmap is not passed. Set these to True
to use the default rc['cmap.sequential'], rc['cmap.diverging'], rc['cmap.cyclic'], and rc['cmap.qualitative'] colormaps. The diverging option also applies DivergingNorm as the default continuous normalizer.

N
Shorthand for levels.
levels (int or sequence of float, default: rc['cmap.levels'] = 11) – The number of level edges or a sequence of level edges. If the former, locator is used to generate this many level edges at “nice” intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing levels fail with contour plots).
values (int or sequence of float, default: None) – The number of level centers or a sequence of level centers. If the former, locator is used to generate this many level centers at “nice” intervals. If the latter, levels are inferred using edges. This will override any levels input.
center_levels (bool, default False) – If set to true, the discrete color bar bins will be centered on the level values
instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented.

robustbool, float, or 2-tuple, default: rc['cmap.robust'] = False
If True and vmin or vmax were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, 90 corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers.
inbounds (bool, default: rc['cmap.inbounds'] = True) – If True and vmin or vmax were not provided, when axis limits have been explicitly restricted with set_xlim() or set_ylim(), out-of-bounds data is ignored. See also rc['cmap.inbounds'] and rc['axes.inbounds'].
locator (locator-spec, default: matplotlib.ticker.MaxNLocator) – The locator used to determine level locations if levels or values were not already passed as lists. Passed to the Locator constructor. Default is MaxNLocator with levels integer levels.
locator_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Locator class.
symmetric (bool, default: False) – If True, the normalization range or discrete colormap levels are symmetric about zero.
positive (bool, default: False) – If True, the normalization range or discrete colormap levels are positive with a minimum at zero.
negative (bool, default: False) – If True, the normaliation range or discrete colormap levels are negative with a minimum at zero.
nozero (bool, default: False) – If True, 0 is removed from the level list. This is mainly useful for
single-color contour plots.

cyclecycle-spec, optional
The cycle specifer, passed to the Cycle constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use cycle=False, cycle='none', or cycle=() (analogous to disabling ticks with e.g. xformatter='none'). To restore the default property cycler, use cycle=True.
cycle_kw (dict-like, optional) – Passed to Cycle. lw, linewidth, linewidths, mew, markeredgewidth, markeredgewidths : float or sequence, optional

The marker edge width(s).

edgecolors, markeredgecolor, markeredgecolorscolor-spec or sequence, optional
The marker edge color(s).

mean, meansbool, default: False
Whether to plot the means of each column for 2D y coordinates. Means are calculated with numpy.nanmean. If no other arguments are specified, this also sets barstd=True (and boxstd=True for violin plots).
median, medians (bool, default: False) – Whether to plot the medians of each column for 2D y coordinates. Medians
are calculated with numpy.nanmedian. If no other arguments arguments are specified, this also sets barstd=True (and boxstd=True for violin plots).

barsbool, default: None
Shorthand for barstd, barstds.
barstd, barstds (bool, float, or 2-tuple of float, optional) – Valid only if mean or median is True. Standard deviation multiples for thin error bars with optional whiskers (i.e., caps). If scalar, then +/- that multiple is used. If True, the default standard deviation range of +/-3 is used.
barpctile, barpctiles (bool, float, or 2-tuple of float, optional) – Valid only if mean or median is True. As with barstd, but instead using percentiles for the error bars. If scalar, that percentile range is used (e.g., 90 shows the 5th to 95th percentiles). If True, the default percentile range of 0 to 100 is used.
bardata (array-like, optional) – Valid only if mean and median are False. If shape is 2 x N, these are the lower and upper bounds for the thin error bars. If shape is N, these are the absolute, symmetric deviations from the central points.
boxes (bool, default: None) – Shorthand for boxstd, boxstds.
boxstd, boxstds, boxpctile, boxpctiles, boxdata (optional) – As with barstd, barpctile, and bardata, but for thicker error bars representing a smaller interval than the thin error bars. If boxstds is True, the default standard deviation range of +/-1 is used. If boxpctiles is True, the default percentile range of 25 to 75 is used (i.e., the interquartile range). When “boxes” and “bars” are combined, this has the effect of drawing miniature box-and-whisker plots.
capsize (float, default: rc['errorbar.capsize'] = 3.0) – The cap size for thin error bars in points.
barz, barzorder, boxz, boxzorder (float, default: 2.5) – The “zorder” for the thin and thick error bars.
barc, barcolor, boxc, boxcolor (color-spec, default: rc['boxplot.whiskerprops.color'] = 'black') – Colors for the thin and thick error bars.
barlw, barlinewidth, boxlw, boxlinewidth (float, default: rc['boxplot.whiskerprops.linewidth'] = 1.0) – Line widths for the thin and thick error bars, in points. The default for boxes is 4 times rc['boxplot.whiskerprops.linewidth'].
boxm, boxmarker (bool or marker-spec, default: 'o') – Whether to draw a small marker in the middle of the box denoting the mean or median position. Ignored if boxes is False.
boxms, boxmarkersize (size-spec, default: (2 * boxlinewidth) ** 2) – The marker size for the boxmarker marker in points ** 2.
boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor (color-spec, default: 'w') – Color, face color, and edge color for the boxmarker marker. shade : bool, default: None

Shorthand for shadestd.
shadestd, shadestds, shadepctile, shadepctiles, shadedata (optional) – As with barstd, barpctile, and bardata, but using shading to indicate the error range. If shadestds is True, the default standard deviation range of +/-2 is used. If shadepctiles is True, the default percentile range of 10 to 90 is used.
fade (bool, default: None) – Shorthand for fadestd.
fadestd, fadestds, fadepctile, fadepctiles, fadedata (optional) – As with shadestd, shadepctile, and shadedata, but for an additional, more faded, secondary shaded region. If fadestds is True, the default standard deviation range of +/-3 is used. If fadepctiles is True, the default percentile range of 0 to 100 is used.
shadec, shadecolor, fadec, fadecolor (color-spec, default: None) – Colors for the different shaded regions. The parent artist color is used by default.
shadez, shadezorder, fadez, fadezorder (float, default: 1.5) – The “zorder” for the different shaded regions.
shadea, shadealpha, fadea, fadealpha (float, default: 0.4, 0.2) – The opacity for the different shaded regions.
shadelw, shadelinewidth, fadelw, fadelinewidth (float, default: rc['patch.linewidth'] = 0.6.) – The edge line width for the shading patches.
shdeec, shadeedgecolor, fadeec, fadeedgecolor (float, default: 'none') – The edge color for the shading patches.
shadelabel, fadelabel (bool or str, optional) – Labels for the shaded regions to be used as separate legend entries. To toggle
labels “on” and apply a default label, use e.g. shadelabel=True. To apply a custom label, use e.g. shadelabel='label'. Otherwise, the shading is drawn underneath the line and/or marker in the legend entry.

inboundsbool, default: rc['axes.inbounds'] = True
Whether to restrict the default y (x) axis limits to account for only in-bounds data when the x (y) axis limits have been locked. See also rc['axes.inbounds'] and rc['cmap.inbounds'].

label, valuefloat or str, optional
The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally used with 1D positional arguments.
labels, values (sequence of float or sequence of str, optional) – The legend labels or colorbar coordinates used for each plotted element.
Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments.

colorbarbool, int, or str, optional
If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend. **kwargs

Passed to scatter.

See also

PlotAxes.scatter, PlotAxes.scatterx, matplotlib.axes.Axes.scatter

box(*args, **kwargs)[source]

Plot vertical boxes and whiskers with a nice default style.

Parameters:

*args (y or x, y) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only y coordinates are passed, try to infer the x coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the x coordinates are np.arange(0, y.shape[0]).
- If the y coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with boxplot, violinplot, or when using means=True or medians=True).
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

fill (bool, default: True) – Whether to fill the box with a color.
mean, means (bool, default: False) – If True, this passes showmeans=True and meanline=True to matplotlib.axes.Axes.boxplot. Adds mean lines alongside the median.
cycle (cycle-spec, optional) – The cycle specifer, passed to the Cycle constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use cycle=False, cycle='none', or cycle=() (analogous to disabling ticks with e.g. xformatter='none'). To restore the default property cycler, use cycle=True.
cycle_kw (dict-like, optional) – Passed to Cycle.
lw, linewidth, linewidths (unit-spec, default: rc['patch.linewidth'] = 0.6) – The edge width of the patch(es). If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: '-') – The edge style of the patch(es).
ec, edgecolor, edgecolors (color-spec, default: 'black') – The edge color of the patch(es).
fc, facecolor, facecolors, fillcolor, fillcolors (color-spec, optional) – The face color of the patch(es). The property cycle is used by default.
a, alpha, alphas (float, optional) – The opacity of the patch(es). Inferred from facecolor and edgecolor by default.
m, marker, ms, markersize (float or str, optional) – Marker style and size for the ‘fliers’, i.e. outliers. See the boxplot.flierprops rcParams settings.
meanls, medianls, meanlinestyle, medianlinestyle, meanlinestyles, medianlinestyles (str, optional) – Line style for the mean and median lines drawn across the box. See the boxplot.meanprops and boxplot.medianprops rcParams settings.
boxc, capc, whiskerc, flierc, meanc, medianc, boxcolor, capcolor, whiskercolor, fliercolor, meancolor, mediancolor boxcolors, capcolors, whiskercolors, fliercolors, meancolors, mediancolors (color-spec or sequence, optional) – Color of various boxplot components. If a sequence, should be the same length as the number of boxes. These are shorthands so you don’t have to pass e.g. a boxprops dictionary keyword. See the boxplot.boxprops, boxplot.capprops, boxplot.whiskerprops, boxplot.flierprops, boxplot.meanprops, and boxplot.medianprops rcParams settings.
boxlw, caplw, whiskerlw, flierlw, meanlw, medianlw, boxlinewidth, caplinewidth, meanlinewidth, medianlinewidth, whiskerlinewidth, flierlinewidth, boxlinewidths, caplinewidths, meanlinewidths, medianlinewidths, whiskerlinewidths, flierlinewidths (float, optional) – Line width of various boxplot components. These are shorthands so you don’t have to pass e.g. a boxprops dictionary keyword. See the boxplot.boxprops, boxplot.capprops, boxplot.whiskerprops, boxplot.flierprops, boxplot.meanprops, and boxplot.medianprops rcParams settings.
label, value (float or str, optional) – The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally used with 1D positional arguments.
labels, values (sequence of float or sequence of str, optional) – The legend labels or colorbar coordinates used for each plotted element. Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments.
**kwargs – Passed to matplotlib.axes.Axes.boxplot.

boxes(*, new_obj=<function PlotAxes.box>, message="'boxes' was deprecated in version 0.8.0 and may be removed in the next major release (version 2.0.0). Please use 'box' instead.", **kwargs)

boxh(*args, **kwargs)[source]

Plot horizontal boxes and whiskers with a nice default style.

Parameters:

*args (x or y, x) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only x coordinates are passed, try to infer the y coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the y coordinates are np.arange(0, x.shape[0]).
- If the x coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with boxplot, violinplot, or when using means=True or medians=True).
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

fill (bool, default: True) – Whether to fill the box with a color.
mean, means (bool, default: False) – If True, this passes showmeans=True and meanline=True to matplotlib.axes.Axes.boxplot. Adds mean lines alongside the median.
cycle (cycle-spec, optional) – The cycle specifer, passed to the Cycle constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use cycle=False, cycle='none', or cycle=() (analogous to disabling ticks with e.g. xformatter='none'). To restore the default property cycler, use cycle=True.
cycle_kw (dict-like, optional) – Passed to Cycle.
lw, linewidth, linewidths (unit-spec, default: rc['patch.linewidth'] = 0.6) – The edge width of the patch(es). If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: '-') – The edge style of the patch(es).
ec, edgecolor, edgecolors (color-spec, default: 'black') – The edge color of the patch(es).
fc, facecolor, facecolors, fillcolor, fillcolors (color-spec, optional) – The face color of the patch(es). The property cycle is used by default.
a, alpha, alphas (float, optional) – The opacity of the patch(es). Inferred from facecolor and edgecolor by default.
m, marker, ms, markersize (float or str, optional) – Marker style and size for the ‘fliers’, i.e. outliers. See the boxplot.flierprops rcParams settings.
meanls, medianls, meanlinestyle, medianlinestyle, meanlinestyles, medianlinestyles (str, optional) – Line style for the mean and median lines drawn across the box. See the boxplot.meanprops and boxplot.medianprops rcParams settings.
boxc, capc, whiskerc, flierc, meanc, medianc, boxcolor, capcolor, whiskercolor, fliercolor, meancolor, mediancolor boxcolors, capcolors, whiskercolors, fliercolors, meancolors, mediancolors (color-spec or sequence, optional) – Color of various boxplot components. If a sequence, should be the same length as the number of boxes. These are shorthands so you don’t have to pass e.g. a boxprops dictionary keyword. See the boxplot.boxprops, boxplot.capprops, boxplot.whiskerprops, boxplot.flierprops, boxplot.meanprops, and boxplot.medianprops rcParams settings.
boxlw, caplw, whiskerlw, flierlw, meanlw, medianlw, boxlinewidth, caplinewidth, meanlinewidth, medianlinewidth, whiskerlinewidth, flierlinewidth, boxlinewidths, caplinewidths, meanlinewidths, medianlinewidths, whiskerlinewidths, flierlinewidths (float, optional) – Line width of various boxplot components. These are shorthands so you don’t have to pass e.g. a boxprops dictionary keyword. See the boxplot.boxprops, boxplot.capprops, boxplot.whiskerprops, boxplot.flierprops, boxplot.meanprops, and boxplot.medianprops rcParams settings.
label, value (float or str, optional) – The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally used with 1D positional arguments.
labels, values (sequence of float or sequence of str, optional) – The legend labels or colorbar coordinates used for each plotted element. Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments.
**kwargs – Passed to matplotlib.axes.Axes.boxplot.

boxplot(**kwargs)[source]

Plot vertical boxes and whiskers with a nice default style.

Parameters:

*args (y or x, y) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only y coordinates are passed, try to infer the x coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the x coordinates are np.arange(0, y.shape[0]).
- If the y coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with boxplot, violinplot, or when using means=True or medians=True).
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

fill (bool, default: True) – Whether to fill the box with a color.
mean, means (bool, default: False) – If True, this passes showmeans=True and meanline=True to matplotlib.axes.Axes.boxplot. Adds mean lines alongside the median.
cycle (cycle-spec, optional) – The cycle specifer, passed to the Cycle constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use cycle=False, cycle='none', or cycle=() (analogous to disabling ticks with e.g. xformatter='none'). To restore the default property cycler, use cycle=True.
cycle_kw (dict-like, optional) – Passed to Cycle.
lw, linewidth, linewidths (unit-spec, default: rc['patch.linewidth'] = 0.6) – The edge width of the patch(es). If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: '-') – The edge style of the patch(es).
ec, edgecolor, edgecolors (color-spec, default: 'black') – The edge color of the patch(es).
fc, facecolor, facecolors, fillcolor, fillcolors (color-spec, optional) – The face color of the patch(es). The property cycle is used by default.
a, alpha, alphas (float, optional) – The opacity of the patch(es). Inferred from facecolor and edgecolor by default.
m, marker, ms, markersize (float or str, optional) – Marker style and size for the ‘fliers’, i.e. outliers. See the boxplot.flierprops rcParams settings.
meanls, medianls, meanlinestyle, medianlinestyle, meanlinestyles, medianlinestyles (str, optional) – Line style for the mean and median lines drawn across the box. See the boxplot.meanprops and boxplot.medianprops rcParams settings.
boxc, capc, whiskerc, flierc, meanc, medianc, boxcolor, capcolor, whiskercolor, fliercolor, meancolor, mediancolor boxcolors, capcolors, whiskercolors, fliercolors, meancolors, mediancolors (color-spec or sequence, optional) – Color of various boxplot components. If a sequence, should be the same length as the number of boxes. These are shorthands so you don’t have to pass e.g. a boxprops dictionary keyword. See the boxplot.boxprops, boxplot.capprops, boxplot.whiskerprops, boxplot.flierprops, boxplot.meanprops, and boxplot.medianprops rcParams settings.
boxlw, caplw, whiskerlw, flierlw, meanlw, medianlw, boxlinewidth, caplinewidth, meanlinewidth, medianlinewidth, whiskerlinewidth, flierlinewidth, boxlinewidths, caplinewidths, meanlinewidths, medianlinewidths, whiskerlinewidths, flierlinewidths (float, optional) – Line width of various boxplot components. These are shorthands so you don’t have to pass e.g. a boxprops dictionary keyword. See the boxplot.boxprops, boxplot.capprops, boxplot.whiskerprops, boxplot.flierprops, boxplot.meanprops, and boxplot.medianprops rcParams settings.
label, value (float or str, optional) – The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally used with 1D positional arguments.
labels, values (sequence of float or sequence of str, optional) – The legend labels or colorbar coordinates used for each plotted element. Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments.
**kwargs – Passed to matplotlib.axes.Axes.boxplot.

boxploth(*args, **kwargs)[source]

Plot horizontal boxes and whiskers with a nice default style.

Parameters:

*args (x or y, x) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only x coordinates are passed, try to infer the y coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the y coordinates are np.arange(0, x.shape[0]).
- If the x coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with boxplot, violinplot, or when using means=True or medians=True).
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

fill (bool, default: True) – Whether to fill the box with a color.
mean, means (bool, default: False) – If True, this passes showmeans=True and meanline=True to matplotlib.axes.Axes.boxplot. Adds mean lines alongside the median.
cycle (cycle-spec, optional) – The cycle specifer, passed to the Cycle constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use cycle=False, cycle='none', or cycle=() (analogous to disabling ticks with e.g. xformatter='none'). To restore the default property cycler, use cycle=True.
cycle_kw (dict-like, optional) – Passed to Cycle.
lw, linewidth, linewidths (unit-spec, default: rc['patch.linewidth'] = 0.6) – The edge width of the patch(es). If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: '-') – The edge style of the patch(es).
ec, edgecolor, edgecolors (color-spec, default: 'black') – The edge color of the patch(es).
fc, facecolor, facecolors, fillcolor, fillcolors (color-spec, optional) – The face color of the patch(es). The property cycle is used by default.
a, alpha, alphas (float, optional) – The opacity of the patch(es). Inferred from facecolor and edgecolor by default.
m, marker, ms, markersize (float or str, optional) – Marker style and size for the ‘fliers’, i.e. outliers. See the boxplot.flierprops rcParams settings.
meanls, medianls, meanlinestyle, medianlinestyle, meanlinestyles, medianlinestyles (str, optional) – Line style for the mean and median lines drawn across the box. See the boxplot.meanprops and boxplot.medianprops rcParams settings.
boxc, capc, whiskerc, flierc, meanc, medianc, boxcolor, capcolor, whiskercolor, fliercolor, meancolor, mediancolor boxcolors, capcolors, whiskercolors, fliercolors, meancolors, mediancolors (color-spec or sequence, optional) – Color of various boxplot components. If a sequence, should be the same length as the number of boxes. These are shorthands so you don’t have to pass e.g. a boxprops dictionary keyword. See the boxplot.boxprops, boxplot.capprops, boxplot.whiskerprops, boxplot.flierprops, boxplot.meanprops, and boxplot.medianprops rcParams settings.
boxlw, caplw, whiskerlw, flierlw, meanlw, medianlw, boxlinewidth, caplinewidth, meanlinewidth, medianlinewidth, whiskerlinewidth, flierlinewidth, boxlinewidths, caplinewidths, meanlinewidths, medianlinewidths, whiskerlinewidths, flierlinewidths (float, optional) – Line width of various boxplot components. These are shorthands so you don’t have to pass e.g. a boxprops dictionary keyword. See the boxplot.boxprops, boxplot.capprops, boxplot.whiskerprops, boxplot.flierprops, boxplot.meanprops, and boxplot.medianprops rcParams settings.
label, value (float or str, optional) – The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally used with 1D positional arguments.
labels, values (sequence of float or sequence of str, optional) – The legend labels or colorbar coordinates used for each plotted element. Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments.
**kwargs – Passed to matplotlib.axes.Axes.boxplot.

contour(**kwargs)[source]

Plot contour lines.

Parameters:

*args (z or x, y, z) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only z coordinates are passed, try to infer the x and y coordinates from the DataFrame indices and columns or the DataArray coordinates. Otherwise, the y coordinates are np.arange(0, y.shape[0]) and the x coordinates are np.arange(0, y.shape[1]).
- For pcolor and pcolormesh, calculate coordinate edges using edges or :func:`~ultraplot.utils.edges2d` if centers were provided. For all other methods, calculate coordinate centers if edges were provided.
- If the x or y coordinates are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. If the z coordinates are pint.Quantity, pass the magnitude to the plotting command. A pint.Quantity embedded in an xarray.DataArray is also supported.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.
transpose (bool, default: False) – Whether to transpose the input data. This should be used when passing datasets with column-major dimension order (x, y). Otherwise row-major dimension order (y, x) is expected.
order ({'C', 'F'}, default: 'C') – Alternative to transpose. 'C' corresponds to the default C-cyle row-major ordering (equivalent to transpose=False). 'F' corresponds to Fortran-style column-major ordering (equivalent to transpose=True).
globe (bool, default: False) – For ultraplot.axes.GeoAxes only. Whether to enforce global coverage. When set to True this does the following:
1. Interpolates input data to the North and South poles by setting the data values at the poles to the mean from latitudes nearest each pole.
2. Makes meridional coverage “circular”, i.e. the last longitude coordinate equals the first longitude coordinate plus 360°.
3. When basemap is the backend, cycles 1D longitude vectors to fit within the map edges. For example, if the central longitude is 90°, the data is shifted so that it spans -90° to 270°.

Other Parameters:

cmap (colormap-spec, default: rc['cmap.sequential'] = 'Fire' or rc['cmap.diverging'] = 'BuRd') – The colormap specifer, passed to the Colormap constructor function. If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then rc['cmap.diverging'] is used. Otherwise rc['cmap.sequential'] is used.
cmap_kw (dict-like, optional) – Passed to Colormap.
c, color, colors (color-spec or sequence of color-spec, optional) – The color(s) used to create a DiscreteColormap. If not passed, cmap is used.
norm (norm-spec, default: Normalize or DivergingNorm) – The data value normalizer, passed to the Norm constructor function. If discrete is True then 1) this affects the default level-generation algorithm (e.g. norm='log' builds levels in log-space) and 2) this is passed to DiscreteNorm to scale the colors before they are discretized (if norm is not already a DiscreteNorm). If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then DivergingNorm is used. Otherwise Normalize is used.
norm_kw (dict-like, optional) – Passed to Norm.
extend ({'neither', 'both', 'min', 'max'}, default: 'neither') – Direction for drawing colorbar “extensions” indicating out-of-bounds data on the end of the colorbar.
discrete (bool, default: rc['cmap.discrete'] = None) – If False, then DiscreteNorm is not applied to the colormap. Instead, for non-contour plots, the number of levels will be roughly controlled by rc['cmap.lut']. This has a similar effect to using levels=large_number but it may improve rendering speed. Default is True only for contouring commands like contourf and pseudocolor commands like pcolor.
sequential, diverging, cyclic, qualitative (bool, default: None) – Boolean arguments used if cmap is not passed. Set these to True to use the default rc['cmap.sequential'], rc['cmap.diverging'], rc['cmap.cyclic'], and rc['cmap.qualitative'] colormaps. The diverging option also applies DivergingNorm as the default continuous normalizer.
vmin, vmax (float, optional) – The minimum and maximum color scale values used with the norm normalizer. If discrete is False these are the absolute limits, and if discrete is True these are the approximate limits used to automatically determine levels or values lists at “nice” intervals. If levels or values were already passed as lists, these are ignored, and vmin and vmax are set to the minimum and maximum of the lists. If robust was passed, the default vmin and vmax are some percentile range of the data values. Otherwise, the default vmin and vmax are the minimum and maximum of the data values.
N – Shorthand for levels.
levels (int or sequence of float, default: rc['cmap.levels'] = 11) – The number of level edges or a sequence of level edges. If the former, locator is used to generate this many level edges at “nice” intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing levels fail with contour plots).
values (int or sequence of float, default: None) – The number of level centers or a sequence of level centers. If the former, locator is used to generate this many level centers at “nice” intervals. If the latter, levels are inferred using edges. This will override any levels input.
center_levels (bool, default False) – If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented.
robust (bool, float, or 2-tuple, default: rc['cmap.robust'] = False) – If True and vmin or vmax were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, 90 corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers.
inbounds (bool, default: rc['cmap.inbounds'] = True) – If True and vmin or vmax were not provided, when axis limits have been explicitly restricted with set_xlim() or set_ylim(), out-of-bounds data is ignored. See also rc['cmap.inbounds'] and rc['axes.inbounds'].
locator (locator-spec, default: matplotlib.ticker.MaxNLocator) – The locator used to determine level locations if levels or values were not already passed as lists. Passed to the Locator constructor. Default is MaxNLocator with levels integer levels.
locator_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Locator class.
symmetric (bool, default: False) – If True, the normalization range or discrete colormap levels are symmetric about zero.
positive (bool, default: False) – If True, the normalization range or discrete colormap levels are positive with a minimum at zero.
negative (bool, default: False) – If True, the normaliation range or discrete colormap levels are negative with a minimum at zero.
nozero (bool, default: False) – If True, 0 is removed from the level list. This is mainly useful for single-color contour plots.
lw, linewidth, linewidths (unit-spec, default: 0.3 or rc['lines.linewidth'] = 1.5) – The width of the line contours. Default is 0.3 when adding to filled contours or rc['lines.linewidth'] = 1.5 otherwise. If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: '-' or rc['contour.negative_linestyle'] = 'dashed') – The style of the line contours. Default is '-' for positive contours and rc['contour.negative_linestyle'] for negative contours.
ec, edgecolor, edgecolors (color-spec, default: 'k' or inferred) – The color of the line contours. Default is 'k' when adding to filled contours or inferred from color or cmap otherwise.
a, alpha, alpha (float, optional) – The opacity of the contours. Inferred from edgecolor by default.
label (str, optional) – The legend label to be used for this object. In the case of contours, this is paired with the the central artist in the artist list returned by matplotlib.contour.ContourSet.legend_elements.
labels (bool, optional) – Whether to apply labels to contours and grid boxes. The text will be white when the luminance of the underlying filled contour or grid box is less than 50 and black otherwise.
labels_kw (dict-like, optional) – Ignored if labels is False. Extra keyword args for the labels. For contour plots, this is passed to clabel. Otherwise, this is passed to text.
formatter, fmt (formatter-spec, optional) – The Formatter used to format number labels. Passed to the Formatter constructor.
formatter_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Formatter class.
precision (int, optional) – The maximum number of decimal places for number labels generated with the default formatter Simpleformatter.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to matplotlib.axes.Axes.contour.

contourf(**kwargs)[source]

Plot filled contours.

Parameters:

*args (z or x, y, z) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only z coordinates are passed, try to infer the x and y coordinates from the DataFrame indices and columns or the DataArray coordinates. Otherwise, the y coordinates are np.arange(0, y.shape[0]) and the x coordinates are np.arange(0, y.shape[1]).
- For pcolor and pcolormesh, calculate coordinate edges using edges or :func:`~ultraplot.utils.edges2d` if centers were provided. For all other methods, calculate coordinate centers if edges were provided.
- If the x or y coordinates are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. If the z coordinates are pint.Quantity, pass the magnitude to the plotting command. A pint.Quantity embedded in an xarray.DataArray is also supported.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.
transpose (bool, default: False) – Whether to transpose the input data. This should be used when passing datasets with column-major dimension order (x, y). Otherwise row-major dimension order (y, x) is expected.
order ({'C', 'F'}, default: 'C') – Alternative to transpose. 'C' corresponds to the default C-cyle row-major ordering (equivalent to transpose=False). 'F' corresponds to Fortran-style column-major ordering (equivalent to transpose=True).
globe (bool, default: False) – For ultraplot.axes.GeoAxes only. Whether to enforce global coverage. When set to True this does the following:
1. Interpolates input data to the North and South poles by setting the data values at the poles to the mean from latitudes nearest each pole.
2. Makes meridional coverage “circular”, i.e. the last longitude coordinate equals the first longitude coordinate plus 360°.
3. When basemap is the backend, cycles 1D longitude vectors to fit within the map edges. For example, if the central longitude is 90°, the data is shifted so that it spans -90° to 270°.

Other Parameters:

cmap (colormap-spec, default: rc['cmap.sequential'] = 'Fire' or rc['cmap.diverging'] = 'BuRd') – The colormap specifer, passed to the Colormap constructor function. If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then rc['cmap.diverging'] is used. Otherwise rc['cmap.sequential'] is used.
cmap_kw (dict-like, optional) – Passed to Colormap.
c, color, colors (color-spec or sequence of color-spec, optional) – The color(s) used to create a DiscreteColormap. If not passed, cmap is used.
norm (norm-spec, default: Normalize or DivergingNorm) – The data value normalizer, passed to the Norm constructor function. If discrete is True then 1) this affects the default level-generation algorithm (e.g. norm='log' builds levels in log-space) and 2) this is passed to DiscreteNorm to scale the colors before they are discretized (if norm is not already a DiscreteNorm). If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then DivergingNorm is used. Otherwise Normalize is used.
norm_kw (dict-like, optional) – Passed to Norm.
extend ({'neither', 'both', 'min', 'max'}, default: 'neither') – Direction for drawing colorbar “extensions” indicating out-of-bounds data on the end of the colorbar.
discrete (bool, default: rc['cmap.discrete'] = None) – If False, then DiscreteNorm is not applied to the colormap. Instead, for non-contour plots, the number of levels will be roughly controlled by rc['cmap.lut']. This has a similar effect to using levels=large_number but it may improve rendering speed. Default is True only for contouring commands like contourf and pseudocolor commands like pcolor.
sequential, diverging, cyclic, qualitative (bool, default: None) – Boolean arguments used if cmap is not passed. Set these to True to use the default rc['cmap.sequential'], rc['cmap.diverging'], rc['cmap.cyclic'], and rc['cmap.qualitative'] colormaps. The diverging option also applies DivergingNorm as the default continuous normalizer.
vmin, vmax (float, optional) – The minimum and maximum color scale values used with the norm normalizer. If discrete is False these are the absolute limits, and if discrete is True these are the approximate limits used to automatically determine levels or values lists at “nice” intervals. If levels or values were already passed as lists, these are ignored, and vmin and vmax are set to the minimum and maximum of the lists. If robust was passed, the default vmin and vmax are some percentile range of the data values. Otherwise, the default vmin and vmax are the minimum and maximum of the data values.
N – Shorthand for levels.
levels (int or sequence of float, default: rc['cmap.levels'] = 11) – The number of level edges or a sequence of level edges. If the former, locator is used to generate this many level edges at “nice” intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing levels fail with contour plots).
values (int or sequence of float, default: None) – The number of level centers or a sequence of level centers. If the former, locator is used to generate this many level centers at “nice” intervals. If the latter, levels are inferred using edges. This will override any levels input.
center_levels (bool, default False) – If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented.
robust (bool, float, or 2-tuple, default: rc['cmap.robust'] = False) – If True and vmin or vmax were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, 90 corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers.
inbounds (bool, default: rc['cmap.inbounds'] = True) – If True and vmin or vmax were not provided, when axis limits have been explicitly restricted with set_xlim() or set_ylim(), out-of-bounds data is ignored. See also rc['cmap.inbounds'] and rc['axes.inbounds'].
locator (locator-spec, default: matplotlib.ticker.MaxNLocator) – The locator used to determine level locations if levels or values were not already passed as lists. Passed to the Locator constructor. Default is MaxNLocator with levels integer levels.
locator_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Locator class.
symmetric (bool, default: False) – If True, the normalization range or discrete colormap levels are symmetric about zero.
positive (bool, default: False) – If True, the normalization range or discrete colormap levels are positive with a minimum at zero.
negative (bool, default: False) – If True, the normaliation range or discrete colormap levels are negative with a minimum at zero.
nozero (bool, default: False) – If True, 0 is removed from the level list. This is mainly useful for single-color contour plots.
lw, linewidth, linewidths (unit-spec, default: 0.3 or rc['lines.linewidth'] = 1.5) – The width of the line contours. Default is 0.3 when adding to filled contours or rc['lines.linewidth'] = 1.5 otherwise. If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: '-' or rc['contour.negative_linestyle'] = 'dashed') – The style of the line contours. Default is '-' for positive contours and rc['contour.negative_linestyle'] for negative contours.
ec, edgecolor, edgecolors (color-spec, default: 'k' or inferred) – The color of the line contours. Default is 'k' when adding to filled contours or inferred from color or cmap otherwise.
a, alpha, alpha (float, optional) – The opacity of the contours. Inferred from edgecolor by default.edgefix : bool or float, default: rc.edgefix = True Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). See this github repo for a demonstration of the problem. If True, a small default linewidth of 0.3 is used to cover up the white lines. If float (e.g. edgefix=0.5), this specific linewidth is used to cover up the white lines. This feature is automatically disabled when the patches have transparency.
label (str, optional) – The legend label to be used for this object. In the case of contours, this is paired with the the central artist in the artist list returned by matplotlib.contour.ContourSet.legend_elements.
labels (bool, optional) – Whether to apply labels to contours and grid boxes. The text will be white when the luminance of the underlying filled contour or grid box is less than 50 and black otherwise.
labels_kw (dict-like, optional) – Ignored if labels is False. Extra keyword args for the labels. For contour plots, this is passed to clabel. Otherwise, this is passed to text.
formatter, fmt (formatter-spec, optional) – The Formatter used to format number labels. Passed to the Formatter constructor.
formatter_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Formatter class.
precision (int, optional) – The maximum number of decimal places for number labels generated with the default formatter Simpleformatter.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to matplotlib.axes.Axes.contourf.

Draws curved vector field arrows (streamlines with arrows) for 2D vector fields.

Parameters:

x, y (1D or 2D arrays) – Grid coordinates.
u, v (2D arrays) – Vector components.
color (color or 2D array, optional) – Streamline color.
density (float or (float, float), optional) – Controls the closeness of streamlines.
grains (int or (int, int), optional) – Number of seed points in x and y.
linewidth (float or 2D array, optional) – Width of streamlines.
cmap, norm (optional) – Colormap and normalization for array colors.
arrowsize (float, optional) – Arrow size scaling.
arrowstyle (str, optional) – Arrow style specification.
transform (optional) – Matplotlib transform.
zorder (float, optional) – Z-order for lines/arrows.
start_points ((N, 2) array, optional) – Starting points for streamlines.

Returns:

CurvedQuiverSet – Container with attributes: - lines: LineCollection of streamlines - arrows: PatchCollection of arrows

Notes

The implementation of this function is based on the dfm_tools repository. Original file: https://github.com/Deltares/dfm_tools/blob/829e76f48ebc42460aae118cc190147a595a5f26/dfm_tools/modplot.py

fill_between(**kwargs)[source]

Plot individual, grouped, or overlaid shading patches.

Parameters:

*args (y2 or x, y2, or x, y1, y2) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only y coordinates are passed, try to infer the x coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the x coordinates are np.arange(0, y2.shape[0]).
- If only x and y2 coordinates are passed, set the y1 coordinates to zero. This draws elements originating from the zero line.
- If both y1 and y2 are provided, draw elements between these points. If either are 2D, draw elements by iterating over each column.
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
stack, stacked (bool, default: False) – Whether to “stack” area patches from successive columns of y data or plot area patches on top of each other.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

where (ndarray, optional) – A boolean mask for the points that should be shaded. See this matplotlib example.
cycle (cycle-spec, optional) – The cycle specifer, passed to the Cycle constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use cycle=False, cycle='none', or cycle=() (analogous to disabling ticks with e.g. xformatter='none'). To restore the default property cycler, use cycle=True.
cycle_kw (dict-like, optional) – Passed to Cycle.
lw, linewidth, linewidths (unit-spec, default: rc['patch.linewidth'] = 0.6) – The edge width of the patch(es). If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: '-') – The edge style of the patch(es).
ec, edgecolor, edgecolors (color-spec, default: 'none') – The edge color of the patch(es).
fc, facecolor, facecolors, fillcolor, fillcolors (color-spec, optional) – The face color of the patch(es). The property cycle is used by default.
a, alpha, alphas (float, optional) – The opacity of the patch(es). Inferred from facecolor and edgecolor by default.
negpos (bool, default: False) – Whether to shade patches where y2 >= y1 with poscolor and where y2 < y1 with negcolor. If True this function will return a length-2 silent list of handles.
negcolor, poscolor (color-spec, default: rc.negcolor = 'blue7', rc.poscolor = 'red7') – Colors to use for the negative and positive patches. Ignored if negpos is False.
edgefix (bool or float, default: rc.edgefix = True) – Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). See this github repo for a demonstration of the problem. If True, a small default linewidth of 0.3 is used to cover up the white lines. If float (e.g. edgefix=0.5), this specific linewidth is used to cover up the white lines. This feature is automatically disabled when the patches have transparency.
inbounds (bool, default: rc['axes.inbounds'] = True) – Whether to restrict the default y (x) axis limits to account for only in-bounds data when the x (y) axis limits have been locked. See also rc['axes.inbounds'] and rc['cmap.inbounds'].
label, value (float or str, optional) – The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally used with 1D positional arguments.
labels, values (sequence of float or sequence of str, optional) – The legend labels or colorbar coordinates used for each plotted element. Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to fill_between.

fill_betweenx(**kwargs)[source]

Plot individual, grouped, or overlaid shading patches.

Parameters:

*args (x2 or y, x2, or y, x1, x2) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only x coordinates are passed, try to infer the y coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the y coordinates are np.arange(0, x2.shape[0]).
- If only y and x2 coordinates are passed, set the x1 coordinates to zero. This draws elements originating from the zero line.
- If both x1 and x2 are provided, draw elements between these points. If either are 2D, draw elements by iterating over each column.
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
stack, stacked (bool, default: False) – Whether to “stack” area patches from successive columns of x data or plot area patches on top of each other.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

where (ndarray, optional) – A boolean mask for the points that should be shaded. See this matplotlib example.
cycle (cycle-spec, optional) – The cycle specifer, passed to the Cycle constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use cycle=False, cycle='none', or cycle=() (analogous to disabling ticks with e.g. xformatter='none'). To restore the default property cycler, use cycle=True.
cycle_kw (dict-like, optional) – Passed to Cycle.
lw, linewidth, linewidths (unit-spec, default: rc['patch.linewidth'] = 0.6) – The edge width of the patch(es). If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: '-') – The edge style of the patch(es).
ec, edgecolor, edgecolors (color-spec, default: 'none') – The edge color of the patch(es).
fc, facecolor, facecolors, fillcolor, fillcolors (color-spec, optional) – The face color of the patch(es). The property cycle is used by default.
a, alpha, alphas (float, optional) – The opacity of the patch(es). Inferred from facecolor and edgecolor by default.
negpos (bool, default: False) – Whether to shade patches where y2 >= y1 with poscolor and where y2 < y1 with negcolor. If True this function will return a length-2 silent list of handles.
negcolor, poscolor (color-spec, default: rc.negcolor = 'blue7', rc.poscolor = 'red7') – Colors to use for the negative and positive patches. Ignored if negpos is False.
edgefix (bool or float, default: rc.edgefix = True) – Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). See this github repo for a demonstration of the problem. If True, a small default linewidth of 0.3 is used to cover up the white lines. If float (e.g. edgefix=0.5), this specific linewidth is used to cover up the white lines. This feature is automatically disabled when the patches have transparency.
inbounds (bool, default: rc['axes.inbounds'] = True) – Whether to restrict the default y (x) axis limits to account for only in-bounds data when the x (y) axis limits have been locked. See also rc['axes.inbounds'] and rc['cmap.inbounds'].
label, value (float or str, optional) – The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally used with 1D positional arguments.
labels, values (sequence of float or sequence of str, optional) – The legend labels or colorbar coordinates used for each plotted element. Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to fill_betweenx.

Plot a networkx graph with flexible node, edge, and label options.

Parameters:

g (networkx.Graph) – The graph object to be plotted. Can be any subclass of Graph, such as DiGraph or MultiGraph.
layout (callable() or dict, optional) – A layout function or a precomputed dict mapping nodes to 2D positions. If a function is given, it is called as layout(g, **layout_kw) to compute positions. See networkx.drawing.nx_pylab.draw() for more information.
nodes (bool or iterable, default: rc[``”graph.draw_nodes”``]) – Which nodes to draw. If True, all nodes are drawn. If an iterable is provided, only the specified nodes are included. This effectively acts as nodelist in networkx.drawing.nx_pylab.draw_networkx_nodes().
edges (bool or iterable, default: rc[``”graph.draw_edges”``]) – Which edges to draw. If True, all edges are drawn. If an iterable of edge tuples is provided, only those edges are included. This effectively acts as edgelist in networkx.drawing.nx_pylab.draw_networkx_edges().
labels (bool or iterable, default: rc["graph.draw_labels]) – Whether to show node labels. If True, labels are drawn using node names. If an iterable is given, only those nodes are labeled.
layout_kw (dict, default: {}) – Keyword arguments passed to the layout function, if layout is callable, see networkx’s drawing functions for more information.
node_kw (dict, default: {}) – Additional keyword arguments passed to the node drawing function (see networkx.drawing.nx_pylab.draw_networkx_nodes()). These can include size, color, edgecolor, cmap, alpha, etc., depending on the backend used, see networkx.drawing.nx_pylab.draw_networkx_nodes().
edge_kw (dict, default: {}) – Additional keyword arguments passed to the edge drawing function. These can include width, color, style, alpha, arrows, etc (see networkx.drawing.nx_pylab.draw_networkx_edges()).
label_kw (dict, default: {}) – Additional keyword arguments passed to the label drawing function, such as font size, font color, background color, alignment, etc (see networkx.drawing.nx_pylab.draw_networkx_labels()).
rescale (bool, None, default: None.) – When set to none it checks for rc["graph.rescale"] which defaults to True. This performs a rescale such that the node position is within a [0, 1] x [0, 1] box.

Returns:

Nodes, edges, labels output from the networkx drawing functions.

See also

networkx.draw, networkx.draw_networkx, networkx.draw_networkx_nodes, networkx.draw_networkx_edges, networkx.draw_networkx_labels

heatmap(*args, aspect=None, **kwargs)[source]

Plot grid boxes with formatting suitable for heatmaps. Ensures square grid boxes, adds major ticks to the center of each grid box, disables minor ticks and gridlines, and sets rc['cmap.discrete'] to False by default.

Parameters:

*args (z or x, y, z) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only z coordinates are passed, try to infer the x and y coordinates from the DataFrame indices and columns or the DataArray coordinates. Otherwise, the y coordinates are np.arange(0, y.shape[0]) and the x coordinates are np.arange(0, y.shape[1]).
- For pcolor and pcolormesh, calculate coordinate edges using edges or :func:`~ultraplot.utils.edges2d` if centers were provided. For all other methods, calculate coordinate centers if edges were provided.
- If the x or y coordinates are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. If the z coordinates are pint.Quantity, pass the magnitude to the plotting command. A pint.Quantity embedded in an xarray.DataArray is also supported.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.
transpose (bool, default: False) – Whether to transpose the input data. This should be used when passing datasets with column-major dimension order (x, y). Otherwise row-major dimension order (y, x) is expected.
order ({'C', 'F'}, default: 'C') – Alternative to transpose. 'C' corresponds to the default C-cyle row-major ordering (equivalent to transpose=False). 'F' corresponds to Fortran-style column-major ordering (equivalent to transpose=True).
globe (bool, default: False) – For ultraplot.axes.GeoAxes only. Whether to enforce global coverage. When set to True this does the following:
1. Interpolates input data to the North and South poles by setting the data values at the poles to the mean from latitudes nearest each pole.
2. Makes meridional coverage “circular”, i.e. the last longitude coordinate equals the first longitude coordinate plus 360°.
3. When basemap is the backend, cycles 1D longitude vectors to fit within the map edges. For example, if the central longitude is 90°, the data is shifted so that it spans -90° to 270°.
aspect ({'equal', 'auto'} or float, default: rc['image.aspet']) – Modify the axes aspect ratio. The aspect ratio is of particular relevance for heatmaps since it may lead to non-square grid boxes. This parameter is a shortcut for calling set_aspect. The options are as follows:
- Number: The data aspect ratio.
- 'equal': A data aspect ratio of 1.
- 'auto': Allows the data aspect ratio to change depending on the layout. In general this results in non-square grid boxes.

Other Parameters:

cmap (colormap-spec, default: rc['cmap.sequential'] = 'Fire' or rc['cmap.diverging'] = 'BuRd') – The colormap specifer, passed to the Colormap constructor function. If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then rc['cmap.diverging'] is used. Otherwise rc['cmap.sequential'] is used.
cmap_kw (dict-like, optional) – Passed to Colormap.
c, color, colors (color-spec or sequence of color-spec, optional) – The color(s) used to create a DiscreteColormap. If not passed, cmap is used.
norm (norm-spec, default: Normalize or DivergingNorm) – The data value normalizer, passed to the Norm constructor function. If discrete is True then 1) this affects the default level-generation algorithm (e.g. norm='log' builds levels in log-space) and 2) this is passed to DiscreteNorm to scale the colors before they are discretized (if norm is not already a DiscreteNorm). If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then DivergingNorm is used. Otherwise Normalize is used.
norm_kw (dict-like, optional) – Passed to Norm.
extend ({'neither', 'both', 'min', 'max'}, default: 'neither') – Direction for drawing colorbar “extensions” indicating out-of-bounds data on the end of the colorbar.
discrete (bool, default: rc['cmap.discrete'] = None) – If False, then DiscreteNorm is not applied to the colormap. Instead, for non-contour plots, the number of levels will be roughly controlled by rc['cmap.lut']. This has a similar effect to using levels=large_number but it may improve rendering speed. Default is True only for contouring commands like contourf and pseudocolor commands like pcolor.
sequential, diverging, cyclic, qualitative (bool, default: None) – Boolean arguments used if cmap is not passed. Set these to True to use the default rc['cmap.sequential'], rc['cmap.diverging'], rc['cmap.cyclic'], and rc['cmap.qualitative'] colormaps. The diverging option also applies DivergingNorm as the default continuous normalizer.
vmin, vmax (float, optional) – The minimum and maximum color scale values used with the norm normalizer. If discrete is False these are the absolute limits, and if discrete is True these are the approximate limits used to automatically determine levels or values lists at “nice” intervals. If levels or values were already passed as lists, these are ignored, and vmin and vmax are set to the minimum and maximum of the lists. If robust was passed, the default vmin and vmax are some percentile range of the data values. Otherwise, the default vmin and vmax are the minimum and maximum of the data values.
N – Shorthand for levels.
levels (int or sequence of float, default: rc['cmap.levels'] = 11) – The number of level edges or a sequence of level edges. If the former, locator is used to generate this many level edges at “nice” intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing levels fail with contour plots).
values (int or sequence of float, default: None) – The number of level centers or a sequence of level centers. If the former, locator is used to generate this many level centers at “nice” intervals. If the latter, levels are inferred using edges. This will override any levels input.
center_levels (bool, default False) – If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented.
robust (bool, float, or 2-tuple, default: rc['cmap.robust'] = False) – If True and vmin or vmax were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, 90 corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers.
inbounds (bool, default: rc['cmap.inbounds'] = True) – If True and vmin or vmax were not provided, when axis limits have been explicitly restricted with set_xlim() or set_ylim(), out-of-bounds data is ignored. See also rc['cmap.inbounds'] and rc['axes.inbounds'].
locator (locator-spec, default: matplotlib.ticker.MaxNLocator) – The locator used to determine level locations if levels or values were not already passed as lists. Passed to the Locator constructor. Default is MaxNLocator with levels integer levels.
locator_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Locator class.
symmetric (bool, default: False) – If True, the normalization range or discrete colormap levels are symmetric about zero.
positive (bool, default: False) – If True, the normalization range or discrete colormap levels are positive with a minimum at zero.
negative (bool, default: False) – If True, the normaliation range or discrete colormap levels are negative with a minimum at zero.
nozero (bool, default: False) – If True, 0 is removed from the level list. This is mainly useful for single-color contour plots.
lw, linewidth, linewidths (unit-spec, default: 0.3) – The width of lines between grid boxes. If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: '-') – The style of lines between grid boxes.
ec, edgecolor, edgecolors (color-spec, default: 'k') – The color of lines between grid boxes.
a, alpha, alphas (float, optional) – The opacity of the grid boxes. Inferred from cmap by default.
edgefix (bool or float, default: rc.edgefix = True) – Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). See this github repo for a demonstration of the problem. If True, a small default linewidth of 0.3 is used to cover up the white lines. If float (e.g. edgefix=0.5), this specific linewidth is used to cover up the white lines. This feature is automatically disabled when the patches have transparency.
label (str, optional) – The legend label to be used for this object. In the case of contours, this is paired with the the central artist in the artist list returned by matplotlib.contour.ContourSet.legend_elements.
labels (bool, optional) – Whether to apply labels to contours and grid boxes. The text will be white when the luminance of the underlying filled contour or grid box is less than 50 and black otherwise.
labels_kw (dict-like, optional) – Ignored if labels is False. Extra keyword args for the labels. For contour plots, this is passed to clabel. Otherwise, this is passed to text.
formatter, fmt (formatter-spec, optional) – The Formatter used to format number labels. Passed to the Formatter constructor.
formatter_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Formatter class.
precision (int, optional) – The maximum number of decimal places for number labels generated with the default formatter Simpleformatter.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to matplotlib.axes.Axes.pcolormesh.

hexbin(**kwargs)[source]

Plot a 2D hexagonally binned histogram. standard 2D histogram.

Parameters:

*args (y or x, y) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only y coordinates are passed, try to infer the x coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the x coordinates are np.arange(0, y.shape[0]).
- If the y coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with boxplot, violinplot, or when using means=True or medians=True).
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
weights (array-like, optional) – The weights associated with each point. If string this can be retrieved from data (see below).
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

cmap (colormap-spec, default: rc['cmap.sequential'] = 'Fire' or rc['cmap.diverging'] = 'BuRd') – The colormap specifer, passed to the Colormap constructor function. If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then rc['cmap.diverging'] is used. Otherwise rc['cmap.sequential'] is used.
cmap_kw (dict-like, optional) – Passed to Colormap.
c, color, colors (color-spec or sequence of color-spec, optional) – The color(s) used to create a DiscreteColormap. If not passed, cmap is used.
norm (norm-spec, default: Normalize or DivergingNorm) – The data value normalizer, passed to the Norm constructor function. If discrete is True then 1) this affects the default level-generation algorithm (e.g. norm='log' builds levels in log-space) and 2) this is passed to DiscreteNorm to scale the colors before they are discretized (if norm is not already a DiscreteNorm). If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then DivergingNorm is used. Otherwise Normalize is used.
norm_kw (dict-like, optional) – Passed to Norm.
extend ({'neither', 'both', 'min', 'max'}, default: 'neither') – Direction for drawing colorbar “extensions” indicating out-of-bounds data on the end of the colorbar.
discrete (bool, default: rc['cmap.discrete'] = None) – If False, then DiscreteNorm is not applied to the colormap. Instead, for non-contour plots, the number of levels will be roughly controlled by rc['cmap.lut']. This has a similar effect to using levels=large_number but it may improve rendering speed. Default is True only for contouring commands like contourf and pseudocolor commands like pcolor.
sequential, diverging, cyclic, qualitative (bool, default: None) – Boolean arguments used if cmap is not passed. Set these to True to use the default rc['cmap.sequential'], rc['cmap.diverging'], rc['cmap.cyclic'], and rc['cmap.qualitative'] colormaps. The diverging option also applies DivergingNorm as the default continuous normalizer.
vmin, vmax (float, optional) – The minimum and maximum color scale values used with the norm normalizer. If discrete is False these are the absolute limits, and if discrete is True these are the approximate limits used to automatically determine levels or values lists at “nice” intervals. If levels or values were already passed as lists, these are ignored, and vmin and vmax are set to the minimum and maximum of the lists. If robust was passed, the default vmin and vmax are some percentile range of the data values. Otherwise, the default vmin and vmax are the minimum and maximum of the data values.
N – Shorthand for levels.
levels (int or sequence of float, default: rc['cmap.levels'] = 11) – The number of level edges or a sequence of level edges. If the former, locator is used to generate this many level edges at “nice” intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing levels fail with contour plots).
values (int or sequence of float, default: None) – The number of level centers or a sequence of level centers. If the former, locator is used to generate this many level centers at “nice” intervals. If the latter, levels are inferred using edges. This will override any levels input.
center_levels (bool, default False) – If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented.
robust (bool, float, or 2-tuple, default: rc['cmap.robust'] = False) – If True and vmin or vmax were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, 90 corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers.
inbounds (bool, default: rc['cmap.inbounds'] = True) – If True and vmin or vmax were not provided, when axis limits have been explicitly restricted with set_xlim() or set_ylim(), out-of-bounds data is ignored. See also rc['cmap.inbounds'] and rc['axes.inbounds'].
locator (locator-spec, default: matplotlib.ticker.MaxNLocator) – The locator used to determine level locations if levels or values were not already passed as lists. Passed to the Locator constructor. Default is MaxNLocator with levels integer levels.
locator_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Locator class.
symmetric (bool, default: False) – If True, the normalization range or discrete colormap levels are symmetric about zero.
positive (bool, default: False) – If True, the normalization range or discrete colormap levels are positive with a minimum at zero.
negative (bool, default: False) – If True, the normaliation range or discrete colormap levels are negative with a minimum at zero.
nozero (bool, default: False) – If True, 0 is removed from the level list. This is mainly useful for single-color contour plots.
label (str, optional) – The legend label to be used for this object. In the case of contours, this is paired with the the central artist in the artist list returned by matplotlib.contour.ContourSet.legend_elements.
labels (bool, optional) – Whether to apply labels to contours and grid boxes. The text will be white when the luminance of the underlying filled contour or grid box is less than 50 and black otherwise.
labels_kw (dict-like, optional) – Ignored if labels is False. Extra keyword args for the labels. For contour plots, this is passed to clabel. Otherwise, this is passed to text.
formatter, fmt (formatter-spec, optional) – The Formatter used to format number labels. Passed to the Formatter constructor.
formatter_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Formatter class.
precision (int, optional) – The maximum number of decimal places for number labels generated with the default formatter Simpleformatter.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to hexbin.

hist(**kwargs)[source]

Plot vertical histograms.

Parameters:

*args (x or y, x) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only x coordinates are passed, try to infer the y coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the y coordinates are np.arange(0, x.shape[0]).
- If the x coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with boxplot, violinplot, or when using means=True or medians=True).
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
bins (int or sequence of float, optional) – The bin count or exact bin edges.
weights (array-like, optional) – The weights associated with each point. If string this can be retrieved from data (see below).
histtype ({'bar', 'barstacked', 'step', 'stepfilled'}, optional) – The histogram type. See matplotlib.axes.Axes.hist for details.
width, rwidth (float, default: 0.8 or 1) – The bar width(s) for bar-type histograms relative to the bin size. Default is 0.8 for multiple columns of unstacked data and 1 otherwise.
stack, stacked (bool, optional) – Whether to “stack” successive columns of x data for bar-type histograms or show side-by-side in groups. Setting this to False is equivalent to histtype='bar' and to True is equivalent to histtype='barstacked'.
fill, filled (bool, optional) – Whether to “fill” step-type histograms or just plot the edges. Setting this to False is equivalent to histtype='step' and to True is equivalent to histtype='stepfilled'.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

cycle (cycle-spec, optional) – The cycle specifer, passed to the Cycle constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use cycle=False, cycle='none', or cycle=() (analogous to disabling ticks with e.g. xformatter='none'). To restore the default property cycler, use cycle=True.
cycle_kw (dict-like, optional) – Passed to Cycle.
lw, linewidth, linewidths (unit-spec, default: rc['patch.linewidth'] = 0.6) – The edge width of the patch(es). If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: '-') – The edge style of the patch(es).
ec, edgecolor, edgecolors (color-spec, default: 'none') – The edge color of the patch(es).
fc, facecolor, facecolors, fillcolor, fillcolors (color-spec, optional) – The face color of the patch(es). The property cycle is used by default.
a, alpha, alphas (float, optional) – The opacity of the patch(es). Inferred from facecolor and edgecolor by default.
edgefix (bool or float, default: rc.edgefix = True) – Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). See this github repo for a demonstration of the problem. If True, a small default linewidth of 0.3 is used to cover up the white lines. If float (e.g. edgefix=0.5), this specific linewidth is used to cover up the white lines. This feature is automatically disabled when the patches have transparency.
label, value (float or str, optional) – The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally used with 1D positional arguments.
labels, values (sequence of float or sequence of str, optional) – The legend labels or colorbar coordinates used for each plotted element. Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to hist.

hist2d(**kwargs)[source]

Plot a standard 2D histogram. standard 2D histogram.

Parameters:

*args (y or x, y) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only y coordinates are passed, try to infer the x coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the x coordinates are np.arange(0, y.shape[0]).
- If the y coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with boxplot, violinplot, or when using means=True or medians=True).
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
bins (int or 2-tuple of int, or array-like or 2-tuple of array-like, optional) – The bin count or exact bin edges for each dimension or both dimensions.
weights (array-like, optional) – The weights associated with each point. If string this can be retrieved from data (see below).
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

cmap (colormap-spec, default: rc['cmap.sequential'] = 'Fire' or rc['cmap.diverging'] = 'BuRd') – The colormap specifer, passed to the Colormap constructor function. If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then rc['cmap.diverging'] is used. Otherwise rc['cmap.sequential'] is used.
cmap_kw (dict-like, optional) – Passed to Colormap.
c, color, colors (color-spec or sequence of color-spec, optional) – The color(s) used to create a DiscreteColormap. If not passed, cmap is used.
norm (norm-spec, default: Normalize or DivergingNorm) – The data value normalizer, passed to the Norm constructor function. If discrete is True then 1) this affects the default level-generation algorithm (e.g. norm='log' builds levels in log-space) and 2) this is passed to DiscreteNorm to scale the colors before they are discretized (if norm is not already a DiscreteNorm). If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then DivergingNorm is used. Otherwise Normalize is used.
norm_kw (dict-like, optional) – Passed to Norm.
extend ({'neither', 'both', 'min', 'max'}, default: 'neither') – Direction for drawing colorbar “extensions” indicating out-of-bounds data on the end of the colorbar.
discrete (bool, default: rc['cmap.discrete'] = None) – If False, then DiscreteNorm is not applied to the colormap. Instead, for non-contour plots, the number of levels will be roughly controlled by rc['cmap.lut']. This has a similar effect to using levels=large_number but it may improve rendering speed. Default is True only for contouring commands like contourf and pseudocolor commands like pcolor.
sequential, diverging, cyclic, qualitative (bool, default: None) – Boolean arguments used if cmap is not passed. Set these to True to use the default rc['cmap.sequential'], rc['cmap.diverging'], rc['cmap.cyclic'], and rc['cmap.qualitative'] colormaps. The diverging option also applies DivergingNorm as the default continuous normalizer.
vmin, vmax (float, optional) – The minimum and maximum color scale values used with the norm normalizer. If discrete is False these are the absolute limits, and if discrete is True these are the approximate limits used to automatically determine levels or values lists at “nice” intervals. If levels or values were already passed as lists, these are ignored, and vmin and vmax are set to the minimum and maximum of the lists. If robust was passed, the default vmin and vmax are some percentile range of the data values. Otherwise, the default vmin and vmax are the minimum and maximum of the data values.
N – Shorthand for levels.
levels (int or sequence of float, default: rc['cmap.levels'] = 11) – The number of level edges or a sequence of level edges. If the former, locator is used to generate this many level edges at “nice” intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing levels fail with contour plots).
values (int or sequence of float, default: None) – The number of level centers or a sequence of level centers. If the former, locator is used to generate this many level centers at “nice” intervals. If the latter, levels are inferred using edges. This will override any levels input.
center_levels (bool, default False) – If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented.
robust (bool, float, or 2-tuple, default: rc['cmap.robust'] = False) – If True and vmin or vmax were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, 90 corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers.
inbounds (bool, default: rc['cmap.inbounds'] = True) – If True and vmin or vmax were not provided, when axis limits have been explicitly restricted with set_xlim() or set_ylim(), out-of-bounds data is ignored. See also rc['cmap.inbounds'] and rc['axes.inbounds'].
locator (locator-spec, default: matplotlib.ticker.MaxNLocator) – The locator used to determine level locations if levels or values were not already passed as lists. Passed to the Locator constructor. Default is MaxNLocator with levels integer levels.
locator_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Locator class.
symmetric (bool, default: False) – If True, the normalization range or discrete colormap levels are symmetric about zero.
positive (bool, default: False) – If True, the normalization range or discrete colormap levels are positive with a minimum at zero.
negative (bool, default: False) – If True, the normaliation range or discrete colormap levels are negative with a minimum at zero.
nozero (bool, default: False) – If True, 0 is removed from the level list. This is mainly useful for single-color contour plots.
label (str, optional) – The legend label to be used for this object. In the case of contours, this is paired with the the central artist in the artist list returned by matplotlib.contour.ContourSet.legend_elements.
labels (bool, optional) – Whether to apply labels to contours and grid boxes. The text will be white when the luminance of the underlying filled contour or grid box is less than 50 and black otherwise.
labels_kw (dict-like, optional) – Ignored if labels is False. Extra keyword args for the labels. For contour plots, this is passed to clabel. Otherwise, this is passed to text.
formatter, fmt (formatter-spec, optional) – The Formatter used to format number labels. Passed to the Formatter constructor.
formatter_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Formatter class.
precision (int, optional) – The maximum number of decimal places for number labels generated with the default formatter Simpleformatter.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to hist2d.

histh(*args, **kwargs)[source]

Plot horizontal histograms.

Parameters:

*args (x or y, x) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only x coordinates are passed, try to infer the y coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the y coordinates are np.arange(0, x.shape[0]).
- If the x coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with boxplot, violinplot, or when using means=True or medians=True).
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
bins (int or sequence of float, optional) – The bin count or exact bin edges.
weights (array-like, optional) – The weights associated with each point. If string this can be retrieved from data (see below).
histtype ({'bar', 'barstacked', 'step', 'stepfilled'}, optional) – The histogram type. See matplotlib.axes.Axes.hist for details.
width, rwidth (float, default: 0.8 or 1) – The bar width(s) for bar-type histograms relative to the bin size. Default is 0.8 for multiple columns of unstacked data and 1 otherwise.
stack, stacked (bool, optional) – Whether to “stack” successive columns of x data for bar-type histograms or show side-by-side in groups. Setting this to False is equivalent to histtype='bar' and to True is equivalent to histtype='barstacked'.
fill, filled (bool, optional) – Whether to “fill” step-type histograms or just plot the edges. Setting this to False is equivalent to histtype='step' and to True is equivalent to histtype='stepfilled'.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

cycle (cycle-spec, optional) – The cycle specifer, passed to the Cycle constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use cycle=False, cycle='none', or cycle=() (analogous to disabling ticks with e.g. xformatter='none'). To restore the default property cycler, use cycle=True.
cycle_kw (dict-like, optional) – Passed to Cycle.
lw, linewidth, linewidths (unit-spec, default: rc['patch.linewidth'] = 0.6) – The edge width of the patch(es). If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: '-') – The edge style of the patch(es).
ec, edgecolor, edgecolors (color-spec, default: 'none') – The edge color of the patch(es).
fc, facecolor, facecolors, fillcolor, fillcolors (color-spec, optional) – The face color of the patch(es). The property cycle is used by default.
a, alpha, alphas (float, optional) – The opacity of the patch(es). Inferred from facecolor and edgecolor by default.
edgefix (bool or float, default: rc.edgefix = True) – Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). See this github repo for a demonstration of the problem. If True, a small default linewidth of 0.3 is used to cover up the white lines. If float (e.g. edgefix=0.5), this specific linewidth is used to cover up the white lines. This feature is automatically disabled when the patches have transparency.
label, value (float or str, optional) – The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally used with 1D positional arguments.
labels, values (sequence of float or sequence of str, optional) – The legend labels or colorbar coordinates used for each plotted element. Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to hist.

hlines(*args, **kwargs)[source]

Plot horizontal lines.

Parameters:

*args (x2 or y, x2, or y, x1, x2) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only x coordinates are passed, try to infer the y coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the y coordinates are np.arange(0, x2.shape[0]).
- If only y and x2 coordinates are passed, set the x1 coordinates to zero. This draws elements originating from the zero line.
- If both x1 and x2 are provided, draw elements between these points. If either are 2D, draw elements by iterating over each column.
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

stack, stacked (bool, default: False) – Whether to “stack” lines from successive columns of x data or plot lines on top of each other.
cycle (cycle-spec, optional) – The cycle specifer, passed to the Cycle constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use cycle=False, cycle='none', or cycle=() (analogous to disabling ticks with e.g. xformatter='none'). To restore the default property cycler, use cycle=True.
cycle_kw (dict-like, optional) – Passed to Cycle.
lw, linewidth, linewidths (unit-spec, default: rc['lines.linewidth'] = 1.5) – The width of the line(s). If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: rc['lines.linestyle'] = '-') – The style of the line(s).
c, color, colors (color-spec, optional) – The color of the line(s). The property cycle is used by default.
a, alpha, alphas (float, optional) – The opacity of the line(s). Inferred from color by default.
negpos (bool, default: False) – Whether to shade lines where ymax >= ymin with poscolor and where ymax < ymin with negcolor. If True this function will return a length-2 silent list of handles.
negcolor, poscolor (color-spec, default: rc.negcolor = 'blue7', rc.poscolor = 'red7') – Colors to use for the negative and positive lines. Ignored if negpos is False.
inbounds (bool, default: rc['axes.inbounds'] = True) – Whether to restrict the default y (x) axis limits to account for only in-bounds data when the x (y) axis limits have been locked. See also rc['axes.inbounds'] and rc['cmap.inbounds'].
label, value (float or str, optional) – The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally used with 1D positional arguments.
labels, values (sequence of float or sequence of str, optional) – The legend labels or colorbar coordinates used for each plotted element. Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to hlines.

imshow(**kwargs)[source]

Plot an image.

Parameters:

z (array-like) – The data passed as a positional argument or keyword argument.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

cmap (colormap-spec, default: rc['cmap.sequential'] = 'Fire' or rc['cmap.diverging'] = 'BuRd') – The colormap specifer, passed to the Colormap constructor function. If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then rc['cmap.diverging'] is used. Otherwise rc['cmap.sequential'] is used.
cmap_kw (dict-like, optional) – Passed to Colormap.
c, color, colors (color-spec or sequence of color-spec, optional) – The color(s) used to create a DiscreteColormap. If not passed, cmap is used.
norm (norm-spec, default: Normalize or DivergingNorm) – The data value normalizer, passed to the Norm constructor function. If discrete is True then 1) this affects the default level-generation algorithm (e.g. norm='log' builds levels in log-space) and 2) this is passed to DiscreteNorm to scale the colors before they are discretized (if norm is not already a DiscreteNorm). If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then DivergingNorm is used. Otherwise Normalize is used.
norm_kw (dict-like, optional) – Passed to Norm.
extend ({'neither', 'both', 'min', 'max'}, default: 'neither') – Direction for drawing colorbar “extensions” indicating out-of-bounds data on the end of the colorbar.
discrete (bool, default: rc['cmap.discrete'] = None) – If False, then DiscreteNorm is not applied to the colormap. Instead, for non-contour plots, the number of levels will be roughly controlled by rc['cmap.lut']. This has a similar effect to using levels=large_number but it may improve rendering speed. Default is True only for contouring commands like contourf and pseudocolor commands like pcolor.
sequential, diverging, cyclic, qualitative (bool, default: None) – Boolean arguments used if cmap is not passed. Set these to True to use the default rc['cmap.sequential'], rc['cmap.diverging'], rc['cmap.cyclic'], and rc['cmap.qualitative'] colormaps. The diverging option also applies DivergingNorm as the default continuous normalizer.
vmin, vmax (float, optional) – The minimum and maximum color scale values used with the norm normalizer. If discrete is False these are the absolute limits, and if discrete is True these are the approximate limits used to automatically determine levels or values lists at “nice” intervals. If levels or values were already passed as lists, these are ignored, and vmin and vmax are set to the minimum and maximum of the lists. If robust was passed, the default vmin and vmax are some percentile range of the data values. Otherwise, the default vmin and vmax are the minimum and maximum of the data values.
N – Shorthand for levels.
levels (int or sequence of float, default: rc['cmap.levels'] = 11) – The number of level edges or a sequence of level edges. If the former, locator is used to generate this many level edges at “nice” intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing levels fail with contour plots).
values (int or sequence of float, default: None) – The number of level centers or a sequence of level centers. If the former, locator is used to generate this many level centers at “nice” intervals. If the latter, levels are inferred using edges. This will override any levels input.
center_levels (bool, default False) – If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented.
robust (bool, float, or 2-tuple, default: rc['cmap.robust'] = False) – If True and vmin or vmax were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, 90 corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers.
inbounds (bool, default: rc['cmap.inbounds'] = True) – If True and vmin or vmax were not provided, when axis limits have been explicitly restricted with set_xlim() or set_ylim(), out-of-bounds data is ignored. See also rc['cmap.inbounds'] and rc['axes.inbounds'].
locator (locator-spec, default: matplotlib.ticker.MaxNLocator) – The locator used to determine level locations if levels or values were not already passed as lists. Passed to the Locator constructor. Default is MaxNLocator with levels integer levels.
locator_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Locator class.
symmetric (bool, default: False) – If True, the normalization range or discrete colormap levels are symmetric about zero.
positive (bool, default: False) – If True, the normalization range or discrete colormap levels are positive with a minimum at zero.
negative (bool, default: False) – If True, the normaliation range or discrete colormap levels are negative with a minimum at zero.
nozero (bool, default: False) – If True, 0 is removed from the level list. This is mainly useful for single-color contour plots.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to matplotlib.axes.Axes.imshow.

line(*args, **kwargs)[source]

Plot standard lines.

Parameters:

*args (y or x, y) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only y coordinates are passed, try to infer the x coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the x coordinates are np.arange(0, y.shape[0]).
- If the y coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with boxplot, violinplot, or when using means=True or medians=True).
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

cycle (cycle-spec, optional) – The cycle specifer, passed to the Cycle constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use cycle=False, cycle='none', or cycle=() (analogous to disabling ticks with e.g. xformatter='none'). To restore the default property cycler, use cycle=True.
cycle_kw (dict-like, optional) – Passed to Cycle.
lw, linewidth, linewidths (unit-spec, default: rc['lines.linewidth'] = 1.5) – The width of the line(s). If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: rc['lines.linestyle'] = '-') – The style of the line(s).
c, color, colors (color-spec, optional) – The color of the line(s). The property cycle is used by default.
a, alpha, alphas (float, optional) – The opacity of the line(s). Inferred from color by default.
mean, means (bool, default: False) – Whether to plot the means of each column for 2D y coordinates. Means are calculated with numpy.nanmean. If no other arguments are specified, this also sets barstd=True (and boxstd=True for violin plots).
median, medians (bool, default: False) – Whether to plot the medians of each column for 2D y coordinates. Medians are calculated with numpy.nanmedian. If no other arguments arguments are specified, this also sets barstd=True (and boxstd=True for violin plots).
bars (bool, default: None) – Shorthand for barstd, barstds.
barstd, barstds (bool, float, or 2-tuple of float, optional) – Valid only if mean or median is True. Standard deviation multiples for thin error bars with optional whiskers (i.e., caps). If scalar, then +/- that multiple is used. If True, the default standard deviation range of +/-3 is used.
barpctile, barpctiles (bool, float, or 2-tuple of float, optional) – Valid only if mean or median is True. As with barstd, but instead using percentiles for the error bars. If scalar, that percentile range is used (e.g., 90 shows the 5th to 95th percentiles). If True, the default percentile range of 0 to 100 is used.
bardata (array-like, optional) – Valid only if mean and median are False. If shape is 2 x N, these are the lower and upper bounds for the thin error bars. If shape is N, these are the absolute, symmetric deviations from the central points.
boxes (bool, default: None) – Shorthand for boxstd, boxstds.
boxstd, boxstds, boxpctile, boxpctiles, boxdata (optional) – As with barstd, barpctile, and bardata, but for thicker error bars representing a smaller interval than the thin error bars. If boxstds is True, the default standard deviation range of +/-1 is used. If boxpctiles is True, the default percentile range of 25 to 75 is used (i.e., the interquartile range). When “boxes” and “bars” are combined, this has the effect of drawing miniature box-and-whisker plots.
capsize (float, default: rc['errorbar.capsize'] = 3.0) – The cap size for thin error bars in points.
barz, barzorder, boxz, boxzorder (float, default: 2.5) – The “zorder” for the thin and thick error bars.
barc, barcolor, boxc, boxcolor (color-spec, default: rc['boxplot.whiskerprops.color'] = 'black') – Colors for the thin and thick error bars.
barlw, barlinewidth, boxlw, boxlinewidth (float, default: rc['boxplot.whiskerprops.linewidth'] = 1.0) – Line widths for the thin and thick error bars, in points. The default for boxes is 4 times rc['boxplot.whiskerprops.linewidth'].
boxm, boxmarker (bool or marker-spec, default: 'o') – Whether to draw a small marker in the middle of the box denoting the mean or median position. Ignored if boxes is False.
boxms, boxmarkersize (size-spec, default: (2 * boxlinewidth) ** 2) – The marker size for the boxmarker marker in points ** 2.
boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor (color-spec, default: 'w') – Color, face color, and edge color for the boxmarker marker.
shade (bool, default: None) – Shorthand for shadestd.
shadestd, shadestds, shadepctile, shadepctiles, shadedata (optional) – As with barstd, barpctile, and bardata, but using shading to indicate the error range. If shadestds is True, the default standard deviation range of +/-2 is used. If shadepctiles is True, the default percentile range of 10 to 90 is used.
fade (bool, default: None) – Shorthand for fadestd.
fadestd, fadestds, fadepctile, fadepctiles, fadedata (optional) – As with shadestd, shadepctile, and shadedata, but for an additional, more faded, secondary shaded region. If fadestds is True, the default standard deviation range of +/-3 is used. If fadepctiles is True, the default percentile range of 0 to 100 is used.
shadec, shadecolor, fadec, fadecolor (color-spec, default: None) – Colors for the different shaded regions. The parent artist color is used by default.
shadez, shadezorder, fadez, fadezorder (float, default: 1.5) – The “zorder” for the different shaded regions.
shadea, shadealpha, fadea, fadealpha (float, default: 0.4, 0.2) – The opacity for the different shaded regions.
shadelw, shadelinewidth, fadelw, fadelinewidth (float, default: rc['patch.linewidth'] = 0.6.) – The edge line width for the shading patches.
shdeec, shadeedgecolor, fadeec, fadeedgecolor (float, default: 'none') – The edge color for the shading patches.
shadelabel, fadelabel (bool or str, optional) – Labels for the shaded regions to be used as separate legend entries. To toggle labels “on” and apply a default label, use e.g. shadelabel=True. To apply a custom label, use e.g. shadelabel='label'. Otherwise, the shading is drawn underneath the line and/or marker in the legend entry.
inbounds (bool, default: rc['axes.inbounds'] = True) – Whether to restrict the default y (x) axis limits to account for only in-bounds data when the x (y) axis limits have been locked. See also rc['axes.inbounds'] and rc['cmap.inbounds'].
label, value (float or str, optional) – The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally used with 1D positional arguments.
labels, values (sequence of float or sequence of str, optional) – The legend labels or colorbar coordinates used for each plotted element. Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to plot().

linex(*args, **kwargs)[source]

Plot standard lines.

Parameters:

*args (x or y, x) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only x coordinates are passed, try to infer the y coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the y coordinates are np.arange(0, x.shape[0]).
- If the x coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with boxplot, violinplot, or when using means=True or medians=True).
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

cycle (cycle-spec, optional) – The cycle specifer, passed to the Cycle constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use cycle=False, cycle='none', or cycle=() (analogous to disabling ticks with e.g. xformatter='none'). To restore the default property cycler, use cycle=True.
cycle_kw (dict-like, optional) – Passed to Cycle.
lw, linewidth, linewidths (unit-spec, default: rc['lines.linewidth'] = 1.5) – The width of the line(s). If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: rc['lines.linestyle'] = '-') – The style of the line(s).
c, color, colors (color-spec, optional) – The color of the line(s). The property cycle is used by default.
a, alpha, alphas (float, optional) – The opacity of the line(s). Inferred from color by default.
mean, means (bool, default: False) – Whether to plot the means of each column for 2D x coordinates. Means are calculated with numpy.nanmean. If no other arguments are specified, this also sets barstd=True (and boxstd=True for violin plots).
median, medians (bool, default: False) – Whether to plot the medians of each column for 2D x coordinates. Medians are calculated with numpy.nanmedian. If no other arguments arguments are specified, this also sets barstd=True (and boxstd=True for violin plots).
bars (bool, default: None) – Shorthand for barstd, barstds.
barstd, barstds (bool, float, or 2-tuple of float, optional) – Valid only if mean or median is True. Standard deviation multiples for thin error bars with optional whiskers (i.e., caps). If scalar, then +/- that multiple is used. If True, the default standard deviation range of +/-3 is used.
barpctile, barpctiles (bool, float, or 2-tuple of float, optional) – Valid only if mean or median is True. As with barstd, but instead using percentiles for the error bars. If scalar, that percentile range is used (e.g., 90 shows the 5th to 95th percentiles). If True, the default percentile range of 0 to 100 is used.
bardata (array-like, optional) – Valid only if mean and median are False. If shape is 2 x N, these are the lower and upper bounds for the thin error bars. If shape is N, these are the absolute, symmetric deviations from the central points.
boxes (bool, default: None) – Shorthand for boxstd, boxstds.
boxstd, boxstds, boxpctile, boxpctiles, boxdata (optional) – As with barstd, barpctile, and bardata, but for thicker error bars representing a smaller interval than the thin error bars. If boxstds is True, the default standard deviation range of +/-1 is used. If boxpctiles is True, the default percentile range of 25 to 75 is used (i.e., the interquartile range). When “boxes” and “bars” are combined, this has the effect of drawing miniature box-and-whisker plots.
capsize (float, default: rc['errorbar.capsize'] = 3.0) – The cap size for thin error bars in points.
barz, barzorder, boxz, boxzorder (float, default: 2.5) – The “zorder” for the thin and thick error bars.
barc, barcolor, boxc, boxcolor (color-spec, default: rc['boxplot.whiskerprops.color'] = 'black') – Colors for the thin and thick error bars.
barlw, barlinewidth, boxlw, boxlinewidth (float, default: rc['boxplot.whiskerprops.linewidth'] = 1.0) – Line widths for the thin and thick error bars, in points. The default for boxes is 4 times rc['boxplot.whiskerprops.linewidth'].
boxm, boxmarker (bool or marker-spec, default: 'o') – Whether to draw a small marker in the middle of the box denoting the mean or median position. Ignored if boxes is False.
boxms, boxmarkersize (size-spec, default: (2 * boxlinewidth) ** 2) – The marker size for the boxmarker marker in points ** 2.
boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor (color-spec, default: 'w') – Color, face color, and edge color for the boxmarker marker.
shade (bool, default: None) – Shorthand for shadestd.
shadestd, shadestds, shadepctile, shadepctiles, shadedata (optional) – As with barstd, barpctile, and bardata, but using shading to indicate the error range. If shadestds is True, the default standard deviation range of +/-2 is used. If shadepctiles is True, the default percentile range of 10 to 90 is used.
fade (bool, default: None) – Shorthand for fadestd.
fadestd, fadestds, fadepctile, fadepctiles, fadedata (optional) – As with shadestd, shadepctile, and shadedata, but for an additional, more faded, secondary shaded region. If fadestds is True, the default standard deviation range of +/-3 is used. If fadepctiles is True, the default percentile range of 0 to 100 is used.
shadec, shadecolor, fadec, fadecolor (color-spec, default: None) – Colors for the different shaded regions. The parent artist color is used by default.
shadez, shadezorder, fadez, fadezorder (float, default: 1.5) – The “zorder” for the different shaded regions.
shadea, shadealpha, fadea, fadealpha (float, default: 0.4, 0.2) – The opacity for the different shaded regions.
shadelw, shadelinewidth, fadelw, fadelinewidth (float, default: rc['patch.linewidth'] = 0.6.) – The edge line width for the shading patches.
shdeec, shadeedgecolor, fadeec, fadeedgecolor (float, default: 'none') – The edge color for the shading patches.
shadelabel, fadelabel (bool or str, optional) – Labels for the shaded regions to be used as separate legend entries. To toggle labels “on” and apply a default label, use e.g. shadelabel=True. To apply a custom label, use e.g. shadelabel='label'. Otherwise, the shading is drawn underneath the line and/or marker in the legend entry.
inbounds (bool, default: rc['axes.inbounds'] = True) – Whether to restrict the default y (x) axis limits to account for only in-bounds data when the x (y) axis limits have been locked. See also rc['axes.inbounds'] and rc['cmap.inbounds'].
label, value (float or str, optional) – The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally used with 1D positional arguments.
labels, values (sequence of float or sequence of str, optional) – The legend labels or colorbar coordinates used for each plotted element. Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to plot().

loglog(*args, **kwargs)[source]

Plot loglog

UltraPlot is optimized for visualizing logarithmic scales by default. For cases with large differences in magnitude, we recommend setting rc["formatter.log"] = True to enhance axis label formatting. Make a plot with log scaling on both the x- and y-axis.

Call signatures:

loglog([x], y, [fmt], data=None, **kwargs)
loglog([x], y, [fmt], [x2], y2, [fmt2], ..., **kwargs)

This is just a thin wrapper around plot which additionally changes both the x-axis and the y-axis to log scaling. All the concepts and parameters of plot can be used here as well.

The additional parameters base, subs and nonpositive control the x/y-axis properties. They are just forwarded to Axes.set_xscale and Axes.set_yscale. To use different properties on the x-axis and the y-axis, use e.g. ax.set_xscale("log", base=10); ax.set_yscale("log", base=2).

Parameters:

base (float, default: 10) – Base of the logarithm.
subs (sequence, optional) – The location of the minor ticks. If None, reasonable locations are automatically chosen depending on the number of decades in the plot. See Axes.set_xscale/Axes.set_yscale for details.
nonpositive ({'mask', 'clip'}, default: 'clip') – Non-positive values can be masked as invalid, or clipped to a very small positive number.
**kwargs – All parameters supported by plot.

Returns:

list of Line2D – Objects representing the plotted data.

Notes

Note

This is the pyplot wrapper for axes.Axes.loglog.

lollipop(*args, **kwargs)[source]

Plot individual or group lollipop graphs.

A lollipop graph is a bar graph with the bars replaced by dots connected to the x-axis by lines.

Inputs such as arrays (x or y) or dataframes (pandas or xarray) are passed through bar(). Colors are inferred from the bar objects and parsed automatically. Formatting of the lollipop consists of controlling the stem and the marker. The stem properties can be set for the width, size, or color. Marker formatting follows the same inputs to scatter().

Parameters:

*args (x or y, x) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only x coordinates are passed, try to infer the y coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the y coordinates are np.arange(0, x.shape[0]).
- If the x coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with boxplot, violinplot, or when using means=True or medians=True).
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
stemlinewdith (str, default :py:class:rc[`”lollipop.stemlinewidth”:py:class:`])
stemcolor (str, default :py:class:rc[`”lollipop.stemcolor”:py:class:`]) – Line color of the lines connecting the dots to the x-axis. Defaults to rc["lollipop.linecolor"].
stemlinestyle (str, default: :py:class:rc[`”lollipop.stemlinestyle”:py:class:`]) – The style of the lines connecting the dots to the x-axis. Defaults to rc["lollipop.linestyle"].
s, size, ms, markersize (float or array-like or unit-spec, optional) – The marker size area(s). If this is an array matching the shape of x and y, the units are scaled by smin and smax. If this contains unit string(s), it is processed by units and represents the width rather than area.
c, color, colors, mc, markercolor, markercolors, fc, facecolor, facecolors (array-like or color-spec, optional) – The marker color(s). If this is an array matching the shape of x and y, the colors are generated using cmap, norm, vmin, and vmax. Otherwise, this should be a valid matplotlib color.
smin, smax (float, optional) – The minimum and maximum marker size area in units points ** 2. Ignored if absolute_size is True. Default value for smin is 1 and for smax is the square of rc['lines.markersize'] = 6.0.
area_size (bool, default: True) – Whether the marker sizes s are scaled by area or by radius. The default True is consistent with matplotlib. When absolute_size is True, the s units are points ** 2 if area_size is True and points if area_size is False.
absolute_size (bool, default: True or False) – Whether s should be taken to represent “absolute” marker sizes in units points or points ** 2 or “relative” marker sizes scaled by smin and smax. Default is True if s is scalar and False if s is array-like or smin or smax were passed.
vmin, vmax (float, optional) – The minimum and maximum color scale values used with the norm normalizer. If discrete is False these are the absolute limits, and if discrete is True these are the approximate limits used to automatically determine levels or values lists at “nice” intervals. If levels or values were already passed as lists, these are ignored, and vmin and vmax are set to the minimum and maximum of the lists. If robust was passed, the default vmin and vmax are some percentile range of the data values. Otherwise, the default vmin and vmax are the minimum and maximum of the data values.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

cmap (colormap-spec, default: rc['cmap.sequential'] = 'Fire' or rc['cmap.diverging'] = 'BuRd') – The colormap specifer, passed to the Colormap constructor function. If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then rc['cmap.diverging'] is used. Otherwise rc['cmap.sequential'] is used.
cmap_kw (dict-like, optional) – Passed to Colormap.
c, color, colors (color-spec or sequence of color-spec, optional) – The color(s) used to create a DiscreteColormap. If not passed, cmap is used.
norm (norm-spec, default: Normalize or DivergingNorm) – The data value normalizer, passed to the Norm constructor function. If discrete is True then 1) this affects the default level-generation algorithm (e.g. norm='log' builds levels in log-space) and 2) this is passed to DiscreteNorm to scale the colors before they are discretized (if norm is not already a DiscreteNorm). If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then DivergingNorm is used. Otherwise Normalize is used.
norm_kw (dict-like, optional) – Passed to Norm.
extend ({'neither', 'both', 'min', 'max'}, default: 'neither') – Direction for drawing colorbar “extensions” indicating out-of-bounds data on the end of the colorbar.
discrete (bool, default: rc['cmap.discrete'] = None) – If False, then DiscreteNorm is not applied to the colormap. Instead, for non-contour plots, the number of levels will be roughly controlled by rc['cmap.lut']. This has a similar effect to using levels=large_number but it may improve rendering speed. Default is True only for contouring commands like contourf and pseudocolor commands like pcolor.
sequential, diverging, cyclic, qualitative (bool, default: None) – Boolean arguments used if cmap is not passed. Set these to True to use the default rc['cmap.sequential'], rc['cmap.diverging'], rc['cmap.cyclic'], and rc['cmap.qualitative'] colormaps. The diverging option also applies DivergingNorm as the default continuous normalizer.
N – Shorthand for levels.
levels (int or sequence of float, default: rc['cmap.levels'] = 11) – The number of level edges or a sequence of level edges. If the former, locator is used to generate this many level edges at “nice” intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing levels fail with contour plots).
values (int or sequence of float, default: None) – The number of level centers or a sequence of level centers. If the former, locator is used to generate this many level centers at “nice” intervals. If the latter, levels are inferred using edges. This will override any levels input.
center_levels (bool, default False) – If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented.
robust (bool, float, or 2-tuple, default: rc['cmap.robust'] = False) – If True and vmin or vmax were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, 90 corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers.
inbounds (bool, default: rc['cmap.inbounds'] = True) – If True and vmin or vmax were not provided, when axis limits have been explicitly restricted with set_xlim() or set_ylim(), out-of-bounds data is ignored. See also rc['cmap.inbounds'] and rc['axes.inbounds'].
locator (locator-spec, default: matplotlib.ticker.MaxNLocator) – The locator used to determine level locations if levels or values were not already passed as lists. Passed to the Locator constructor. Default is MaxNLocator with levels integer levels.
locator_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Locator class.
symmetric (bool, default: False) – If True, the normalization range or discrete colormap levels are symmetric about zero.
positive (bool, default: False) – If True, the normalization range or discrete colormap levels are positive with a minimum at zero.
negative (bool, default: False) – If True, the normaliation range or discrete colormap levels are negative with a minimum at zero.
nozero (bool, default: False) – If True, 0 is removed from the level list. This is mainly useful for single-color contour plots.
cycle (cycle-spec, optional) – The cycle specifer, passed to the Cycle constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use cycle=False, cycle='none', or cycle=() (analogous to disabling ticks with e.g. xformatter='none'). To restore the default property cycler, use cycle=True.
cycle_kw (dict-like, optional) – Passed to Cycle.
lw, linewidth, linewidths, mew, markeredgewidth, markeredgewidths (float or sequence, optional) – The marker edge width(s).
edgecolors, markeredgecolor, markeredgecolors (color-spec or sequence, optional) – The marker edge color(s).
mean, means (bool, default: False) – Whether to plot the means of each column for 2D x coordinates. Means are calculated with numpy.nanmean. If no other arguments are specified, this also sets barstd=True (and boxstd=True for violin plots).
median, medians (bool, default: False) – Whether to plot the medians of each column for 2D x coordinates. Medians are calculated with numpy.nanmedian. If no other arguments arguments are specified, this also sets barstd=True (and boxstd=True for violin plots).
bars (bool, default: None) – Shorthand for barstd, barstds.
barstd, barstds (bool, float, or 2-tuple of float, optional) – Valid only if mean or median is True. Standard deviation multiples for thin error bars with optional whiskers (i.e., caps). If scalar, then +/- that multiple is used. If True, the default standard deviation range of +/-3 is used.
barpctile, barpctiles (bool, float, or 2-tuple of float, optional) – Valid only if mean or median is True. As with barstd, but instead using percentiles for the error bars. If scalar, that percentile range is used (e.g., 90 shows the 5th to 95th percentiles). If True, the default percentile range of 0 to 100 is used.
bardata (array-like, optional) – Valid only if mean and median are False. If shape is 2 x N, these are the lower and upper bounds for the thin error bars. If shape is N, these are the absolute, symmetric deviations from the central points.
boxes (bool, default: None) – Shorthand for boxstd, boxstds.
boxstd, boxstds, boxpctile, boxpctiles, boxdata (optional) – As with barstd, barpctile, and bardata, but for thicker error bars representing a smaller interval than the thin error bars. If boxstds is True, the default standard deviation range of +/-1 is used. If boxpctiles is True, the default percentile range of 25 to 75 is used (i.e., the interquartile range). When “boxes” and “bars” are combined, this has the effect of drawing miniature box-and-whisker plots.
capsize (float, default: rc['errorbar.capsize'] = 3.0) – The cap size for thin error bars in points.
barz, barzorder, boxz, boxzorder (float, default: 2.5) – The “zorder” for the thin and thick error bars.
barc, barcolor, boxc, boxcolor (color-spec, default: rc['boxplot.whiskerprops.color'] = 'black') – Colors for the thin and thick error bars.
barlw, barlinewidth, boxlw, boxlinewidth (float, default: rc['boxplot.whiskerprops.linewidth'] = 1.0) – Line widths for the thin and thick error bars, in points. The default for boxes is 4 times rc['boxplot.whiskerprops.linewidth'].
boxm, boxmarker (bool or marker-spec, default: 'o') – Whether to draw a small marker in the middle of the box denoting the mean or median position. Ignored if boxes is False.
boxms, boxmarkersize (size-spec, default: (2 * boxlinewidth) ** 2) – The marker size for the boxmarker marker in points ** 2.
boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor (color-spec, default: 'w') – Color, face color, and edge color for the boxmarker marker.
shade (bool, default: None) – Shorthand for shadestd.
shadestd, shadestds, shadepctile, shadepctiles, shadedata (optional) – As with barstd, barpctile, and bardata, but using shading to indicate the error range. If shadestds is True, the default standard deviation range of +/-2 is used. If shadepctiles is True, the default percentile range of 10 to 90 is used.
fade (bool, default: None) – Shorthand for fadestd.
fadestd, fadestds, fadepctile, fadepctiles, fadedata (optional) – As with shadestd, shadepctile, and shadedata, but for an additional, more faded, secondary shaded region. If fadestds is True, the default standard deviation range of +/-3 is used. If fadepctiles is True, the default percentile range of 0 to 100 is used.
shadec, shadecolor, fadec, fadecolor (color-spec, default: None) – Colors for the different shaded regions. The parent artist color is used by default.
shadez, shadezorder, fadez, fadezorder (float, default: 1.5) – The “zorder” for the different shaded regions.
shadea, shadealpha, fadea, fadealpha (float, default: 0.4, 0.2) – The opacity for the different shaded regions.
shadelw, shadelinewidth, fadelw, fadelinewidth (float, default: rc['patch.linewidth'] = 0.6.) – The edge line width for the shading patches.
shdeec, shadeedgecolor, fadeec, fadeedgecolor (float, default: 'none') – The edge color for the shading patches.
shadelabel, fadelabel (bool or str, optional) – Labels for the shaded regions to be used as separate legend entries. To toggle labels “on” and apply a default label, use e.g. shadelabel=True. To apply a custom label, use e.g. shadelabel='label'. Otherwise, the shading is drawn underneath the line and/or marker in the legend entry.
inbounds (bool, default: rc['axes.inbounds'] = True) – Whether to restrict the default y (x) axis limits to account for only in-bounds data when the x (y) axis limits have been locked. See also rc['axes.inbounds'] and rc['cmap.inbounds'].
label, value (float or str, optional) – The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally used with 1D positional arguments.
labels, values (sequence of float or sequence of str, optional) – The legend labels or colorbar coordinates used for each plotted element. Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to scatter.
See for more info on the grouping behavior :func:`~ultraplot.PlotAxes.bar`, and for formatting :func:`~ultraplot.PlotAxes.scatter`.

Returns:

List of PatchCollection, and a ~matplotlib.collections.LineCollection

lollipoph(*args, **kwargs)[source]

Plot individual or group lollipop graphs.

A lollipop graph is a bar graph with the bars replaced by dots connected to the x-axis by lines.

Inputs such as arrays (x or y) or dataframes (pandas or xarray) are passed through bar(). Colors are inferred from the bar objects and parsed automatically. Formatting of the lollipop consists of controlling the stem and the marker. The stem properties can be set for the width, size, or color. Marker formatting follows the same inputs to scatter().

Parameters:

*args (x or y, x) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only x coordinates are passed, try to infer the y coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the y coordinates are np.arange(0, x.shape[0]).
- If the x coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with boxplot, violinplot, or when using means=True or medians=True).
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
stemlinewdith (str, default :py:class:rc[`”lollipop.stemlinewidth”:py:class:`])
stemcolor (str, default :py:class:rc[`”lollipop.stemcolor”:py:class:`]) – Line color of the lines connecting the dots to the x-axis. Defaults to rc["lollipop.linecolor"].
stemlinestyle (str, default: :py:class:rc[`”lollipop.stemlinestyle”:py:class:`]) – The style of the lines connecting the dots to the x-axis. Defaults to rc["lollipop.linestyle"].
s, size, ms, markersize (float or array-like or unit-spec, optional) – The marker size area(s). If this is an array matching the shape of x and y, the units are scaled by smin and smax. If this contains unit string(s), it is processed by units and represents the width rather than area.
c, color, colors, mc, markercolor, markercolors, fc, facecolor, facecolors (array-like or color-spec, optional) – The marker color(s). If this is an array matching the shape of x and y, the colors are generated using cmap, norm, vmin, and vmax. Otherwise, this should be a valid matplotlib color.
smin, smax (float, optional) – The minimum and maximum marker size area in units points ** 2. Ignored if absolute_size is True. Default value for smin is 1 and for smax is the square of rc['lines.markersize'] = 6.0.
area_size (bool, default: True) – Whether the marker sizes s are scaled by area or by radius. The default True is consistent with matplotlib. When absolute_size is True, the s units are points ** 2 if area_size is True and points if area_size is False.
absolute_size (bool, default: True or False) – Whether s should be taken to represent “absolute” marker sizes in units points or points ** 2 or “relative” marker sizes scaled by smin and smax. Default is True if s is scalar and False if s is array-like or smin or smax were passed.
vmin, vmax (float, optional) – The minimum and maximum color scale values used with the norm normalizer. If discrete is False these are the absolute limits, and if discrete is True these are the approximate limits used to automatically determine levels or values lists at “nice” intervals. If levels or values were already passed as lists, these are ignored, and vmin and vmax are set to the minimum and maximum of the lists. If robust was passed, the default vmin and vmax are some percentile range of the data values. Otherwise, the default vmin and vmax are the minimum and maximum of the data values.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

cmap (colormap-spec, default: rc['cmap.sequential'] = 'Fire' or rc['cmap.diverging'] = 'BuRd') – The colormap specifer, passed to the Colormap constructor function. If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then rc['cmap.diverging'] is used. Otherwise rc['cmap.sequential'] is used.
cmap_kw (dict-like, optional) – Passed to Colormap.
c, color, colors (color-spec or sequence of color-spec, optional) – The color(s) used to create a DiscreteColormap. If not passed, cmap is used.
norm (norm-spec, default: Normalize or DivergingNorm) – The data value normalizer, passed to the Norm constructor function. If discrete is True then 1) this affects the default level-generation algorithm (e.g. norm='log' builds levels in log-space) and 2) this is passed to DiscreteNorm to scale the colors before they are discretized (if norm is not already a DiscreteNorm). If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then DivergingNorm is used. Otherwise Normalize is used.
norm_kw (dict-like, optional) – Passed to Norm.
extend ({'neither', 'both', 'min', 'max'}, default: 'neither') – Direction for drawing colorbar “extensions” indicating out-of-bounds data on the end of the colorbar.
discrete (bool, default: rc['cmap.discrete'] = None) – If False, then DiscreteNorm is not applied to the colormap. Instead, for non-contour plots, the number of levels will be roughly controlled by rc['cmap.lut']. This has a similar effect to using levels=large_number but it may improve rendering speed. Default is True only for contouring commands like contourf and pseudocolor commands like pcolor.
sequential, diverging, cyclic, qualitative (bool, default: None) – Boolean arguments used if cmap is not passed. Set these to True to use the default rc['cmap.sequential'], rc['cmap.diverging'], rc['cmap.cyclic'], and rc['cmap.qualitative'] colormaps. The diverging option also applies DivergingNorm as the default continuous normalizer.
N – Shorthand for levels.
levels (int or sequence of float, default: rc['cmap.levels'] = 11) – The number of level edges or a sequence of level edges. If the former, locator is used to generate this many level edges at “nice” intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing levels fail with contour plots).
values (int or sequence of float, default: None) – The number of level centers or a sequence of level centers. If the former, locator is used to generate this many level centers at “nice” intervals. If the latter, levels are inferred using edges. This will override any levels input.
center_levels (bool, default False) – If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented.
robust (bool, float, or 2-tuple, default: rc['cmap.robust'] = False) – If True and vmin or vmax were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, 90 corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers.
inbounds (bool, default: rc['cmap.inbounds'] = True) – If True and vmin or vmax were not provided, when axis limits have been explicitly restricted with set_xlim() or set_ylim(), out-of-bounds data is ignored. See also rc['cmap.inbounds'] and rc['axes.inbounds'].
locator (locator-spec, default: matplotlib.ticker.MaxNLocator) – The locator used to determine level locations if levels or values were not already passed as lists. Passed to the Locator constructor. Default is MaxNLocator with levels integer levels.
locator_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Locator class.
symmetric (bool, default: False) – If True, the normalization range or discrete colormap levels are symmetric about zero.
positive (bool, default: False) – If True, the normalization range or discrete colormap levels are positive with a minimum at zero.
negative (bool, default: False) – If True, the normaliation range or discrete colormap levels are negative with a minimum at zero.
nozero (bool, default: False) – If True, 0 is removed from the level list. This is mainly useful for single-color contour plots.
cycle (cycle-spec, optional) – The cycle specifer, passed to the Cycle constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use cycle=False, cycle='none', or cycle=() (analogous to disabling ticks with e.g. xformatter='none'). To restore the default property cycler, use cycle=True.
cycle_kw (dict-like, optional) – Passed to Cycle.
lw, linewidth, linewidths, mew, markeredgewidth, markeredgewidths (float or sequence, optional) – The marker edge width(s).
edgecolors, markeredgecolor, markeredgecolors (color-spec or sequence, optional) – The marker edge color(s).
mean, means (bool, default: False) – Whether to plot the means of each column for 2D x coordinates. Means are calculated with numpy.nanmean. If no other arguments are specified, this also sets barstd=True (and boxstd=True for violin plots).
median, medians (bool, default: False) – Whether to plot the medians of each column for 2D x coordinates. Medians are calculated with numpy.nanmedian. If no other arguments arguments are specified, this also sets barstd=True (and boxstd=True for violin plots).
bars (bool, default: None) – Shorthand for barstd, barstds.
barstd, barstds (bool, float, or 2-tuple of float, optional) – Valid only if mean or median is True. Standard deviation multiples for thin error bars with optional whiskers (i.e., caps). If scalar, then +/- that multiple is used. If True, the default standard deviation range of +/-3 is used.
barpctile, barpctiles (bool, float, or 2-tuple of float, optional) – Valid only if mean or median is True. As with barstd, but instead using percentiles for the error bars. If scalar, that percentile range is used (e.g., 90 shows the 5th to 95th percentiles). If True, the default percentile range of 0 to 100 is used.
bardata (array-like, optional) – Valid only if mean and median are False. If shape is 2 x N, these are the lower and upper bounds for the thin error bars. If shape is N, these are the absolute, symmetric deviations from the central points.
boxes (bool, default: None) – Shorthand for boxstd, boxstds.
boxstd, boxstds, boxpctile, boxpctiles, boxdata (optional) – As with barstd, barpctile, and bardata, but for thicker error bars representing a smaller interval than the thin error bars. If boxstds is True, the default standard deviation range of +/-1 is used. If boxpctiles is True, the default percentile range of 25 to 75 is used (i.e., the interquartile range). When “boxes” and “bars” are combined, this has the effect of drawing miniature box-and-whisker plots.
capsize (float, default: rc['errorbar.capsize'] = 3.0) – The cap size for thin error bars in points.
barz, barzorder, boxz, boxzorder (float, default: 2.5) – The “zorder” for the thin and thick error bars.
barc, barcolor, boxc, boxcolor (color-spec, default: rc['boxplot.whiskerprops.color'] = 'black') – Colors for the thin and thick error bars.
barlw, barlinewidth, boxlw, boxlinewidth (float, default: rc['boxplot.whiskerprops.linewidth'] = 1.0) – Line widths for the thin and thick error bars, in points. The default for boxes is 4 times rc['boxplot.whiskerprops.linewidth'].
boxm, boxmarker (bool or marker-spec, default: 'o') – Whether to draw a small marker in the middle of the box denoting the mean or median position. Ignored if boxes is False.
boxms, boxmarkersize (size-spec, default: (2 * boxlinewidth) ** 2) – The marker size for the boxmarker marker in points ** 2.
boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor (color-spec, default: 'w') – Color, face color, and edge color for the boxmarker marker.
shade (bool, default: None) – Shorthand for shadestd.
shadestd, shadestds, shadepctile, shadepctiles, shadedata (optional) – As with barstd, barpctile, and bardata, but using shading to indicate the error range. If shadestds is True, the default standard deviation range of +/-2 is used. If shadepctiles is True, the default percentile range of 10 to 90 is used.
fade (bool, default: None) – Shorthand for fadestd.
fadestd, fadestds, fadepctile, fadepctiles, fadedata (optional) – As with shadestd, shadepctile, and shadedata, but for an additional, more faded, secondary shaded region. If fadestds is True, the default standard deviation range of +/-3 is used. If fadepctiles is True, the default percentile range of 0 to 100 is used.
shadec, shadecolor, fadec, fadecolor (color-spec, default: None) – Colors for the different shaded regions. The parent artist color is used by default.
shadez, shadezorder, fadez, fadezorder (float, default: 1.5) – The “zorder” for the different shaded regions.
shadea, shadealpha, fadea, fadealpha (float, default: 0.4, 0.2) – The opacity for the different shaded regions.
shadelw, shadelinewidth, fadelw, fadelinewidth (float, default: rc['patch.linewidth'] = 0.6.) – The edge line width for the shading patches.
shdeec, shadeedgecolor, fadeec, fadeedgecolor (float, default: 'none') – The edge color for the shading patches.
shadelabel, fadelabel (bool or str, optional) – Labels for the shaded regions to be used as separate legend entries. To toggle labels “on” and apply a default label, use e.g. shadelabel=True. To apply a custom label, use e.g. shadelabel='label'. Otherwise, the shading is drawn underneath the line and/or marker in the legend entry.
inbounds (bool, default: rc['axes.inbounds'] = True) – Whether to restrict the default y (x) axis limits to account for only in-bounds data when the x (y) axis limits have been locked. See also rc['axes.inbounds'] and rc['cmap.inbounds'].
label, value (float or str, optional) – The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally used with 1D positional arguments.
labels, values (sequence of float or sequence of str, optional) – The legend labels or colorbar coordinates used for each plotted element. Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to scatter.
See for more info on the grouping behavior :func:`~ultraplot.PlotAxes.bar`, and for formatting :func:`~ultraplot.PlotAxes.scatter`.

Returns:

List of PatchCollection, and a ~matplotlib.collections.LineCollection (horizontal lollipop)

matshow(**kwargs)[source]

Plot a matrix.

Parameters:

z (array-like) – The data passed as a positional argument or keyword argument.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

cmap (colormap-spec, default: rc['cmap.sequential'] = 'Fire' or rc['cmap.diverging'] = 'BuRd') – The colormap specifer, passed to the Colormap constructor function. If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then rc['cmap.diverging'] is used. Otherwise rc['cmap.sequential'] is used.
cmap_kw (dict-like, optional) – Passed to Colormap.
c, color, colors (color-spec or sequence of color-spec, optional) – The color(s) used to create a DiscreteColormap. If not passed, cmap is used.
norm (norm-spec, default: Normalize or DivergingNorm) – The data value normalizer, passed to the Norm constructor function. If discrete is True then 1) this affects the default level-generation algorithm (e.g. norm='log' builds levels in log-space) and 2) this is passed to DiscreteNorm to scale the colors before they are discretized (if norm is not already a DiscreteNorm). If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then DivergingNorm is used. Otherwise Normalize is used.
norm_kw (dict-like, optional) – Passed to Norm.
extend ({'neither', 'both', 'min', 'max'}, default: 'neither') – Direction for drawing colorbar “extensions” indicating out-of-bounds data on the end of the colorbar.
discrete (bool, default: rc['cmap.discrete'] = None) – If False, then DiscreteNorm is not applied to the colormap. Instead, for non-contour plots, the number of levels will be roughly controlled by rc['cmap.lut']. This has a similar effect to using levels=large_number but it may improve rendering speed. Default is True only for contouring commands like contourf and pseudocolor commands like pcolor.
sequential, diverging, cyclic, qualitative (bool, default: None) – Boolean arguments used if cmap is not passed. Set these to True to use the default rc['cmap.sequential'], rc['cmap.diverging'], rc['cmap.cyclic'], and rc['cmap.qualitative'] colormaps. The diverging option also applies DivergingNorm as the default continuous normalizer.
vmin, vmax (float, optional) – The minimum and maximum color scale values used with the norm normalizer. If discrete is False these are the absolute limits, and if discrete is True these are the approximate limits used to automatically determine levels or values lists at “nice” intervals. If levels or values were already passed as lists, these are ignored, and vmin and vmax are set to the minimum and maximum of the lists. If robust was passed, the default vmin and vmax are some percentile range of the data values. Otherwise, the default vmin and vmax are the minimum and maximum of the data values.
N – Shorthand for levels.
levels (int or sequence of float, default: rc['cmap.levels'] = 11) – The number of level edges or a sequence of level edges. If the former, locator is used to generate this many level edges at “nice” intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing levels fail with contour plots).
values (int or sequence of float, default: None) – The number of level centers or a sequence of level centers. If the former, locator is used to generate this many level centers at “nice” intervals. If the latter, levels are inferred using edges. This will override any levels input.
center_levels (bool, default False) – If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented.
robust (bool, float, or 2-tuple, default: rc['cmap.robust'] = False) – If True and vmin or vmax were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, 90 corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers.
inbounds (bool, default: rc['cmap.inbounds'] = True) – If True and vmin or vmax were not provided, when axis limits have been explicitly restricted with set_xlim() or set_ylim(), out-of-bounds data is ignored. See also rc['cmap.inbounds'] and rc['axes.inbounds'].
locator (locator-spec, default: matplotlib.ticker.MaxNLocator) – The locator used to determine level locations if levels or values were not already passed as lists. Passed to the Locator constructor. Default is MaxNLocator with levels integer levels.
locator_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Locator class.
symmetric (bool, default: False) – If True, the normalization range or discrete colormap levels are symmetric about zero.
positive (bool, default: False) – If True, the normalization range or discrete colormap levels are positive with a minimum at zero.
negative (bool, default: False) – If True, the normaliation range or discrete colormap levels are negative with a minimum at zero.
nozero (bool, default: False) – If True, 0 is removed from the level list. This is mainly useful for single-color contour plots.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to matplotlib.axes.Axes.matshow.

parametric(x, y, c, *, interp=0, scalex=True, scaley=True, **kwargs)[source]

Plot a parametric line.

Parameters:

*args (y or x, y) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only y coordinates are passed, try to infer the x coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the x coordinates are np.arange(0, y.shape[0]).
- If the y coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with boxplot, violinplot, or when using means=True or medians=True).
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
c, color, colors, values, labels (sequence of float, str, or color-spec, optional) – The parametric coordinate(s). These can be passed as a third positional argument or as a keyword argument. If they are float, the colors will be determined from norm and cmap. If they are strings, the color values will be np.arange(len(colors)) and eventual colorbar ticks will be labeled with the strings. If they are colors, they are used for the line segments and cmap is ignored – for example, colors='blue' makes a monochromatic “parametric” line.
interp (int, default: 0) – Interpolate to this many additional points between the parametric coordinates. This can be increased to make the color gradations between a small number of coordinates appear “smooth”.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

cmap (colormap-spec, default: rc['cmap.sequential'] = 'Fire' or rc['cmap.diverging'] = 'BuRd') – The colormap specifer, passed to the Colormap constructor function. If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then rc['cmap.diverging'] is used. Otherwise rc['cmap.sequential'] is used.
cmap_kw (dict-like, optional) – Passed to Colormap.
c, color, colors (color-spec or sequence of color-spec, optional) – The color(s) used to create a DiscreteColormap. If not passed, cmap is used.
norm (norm-spec, default: Normalize or DivergingNorm) – The data value normalizer, passed to the Norm constructor function. If discrete is True then 1) this affects the default level-generation algorithm (e.g. norm='log' builds levels in log-space) and 2) this is passed to DiscreteNorm to scale the colors before they are discretized (if norm is not already a DiscreteNorm). If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then DivergingNorm is used. Otherwise Normalize is used.
norm_kw (dict-like, optional) – Passed to Norm.
extend ({'neither', 'both', 'min', 'max'}, default: 'neither') – Direction for drawing colorbar “extensions” indicating out-of-bounds data on the end of the colorbar.
discrete (bool, default: rc['cmap.discrete'] = None) – If False, then DiscreteNorm is not applied to the colormap. Instead, for non-contour plots, the number of levels will be roughly controlled by rc['cmap.lut']. This has a similar effect to using levels=large_number but it may improve rendering speed. Default is True only for contouring commands like contourf and pseudocolor commands like pcolor.
sequential, diverging, cyclic, qualitative (bool, default: None) – Boolean arguments used if cmap is not passed. Set these to True to use the default rc['cmap.sequential'], rc['cmap.diverging'], rc['cmap.cyclic'], and rc['cmap.qualitative'] colormaps. The diverging option also applies DivergingNorm as the default continuous normalizer.
vmin, vmax (float, optional) – The minimum and maximum color scale values used with the norm normalizer. If discrete is False these are the absolute limits, and if discrete is True these are the approximate limits used to automatically determine levels or values lists at “nice” intervals. If levels or values were already passed as lists, these are ignored, and vmin and vmax are set to the minimum and maximum of the lists. If robust was passed, the default vmin and vmax are some percentile range of the data values. Otherwise, the default vmin and vmax are the minimum and maximum of the data values.
inbounds (bool, default: rc['axes.inbounds'] = True) – Whether to restrict the default y (x) axis limits to account for only in-bounds data when the x (y) axis limits have been locked. See also rc['axes.inbounds'] and rc['cmap.inbounds'].
scalex, scaley (bool, optional) – Whether the view limits are adapted to the data limits. The values are passed on to autoscale_view.
label, value (float or str, optional) – The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally used with 1D positional arguments.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Valid LineCollection properties.

Returns:

LineCollection – The parametric line. See this matplotlib example.

pcolor(**kwargs)[source]

Plot irregular grid boxes.

Parameters:

*args (z or x, y, z) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only z coordinates are passed, try to infer the x and y coordinates from the DataFrame indices and columns or the DataArray coordinates. Otherwise, the y coordinates are np.arange(0, y.shape[0]) and the x coordinates are np.arange(0, y.shape[1]).
- For pcolor and pcolormesh, calculate coordinate edges using edges or :func:`~ultraplot.utils.edges2d` if centers were provided. For all other methods, calculate coordinate centers if edges were provided.
- If the x or y coordinates are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. If the z coordinates are pint.Quantity, pass the magnitude to the plotting command. A pint.Quantity embedded in an xarray.DataArray is also supported.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.
transpose (bool, default: False) – Whether to transpose the input data. This should be used when passing datasets with column-major dimension order (x, y). Otherwise row-major dimension order (y, x) is expected.
order ({'C', 'F'}, default: 'C') – Alternative to transpose. 'C' corresponds to the default C-cyle row-major ordering (equivalent to transpose=False). 'F' corresponds to Fortran-style column-major ordering (equivalent to transpose=True).
globe (bool, default: False) – For ultraplot.axes.GeoAxes only. Whether to enforce global coverage. When set to True this does the following:
1. Interpolates input data to the North and South poles by setting the data values at the poles to the mean from latitudes nearest each pole.
2. Makes meridional coverage “circular”, i.e. the last longitude coordinate equals the first longitude coordinate plus 360°.
3. When basemap is the backend, cycles 1D longitude vectors to fit within the map edges. For example, if the central longitude is 90°, the data is shifted so that it spans -90° to 270°.

Other Parameters:

cmap (colormap-spec, default: rc['cmap.sequential'] = 'Fire' or rc['cmap.diverging'] = 'BuRd') – The colormap specifer, passed to the Colormap constructor function. If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then rc['cmap.diverging'] is used. Otherwise rc['cmap.sequential'] is used.
cmap_kw (dict-like, optional) – Passed to Colormap.
c, color, colors (color-spec or sequence of color-spec, optional) – The color(s) used to create a DiscreteColormap. If not passed, cmap is used.
norm (norm-spec, default: Normalize or DivergingNorm) – The data value normalizer, passed to the Norm constructor function. If discrete is True then 1) this affects the default level-generation algorithm (e.g. norm='log' builds levels in log-space) and 2) this is passed to DiscreteNorm to scale the colors before they are discretized (if norm is not already a DiscreteNorm). If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then DivergingNorm is used. Otherwise Normalize is used.
norm_kw (dict-like, optional) – Passed to Norm.
extend ({'neither', 'both', 'min', 'max'}, default: 'neither') – Direction for drawing colorbar “extensions” indicating out-of-bounds data on the end of the colorbar.
discrete (bool, default: rc['cmap.discrete'] = None) – If False, then DiscreteNorm is not applied to the colormap. Instead, for non-contour plots, the number of levels will be roughly controlled by rc['cmap.lut']. This has a similar effect to using levels=large_number but it may improve rendering speed. Default is True only for contouring commands like contourf and pseudocolor commands like pcolor.
sequential, diverging, cyclic, qualitative (bool, default: None) – Boolean arguments used if cmap is not passed. Set these to True to use the default rc['cmap.sequential'], rc['cmap.diverging'], rc['cmap.cyclic'], and rc['cmap.qualitative'] colormaps. The diverging option also applies DivergingNorm as the default continuous normalizer.
vmin, vmax (float, optional) – The minimum and maximum color scale values used with the norm normalizer. If discrete is False these are the absolute limits, and if discrete is True these are the approximate limits used to automatically determine levels or values lists at “nice” intervals. If levels or values were already passed as lists, these are ignored, and vmin and vmax are set to the minimum and maximum of the lists. If robust was passed, the default vmin and vmax are some percentile range of the data values. Otherwise, the default vmin and vmax are the minimum and maximum of the data values.
N – Shorthand for levels.
levels (int or sequence of float, default: rc['cmap.levels'] = 11) – The number of level edges or a sequence of level edges. If the former, locator is used to generate this many level edges at “nice” intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing levels fail with contour plots).
values (int or sequence of float, default: None) – The number of level centers or a sequence of level centers. If the former, locator is used to generate this many level centers at “nice” intervals. If the latter, levels are inferred using edges. This will override any levels input.
center_levels (bool, default False) – If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented.
robust (bool, float, or 2-tuple, default: rc['cmap.robust'] = False) – If True and vmin or vmax were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, 90 corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers.
inbounds (bool, default: rc['cmap.inbounds'] = True) – If True and vmin or vmax were not provided, when axis limits have been explicitly restricted with set_xlim() or set_ylim(), out-of-bounds data is ignored. See also rc['cmap.inbounds'] and rc['axes.inbounds'].
locator (locator-spec, default: matplotlib.ticker.MaxNLocator) – The locator used to determine level locations if levels or values were not already passed as lists. Passed to the Locator constructor. Default is MaxNLocator with levels integer levels.
locator_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Locator class.
symmetric (bool, default: False) – If True, the normalization range or discrete colormap levels are symmetric about zero.
positive (bool, default: False) – If True, the normalization range or discrete colormap levels are positive with a minimum at zero.
negative (bool, default: False) – If True, the normaliation range or discrete colormap levels are negative with a minimum at zero.
nozero (bool, default: False) – If True, 0 is removed from the level list. This is mainly useful for single-color contour plots.
lw, linewidth, linewidths (unit-spec, default: 0.3) – The width of lines between grid boxes. If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: '-') – The style of lines between grid boxes.
ec, edgecolor, edgecolors (color-spec, default: 'k') – The color of lines between grid boxes.
a, alpha, alphas (float, optional) – The opacity of the grid boxes. Inferred from cmap by default.
edgefix (bool or float, default: rc.edgefix = True) – Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). See this github repo for a demonstration of the problem. If True, a small default linewidth of 0.3 is used to cover up the white lines. If float (e.g. edgefix=0.5), this specific linewidth is used to cover up the white lines. This feature is automatically disabled when the patches have transparency.
label (str, optional) – The legend label to be used for this object. In the case of contours, this is paired with the the central artist in the artist list returned by matplotlib.contour.ContourSet.legend_elements.
labels (bool, optional) – Whether to apply labels to contours and grid boxes. The text will be white when the luminance of the underlying filled contour or grid box is less than 50 and black otherwise.
labels_kw (dict-like, optional) – Ignored if labels is False. Extra keyword args for the labels. For contour plots, this is passed to clabel. Otherwise, this is passed to text.
formatter, fmt (formatter-spec, optional) – The Formatter used to format number labels. Passed to the Formatter constructor.
formatter_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Formatter class.
precision (int, optional) – The maximum number of decimal places for number labels generated with the default formatter Simpleformatter.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to matplotlib.axes.Axes.pcolor.

pcolorfast(**kwargs)[source]

Plot grid boxes quickly.

Parameters:

*args (z or x, y, z) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only z coordinates are passed, try to infer the x and y coordinates from the DataFrame indices and columns or the DataArray coordinates. Otherwise, the y coordinates are np.arange(0, y.shape[0]) and the x coordinates are np.arange(0, y.shape[1]).
- For pcolor and pcolormesh, calculate coordinate edges using edges or :func:`~ultraplot.utils.edges2d` if centers were provided. For all other methods, calculate coordinate centers if edges were provided.
- If the x or y coordinates are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. If the z coordinates are pint.Quantity, pass the magnitude to the plotting command. A pint.Quantity embedded in an xarray.DataArray is also supported.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.
transpose (bool, default: False) – Whether to transpose the input data. This should be used when passing datasets with column-major dimension order (x, y). Otherwise row-major dimension order (y, x) is expected.
order ({'C', 'F'}, default: 'C') – Alternative to transpose. 'C' corresponds to the default C-cyle row-major ordering (equivalent to transpose=False). 'F' corresponds to Fortran-style column-major ordering (equivalent to transpose=True).
globe (bool, default: False) – For ultraplot.axes.GeoAxes only. Whether to enforce global coverage. When set to True this does the following:
1. Interpolates input data to the North and South poles by setting the data values at the poles to the mean from latitudes nearest each pole.
2. Makes meridional coverage “circular”, i.e. the last longitude coordinate equals the first longitude coordinate plus 360°.
3. When basemap is the backend, cycles 1D longitude vectors to fit within the map edges. For example, if the central longitude is 90°, the data is shifted so that it spans -90° to 270°.

Other Parameters:

cmap (colormap-spec, default: rc['cmap.sequential'] = 'Fire' or rc['cmap.diverging'] = 'BuRd') – The colormap specifer, passed to the Colormap constructor function. If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then rc['cmap.diverging'] is used. Otherwise rc['cmap.sequential'] is used.
cmap_kw (dict-like, optional) – Passed to Colormap.
c, color, colors (color-spec or sequence of color-spec, optional) – The color(s) used to create a DiscreteColormap. If not passed, cmap is used.
norm (norm-spec, default: Normalize or DivergingNorm) – The data value normalizer, passed to the Norm constructor function. If discrete is True then 1) this affects the default level-generation algorithm (e.g. norm='log' builds levels in log-space) and 2) this is passed to DiscreteNorm to scale the colors before they are discretized (if norm is not already a DiscreteNorm). If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then DivergingNorm is used. Otherwise Normalize is used.
norm_kw (dict-like, optional) – Passed to Norm.
extend ({'neither', 'both', 'min', 'max'}, default: 'neither') – Direction for drawing colorbar “extensions” indicating out-of-bounds data on the end of the colorbar.
discrete (bool, default: rc['cmap.discrete'] = None) – If False, then DiscreteNorm is not applied to the colormap. Instead, for non-contour plots, the number of levels will be roughly controlled by rc['cmap.lut']. This has a similar effect to using levels=large_number but it may improve rendering speed. Default is True only for contouring commands like contourf and pseudocolor commands like pcolor.
sequential, diverging, cyclic, qualitative (bool, default: None) – Boolean arguments used if cmap is not passed. Set these to True to use the default rc['cmap.sequential'], rc['cmap.diverging'], rc['cmap.cyclic'], and rc['cmap.qualitative'] colormaps. The diverging option also applies DivergingNorm as the default continuous normalizer.
vmin, vmax (float, optional) – The minimum and maximum color scale values used with the norm normalizer. If discrete is False these are the absolute limits, and if discrete is True these are the approximate limits used to automatically determine levels or values lists at “nice” intervals. If levels or values were already passed as lists, these are ignored, and vmin and vmax are set to the minimum and maximum of the lists. If robust was passed, the default vmin and vmax are some percentile range of the data values. Otherwise, the default vmin and vmax are the minimum and maximum of the data values.
N – Shorthand for levels.
levels (int or sequence of float, default: rc['cmap.levels'] = 11) – The number of level edges or a sequence of level edges. If the former, locator is used to generate this many level edges at “nice” intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing levels fail with contour plots).
values (int or sequence of float, default: None) – The number of level centers or a sequence of level centers. If the former, locator is used to generate this many level centers at “nice” intervals. If the latter, levels are inferred using edges. This will override any levels input.
center_levels (bool, default False) – If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented.
robust (bool, float, or 2-tuple, default: rc['cmap.robust'] = False) – If True and vmin or vmax were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, 90 corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers.
inbounds (bool, default: rc['cmap.inbounds'] = True) – If True and vmin or vmax were not provided, when axis limits have been explicitly restricted with set_xlim() or set_ylim(), out-of-bounds data is ignored. See also rc['cmap.inbounds'] and rc['axes.inbounds'].
locator (locator-spec, default: matplotlib.ticker.MaxNLocator) – The locator used to determine level locations if levels or values were not already passed as lists. Passed to the Locator constructor. Default is MaxNLocator with levels integer levels.
locator_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Locator class.
symmetric (bool, default: False) – If True, the normalization range or discrete colormap levels are symmetric about zero.
positive (bool, default: False) – If True, the normalization range or discrete colormap levels are positive with a minimum at zero.
negative (bool, default: False) – If True, the normaliation range or discrete colormap levels are negative with a minimum at zero.
nozero (bool, default: False) – If True, 0 is removed from the level list. This is mainly useful for single-color contour plots.
lw, linewidth, linewidths (unit-spec, default: 0.3) – The width of lines between grid boxes. If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: '-') – The style of lines between grid boxes.
ec, edgecolor, edgecolors (color-spec, default: 'k') – The color of lines between grid boxes.
a, alpha, alphas (float, optional) – The opacity of the grid boxes. Inferred from cmap by default.
edgefix (bool or float, default: rc.edgefix = True) – Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). See this github repo for a demonstration of the problem. If True, a small default linewidth of 0.3 is used to cover up the white lines. If float (e.g. edgefix=0.5), this specific linewidth is used to cover up the white lines. This feature is automatically disabled when the patches have transparency.
label (str, optional) – The legend label to be used for this object. In the case of contours, this is paired with the the central artist in the artist list returned by matplotlib.contour.ContourSet.legend_elements.
labels (bool, optional) – Whether to apply labels to contours and grid boxes. The text will be white when the luminance of the underlying filled contour or grid box is less than 50 and black otherwise.
labels_kw (dict-like, optional) – Ignored if labels is False. Extra keyword args for the labels. For contour plots, this is passed to clabel. Otherwise, this is passed to text.
formatter, fmt (formatter-spec, optional) – The Formatter used to format number labels. Passed to the Formatter constructor.
formatter_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Formatter class.
precision (int, optional) – The maximum number of decimal places for number labels generated with the default formatter Simpleformatter.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to matplotlib.axes.Axes.pcolorfast.

pcolormesh(**kwargs)[source]

Plot regular grid boxes.

Parameters:

*args (z or x, y, z) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only z coordinates are passed, try to infer the x and y coordinates from the DataFrame indices and columns or the DataArray coordinates. Otherwise, the y coordinates are np.arange(0, y.shape[0]) and the x coordinates are np.arange(0, y.shape[1]).
- For pcolor and pcolormesh, calculate coordinate edges using edges or :func:`~ultraplot.utils.edges2d` if centers were provided. For all other methods, calculate coordinate centers if edges were provided.
- If the x or y coordinates are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. If the z coordinates are pint.Quantity, pass the magnitude to the plotting command. A pint.Quantity embedded in an xarray.DataArray is also supported.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.
transpose (bool, default: False) – Whether to transpose the input data. This should be used when passing datasets with column-major dimension order (x, y). Otherwise row-major dimension order (y, x) is expected.
order ({'C', 'F'}, default: 'C') – Alternative to transpose. 'C' corresponds to the default C-cyle row-major ordering (equivalent to transpose=False). 'F' corresponds to Fortran-style column-major ordering (equivalent to transpose=True).
globe (bool, default: False) – For ultraplot.axes.GeoAxes only. Whether to enforce global coverage. When set to True this does the following:
1. Interpolates input data to the North and South poles by setting the data values at the poles to the mean from latitudes nearest each pole.
2. Makes meridional coverage “circular”, i.e. the last longitude coordinate equals the first longitude coordinate plus 360°.
3. When basemap is the backend, cycles 1D longitude vectors to fit within the map edges. For example, if the central longitude is 90°, the data is shifted so that it spans -90° to 270°.

Other Parameters:

cmap (colormap-spec, default: rc['cmap.sequential'] = 'Fire' or rc['cmap.diverging'] = 'BuRd') – The colormap specifer, passed to the Colormap constructor function. If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then rc['cmap.diverging'] is used. Otherwise rc['cmap.sequential'] is used.
cmap_kw (dict-like, optional) – Passed to Colormap.
c, color, colors (color-spec or sequence of color-spec, optional) – The color(s) used to create a DiscreteColormap. If not passed, cmap is used.
norm (norm-spec, default: Normalize or DivergingNorm) – The data value normalizer, passed to the Norm constructor function. If discrete is True then 1) this affects the default level-generation algorithm (e.g. norm='log' builds levels in log-space) and 2) this is passed to DiscreteNorm to scale the colors before they are discretized (if norm is not already a DiscreteNorm). If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then DivergingNorm is used. Otherwise Normalize is used.
norm_kw (dict-like, optional) – Passed to Norm.
extend ({'neither', 'both', 'min', 'max'}, default: 'neither') – Direction for drawing colorbar “extensions” indicating out-of-bounds data on the end of the colorbar.
discrete (bool, default: rc['cmap.discrete'] = None) – If False, then DiscreteNorm is not applied to the colormap. Instead, for non-contour plots, the number of levels will be roughly controlled by rc['cmap.lut']. This has a similar effect to using levels=large_number but it may improve rendering speed. Default is True only for contouring commands like contourf and pseudocolor commands like pcolor.
sequential, diverging, cyclic, qualitative (bool, default: None) – Boolean arguments used if cmap is not passed. Set these to True to use the default rc['cmap.sequential'], rc['cmap.diverging'], rc['cmap.cyclic'], and rc['cmap.qualitative'] colormaps. The diverging option also applies DivergingNorm as the default continuous normalizer.
vmin, vmax (float, optional) – The minimum and maximum color scale values used with the norm normalizer. If discrete is False these are the absolute limits, and if discrete is True these are the approximate limits used to automatically determine levels or values lists at “nice” intervals. If levels or values were already passed as lists, these are ignored, and vmin and vmax are set to the minimum and maximum of the lists. If robust was passed, the default vmin and vmax are some percentile range of the data values. Otherwise, the default vmin and vmax are the minimum and maximum of the data values.
N – Shorthand for levels.
levels (int or sequence of float, default: rc['cmap.levels'] = 11) – The number of level edges or a sequence of level edges. If the former, locator is used to generate this many level edges at “nice” intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing levels fail with contour plots).
values (int or sequence of float, default: None) – The number of level centers or a sequence of level centers. If the former, locator is used to generate this many level centers at “nice” intervals. If the latter, levels are inferred using edges. This will override any levels input.
center_levels (bool, default False) – If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented.
robust (bool, float, or 2-tuple, default: rc['cmap.robust'] = False) – If True and vmin or vmax were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, 90 corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers.
inbounds (bool, default: rc['cmap.inbounds'] = True) – If True and vmin or vmax were not provided, when axis limits have been explicitly restricted with set_xlim() or set_ylim(), out-of-bounds data is ignored. See also rc['cmap.inbounds'] and rc['axes.inbounds'].
locator (locator-spec, default: matplotlib.ticker.MaxNLocator) – The locator used to determine level locations if levels or values were not already passed as lists. Passed to the Locator constructor. Default is MaxNLocator with levels integer levels.
locator_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Locator class.
symmetric (bool, default: False) – If True, the normalization range or discrete colormap levels are symmetric about zero.
positive (bool, default: False) – If True, the normalization range or discrete colormap levels are positive with a minimum at zero.
negative (bool, default: False) – If True, the normaliation range or discrete colormap levels are negative with a minimum at zero.
nozero (bool, default: False) – If True, 0 is removed from the level list. This is mainly useful for single-color contour plots.
lw, linewidth, linewidths (unit-spec, default: 0.3) – The width of lines between grid boxes. If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: '-') – The style of lines between grid boxes.
ec, edgecolor, edgecolors (color-spec, default: 'k') – The color of lines between grid boxes.
a, alpha, alphas (float, optional) – The opacity of the grid boxes. Inferred from cmap by default.
edgefix (bool or float, default: rc.edgefix = True) – Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). See this github repo for a demonstration of the problem. If True, a small default linewidth of 0.3 is used to cover up the white lines. If float (e.g. edgefix=0.5), this specific linewidth is used to cover up the white lines. This feature is automatically disabled when the patches have transparency.
label (str, optional) – The legend label to be used for this object. In the case of contours, this is paired with the the central artist in the artist list returned by matplotlib.contour.ContourSet.legend_elements.
labels (bool, optional) – Whether to apply labels to contours and grid boxes. The text will be white when the luminance of the underlying filled contour or grid box is less than 50 and black otherwise.
labels_kw (dict-like, optional) – Ignored if labels is False. Extra keyword args for the labels. For contour plots, this is passed to clabel. Otherwise, this is passed to text.
formatter, fmt (formatter-spec, optional) – The Formatter used to format number labels. Passed to the Formatter constructor.
formatter_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Formatter class.
precision (int, optional) – The maximum number of decimal places for number labels generated with the default formatter Simpleformatter.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to matplotlib.axes.Axes.pcolormesh.

pie(**kwargs)[source]

Plot a pie chart.

Parameters:

*args (y or x, y) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only y coordinates are passed, try to infer the x coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the x coordinates are np.arange(0, y.shape[0]).
- If the y coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with boxplot, violinplot, or when using means=True or medians=True).
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

cycle (cycle-spec, optional) – The cycle specifer, passed to the Cycle constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use cycle=False, cycle='none', or cycle=() (analogous to disabling ticks with e.g. xformatter='none'). To restore the default property cycler, use cycle=True.
cycle_kw (dict-like, optional) – Passed to Cycle.
lw, linewidth, linewidths (unit-spec, default: rc['patch.linewidth'] = 0.6) – The edge width of the patch(es). If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: '-') – The edge style of the patch(es).
ec, edgecolor, edgecolors (color-spec, default: 'none') – The edge color of the patch(es).
fc, facecolor, facecolors, fillcolor, fillcolors (color-spec, optional) – The face color of the patch(es). The property cycle is used by default.
a, alpha, alphas (float, optional) – The opacity of the patch(es). Inferred from facecolor and edgecolor by default.
edgefix (bool or float, default: rc.edgefix = True) – Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). See this github repo for a demonstration of the problem. If True, a small default linewidth of 0.3 is used to cover up the white lines. If float (e.g. edgefix=0.5), this specific linewidth is used to cover up the white lines. This feature is automatically disabled when the patches have transparency.
label, value (float or str, optional) – The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally used with 1D positional arguments.
labels, values (sequence of float or sequence of str, optional) – The legend labels or colorbar coordinates used for each plotted element. Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments.
labelpad, labeldistance (float, optional) – The distance at which labels are drawn in radial coordinates.

See also

matplotlib.axes.Axes.pie

plot(**kwargs)[source]

Plot standard lines.

Parameters:

*args (y or x, y) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only y coordinates are passed, try to infer the x coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the x coordinates are np.arange(0, y.shape[0]).
- If the y coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with boxplot, violinplot, or when using means=True or medians=True).
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

cycle (cycle-spec, optional) – The cycle specifer, passed to the Cycle constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use cycle=False, cycle='none', or cycle=() (analogous to disabling ticks with e.g. xformatter='none'). To restore the default property cycler, use cycle=True.
cycle_kw (dict-like, optional) – Passed to Cycle.
lw, linewidth, linewidths (unit-spec, default: rc['lines.linewidth'] = 1.5) – The width of the line(s). If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: rc['lines.linestyle'] = '-') – The style of the line(s).
c, color, colors (color-spec, optional) – The color of the line(s). The property cycle is used by default.
a, alpha, alphas (float, optional) – The opacity of the line(s). Inferred from color by default.
mean, means (bool, default: False) – Whether to plot the means of each column for 2D y coordinates. Means are calculated with numpy.nanmean. If no other arguments are specified, this also sets barstd=True (and boxstd=True for violin plots).
median, medians (bool, default: False) – Whether to plot the medians of each column for 2D y coordinates. Medians are calculated with numpy.nanmedian. If no other arguments arguments are specified, this also sets barstd=True (and boxstd=True for violin plots).
bars (bool, default: None) – Shorthand for barstd, barstds.
barstd, barstds (bool, float, or 2-tuple of float, optional) – Valid only if mean or median is True. Standard deviation multiples for thin error bars with optional whiskers (i.e., caps). If scalar, then +/- that multiple is used. If True, the default standard deviation range of +/-3 is used.
barpctile, barpctiles (bool, float, or 2-tuple of float, optional) – Valid only if mean or median is True. As with barstd, but instead using percentiles for the error bars. If scalar, that percentile range is used (e.g., 90 shows the 5th to 95th percentiles). If True, the default percentile range of 0 to 100 is used.
bardata (array-like, optional) – Valid only if mean and median are False. If shape is 2 x N, these are the lower and upper bounds for the thin error bars. If shape is N, these are the absolute, symmetric deviations from the central points.
boxes (bool, default: None) – Shorthand for boxstd, boxstds.
boxstd, boxstds, boxpctile, boxpctiles, boxdata (optional) – As with barstd, barpctile, and bardata, but for thicker error bars representing a smaller interval than the thin error bars. If boxstds is True, the default standard deviation range of +/-1 is used. If boxpctiles is True, the default percentile range of 25 to 75 is used (i.e., the interquartile range). When “boxes” and “bars” are combined, this has the effect of drawing miniature box-and-whisker plots.
capsize (float, default: rc['errorbar.capsize'] = 3.0) – The cap size for thin error bars in points.
barz, barzorder, boxz, boxzorder (float, default: 2.5) – The “zorder” for the thin and thick error bars.
barc, barcolor, boxc, boxcolor (color-spec, default: rc['boxplot.whiskerprops.color'] = 'black') – Colors for the thin and thick error bars.
barlw, barlinewidth, boxlw, boxlinewidth (float, default: rc['boxplot.whiskerprops.linewidth'] = 1.0) – Line widths for the thin and thick error bars, in points. The default for boxes is 4 times rc['boxplot.whiskerprops.linewidth'].
boxm, boxmarker (bool or marker-spec, default: 'o') – Whether to draw a small marker in the middle of the box denoting the mean or median position. Ignored if boxes is False.
boxms, boxmarkersize (size-spec, default: (2 * boxlinewidth) ** 2) – The marker size for the boxmarker marker in points ** 2.
boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor (color-spec, default: 'w') – Color, face color, and edge color for the boxmarker marker.
shade (bool, default: None) – Shorthand for shadestd.
shadestd, shadestds, shadepctile, shadepctiles, shadedata (optional) – As with barstd, barpctile, and bardata, but using shading to indicate the error range. If shadestds is True, the default standard deviation range of +/-2 is used. If shadepctiles is True, the default percentile range of 10 to 90 is used.
fade (bool, default: None) – Shorthand for fadestd.
fadestd, fadestds, fadepctile, fadepctiles, fadedata (optional) – As with shadestd, shadepctile, and shadedata, but for an additional, more faded, secondary shaded region. If fadestds is True, the default standard deviation range of +/-3 is used. If fadepctiles is True, the default percentile range of 0 to 100 is used.
shadec, shadecolor, fadec, fadecolor (color-spec, default: None) – Colors for the different shaded regions. The parent artist color is used by default.
shadez, shadezorder, fadez, fadezorder (float, default: 1.5) – The “zorder” for the different shaded regions.
shadea, shadealpha, fadea, fadealpha (float, default: 0.4, 0.2) – The opacity for the different shaded regions.
shadelw, shadelinewidth, fadelw, fadelinewidth (float, default: rc['patch.linewidth'] = 0.6.) – The edge line width for the shading patches.
shdeec, shadeedgecolor, fadeec, fadeedgecolor (float, default: 'none') – The edge color for the shading patches.
shadelabel, fadelabel (bool or str, optional) – Labels for the shaded regions to be used as separate legend entries. To toggle labels “on” and apply a default label, use e.g. shadelabel=True. To apply a custom label, use e.g. shadelabel='label'. Otherwise, the shading is drawn underneath the line and/or marker in the legend entry.
inbounds (bool, default: rc['axes.inbounds'] = True) – Whether to restrict the default y (x) axis limits to account for only in-bounds data when the x (y) axis limits have been locked. See also rc['axes.inbounds'] and rc['cmap.inbounds'].
label, value (float or str, optional) – The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally used with 1D positional arguments.
labels, values (sequence of float or sequence of str, optional) – The legend labels or colorbar coordinates used for each plotted element. Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to plot().

plotx(*args, **kwargs)[source]

Plot standard lines.

Parameters:

*args (x or y, x) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only x coordinates are passed, try to infer the y coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the y coordinates are np.arange(0, x.shape[0]).
- If the x coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with boxplot, violinplot, or when using means=True or medians=True).
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

cycle (cycle-spec, optional) – The cycle specifer, passed to the Cycle constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use cycle=False, cycle='none', or cycle=() (analogous to disabling ticks with e.g. xformatter='none'). To restore the default property cycler, use cycle=True.
cycle_kw (dict-like, optional) – Passed to Cycle.
lw, linewidth, linewidths (unit-spec, default: rc['lines.linewidth'] = 1.5) – The width of the line(s). If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: rc['lines.linestyle'] = '-') – The style of the line(s).
c, color, colors (color-spec, optional) – The color of the line(s). The property cycle is used by default.
a, alpha, alphas (float, optional) – The opacity of the line(s). Inferred from color by default.
mean, means (bool, default: False) – Whether to plot the means of each column for 2D x coordinates. Means are calculated with numpy.nanmean. If no other arguments are specified, this also sets barstd=True (and boxstd=True for violin plots).
median, medians (bool, default: False) – Whether to plot the medians of each column for 2D x coordinates. Medians are calculated with numpy.nanmedian. If no other arguments arguments are specified, this also sets barstd=True (and boxstd=True for violin plots).
bars (bool, default: None) – Shorthand for barstd, barstds.
barstd, barstds (bool, float, or 2-tuple of float, optional) – Valid only if mean or median is True. Standard deviation multiples for thin error bars with optional whiskers (i.e., caps). If scalar, then +/- that multiple is used. If True, the default standard deviation range of +/-3 is used.
barpctile, barpctiles (bool, float, or 2-tuple of float, optional) – Valid only if mean or median is True. As with barstd, but instead using percentiles for the error bars. If scalar, that percentile range is used (e.g., 90 shows the 5th to 95th percentiles). If True, the default percentile range of 0 to 100 is used.
bardata (array-like, optional) – Valid only if mean and median are False. If shape is 2 x N, these are the lower and upper bounds for the thin error bars. If shape is N, these are the absolute, symmetric deviations from the central points.
boxes (bool, default: None) – Shorthand for boxstd, boxstds.
boxstd, boxstds, boxpctile, boxpctiles, boxdata (optional) – As with barstd, barpctile, and bardata, but for thicker error bars representing a smaller interval than the thin error bars. If boxstds is True, the default standard deviation range of +/-1 is used. If boxpctiles is True, the default percentile range of 25 to 75 is used (i.e., the interquartile range). When “boxes” and “bars” are combined, this has the effect of drawing miniature box-and-whisker plots.
capsize (float, default: rc['errorbar.capsize'] = 3.0) – The cap size for thin error bars in points.
barz, barzorder, boxz, boxzorder (float, default: 2.5) – The “zorder” for the thin and thick error bars.
barc, barcolor, boxc, boxcolor (color-spec, default: rc['boxplot.whiskerprops.color'] = 'black') – Colors for the thin and thick error bars.
barlw, barlinewidth, boxlw, boxlinewidth (float, default: rc['boxplot.whiskerprops.linewidth'] = 1.0) – Line widths for the thin and thick error bars, in points. The default for boxes is 4 times rc['boxplot.whiskerprops.linewidth'].
boxm, boxmarker (bool or marker-spec, default: 'o') – Whether to draw a small marker in the middle of the box denoting the mean or median position. Ignored if boxes is False.
boxms, boxmarkersize (size-spec, default: (2 * boxlinewidth) ** 2) – The marker size for the boxmarker marker in points ** 2.
boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor (color-spec, default: 'w') – Color, face color, and edge color for the boxmarker marker.
shade (bool, default: None) – Shorthand for shadestd.
shadestd, shadestds, shadepctile, shadepctiles, shadedata (optional) – As with barstd, barpctile, and bardata, but using shading to indicate the error range. If shadestds is True, the default standard deviation range of +/-2 is used. If shadepctiles is True, the default percentile range of 10 to 90 is used.
fade (bool, default: None) – Shorthand for fadestd.
fadestd, fadestds, fadepctile, fadepctiles, fadedata (optional) – As with shadestd, shadepctile, and shadedata, but for an additional, more faded, secondary shaded region. If fadestds is True, the default standard deviation range of +/-3 is used. If fadepctiles is True, the default percentile range of 0 to 100 is used.
shadec, shadecolor, fadec, fadecolor (color-spec, default: None) – Colors for the different shaded regions. The parent artist color is used by default.
shadez, shadezorder, fadez, fadezorder (float, default: 1.5) – The “zorder” for the different shaded regions.
shadea, shadealpha, fadea, fadealpha (float, default: 0.4, 0.2) – The opacity for the different shaded regions.
shadelw, shadelinewidth, fadelw, fadelinewidth (float, default: rc['patch.linewidth'] = 0.6.) – The edge line width for the shading patches.
shdeec, shadeedgecolor, fadeec, fadeedgecolor (float, default: 'none') – The edge color for the shading patches.
shadelabel, fadelabel (bool or str, optional) – Labels for the shaded regions to be used as separate legend entries. To toggle labels “on” and apply a default label, use e.g. shadelabel=True. To apply a custom label, use e.g. shadelabel='label'. Otherwise, the shading is drawn underneath the line and/or marker in the legend entry.
inbounds (bool, default: rc['axes.inbounds'] = True) – Whether to restrict the default y (x) axis limits to account for only in-bounds data when the x (y) axis limits have been locked. See also rc['axes.inbounds'] and rc['cmap.inbounds'].
label, value (float or str, optional) – The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally used with 1D positional arguments.
labels, values (sequence of float or sequence of str, optional) – The legend labels or colorbar coordinates used for each plotted element. Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to plot().

quiver(**kwargs)[source]

Plot quiver arrows.

Parameters:

*args (u, v or x, y, u, v) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only u and v coordinates are passed, try to infer the x and y coordinates from the DataFrame indices and columns or the DataArray coordinates. Otherwise, the y coordinates are np.arange(0, y.shape[0]) and the x coordinates are np.arange(0, y.shape[1]).
- For pcolor and pcolormesh, calculate coordinate edges using edges or :func:`~ultraplot.utils.edges2d` if centers were provided. For all other methods, calculate coordinate centers if edges were provided.
- If the x or y coordinates are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. If the u and v coordinates are pint.Quantity, pass the magnitude to the plotting command. A pint.Quantity embedded in an xarray.DataArray is also supported.
c, color, colors (array-like or color-spec, optional) – The colors of the quiver arrows passed as either a keyword argument or a fifth positional argument. This can be a single color or a color array to be scaled by cmap and norm.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.
transpose (bool, default: False) – Whether to transpose the input data. This should be used when passing datasets with column-major dimension order (x, y). Otherwise row-major dimension order (y, x) is expected.
order ({'C', 'F'}, default: 'C') – Alternative to transpose. 'C' corresponds to the default C-cyle row-major ordering (equivalent to transpose=False). 'F' corresponds to Fortran-style column-major ordering (equivalent to transpose=True).
globe (bool, default: False) – For ultraplot.axes.GeoAxes only. Whether to enforce global coverage. When set to True this does the following:
1. Interpolates input data to the North and South poles by setting the data values at the poles to the mean from latitudes nearest each pole.
2. Makes meridional coverage “circular”, i.e. the last longitude coordinate equals the first longitude coordinate plus 360°.
3. When basemap is the backend, cycles 1D longitude vectors to fit within the map edges. For example, if the central longitude is 90°, the data is shifted so that it spans -90° to 270°.

Other Parameters:

cmap (colormap-spec, default: rc['cmap.sequential'] = 'Fire' or rc['cmap.diverging'] = 'BuRd') – The colormap specifer, passed to the Colormap constructor function. If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then rc['cmap.diverging'] is used. Otherwise rc['cmap.sequential'] is used.
cmap_kw (dict-like, optional) – Passed to Colormap.
c, color, colors (color-spec or sequence of color-spec, optional) – The color(s) used to create a DiscreteColormap. If not passed, cmap is used.
norm (norm-spec, default: Normalize or DivergingNorm) – The data value normalizer, passed to the Norm constructor function. If discrete is True then 1) this affects the default level-generation algorithm (e.g. norm='log' builds levels in log-space) and 2) this is passed to DiscreteNorm to scale the colors before they are discretized (if norm is not already a DiscreteNorm). If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then DivergingNorm is used. Otherwise Normalize is used.
norm_kw (dict-like, optional) – Passed to Norm.
extend ({'neither', 'both', 'min', 'max'}, default: 'neither') – Direction for drawing colorbar “extensions” indicating out-of-bounds data on the end of the colorbar.
discrete (bool, default: rc['cmap.discrete'] = None) – If False, then DiscreteNorm is not applied to the colormap. Instead, for non-contour plots, the number of levels will be roughly controlled by rc['cmap.lut']. This has a similar effect to using levels=large_number but it may improve rendering speed. Default is True only for contouring commands like contourf and pseudocolor commands like pcolor.
sequential, diverging, cyclic, qualitative (bool, default: None) – Boolean arguments used if cmap is not passed. Set these to True to use the default rc['cmap.sequential'], rc['cmap.diverging'], rc['cmap.cyclic'], and rc['cmap.qualitative'] colormaps. The diverging option also applies DivergingNorm as the default continuous normalizer.
vmin, vmax (float, optional) – The minimum and maximum color scale values used with the norm normalizer. If discrete is False these are the absolute limits, and if discrete is True these are the approximate limits used to automatically determine levels or values lists at “nice” intervals. If levels or values were already passed as lists, these are ignored, and vmin and vmax are set to the minimum and maximum of the lists. If robust was passed, the default vmin and vmax are some percentile range of the data values. Otherwise, the default vmin and vmax are the minimum and maximum of the data values.
N – Shorthand for levels.
levels (int or sequence of float, default: rc['cmap.levels'] = 11) – The number of level edges or a sequence of level edges. If the former, locator is used to generate this many level edges at “nice” intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing levels fail with contour plots).
values (int or sequence of float, default: None) – The number of level centers or a sequence of level centers. If the former, locator is used to generate this many level centers at “nice” intervals. If the latter, levels are inferred using edges. This will override any levels input.
center_levels (bool, default False) – If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented.
robust (bool, float, or 2-tuple, default: rc['cmap.robust'] = False) – If True and vmin or vmax were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, 90 corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers.
inbounds (bool, default: rc['cmap.inbounds'] = True) – If True and vmin or vmax were not provided, when axis limits have been explicitly restricted with set_xlim() or set_ylim(), out-of-bounds data is ignored. See also rc['cmap.inbounds'] and rc['axes.inbounds'].
locator (locator-spec, default: matplotlib.ticker.MaxNLocator) – The locator used to determine level locations if levels or values were not already passed as lists. Passed to the Locator constructor. Default is MaxNLocator with levels integer levels.
locator_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Locator class.
symmetric (bool, default: False) – If True, the normalization range or discrete colormap levels are symmetric about zero.
positive (bool, default: False) – If True, the normalization range or discrete colormap levels are positive with a minimum at zero.
negative (bool, default: False) – If True, the normaliation range or discrete colormap levels are negative with a minimum at zero.
nozero (bool, default: False) – If True, 0 is removed from the level list. This is mainly useful for single-color contour plots.
**kwargs – Passed to matplotlib.axes.Axes.quiver

ridgeline(data, **kwargs)[source]

Create a vertical ridgeline plot (also known as a joyplot).

Ridgeline plots visualize distributions of multiple datasets as stacked, overlapping density curves. They are useful for comparing distributions across categories or over time.

Parameters:

data (list of array-like) – List of distributions to plot. Each element should be an array-like object containing the data points for one distribution.
labels (list of str, optional) – Labels for each distribution. If not provided, generates default labels.
positions (array-like, optional) – Y-coordinates for positioning each ridge. If provided, enables continuous (coordinate-based) positioning mode where ridges are anchored to specific numerical coordinates along the Y-axis. If None (default), uses categorical positioning with evenly-spaced ridges.
height (float or array-like, optional) – Height of each ridge in Y-axis units. Only used in continuous positioning mode (when positions is provided). Can be a single value applied to all ridges or an array of values (one per ridge). If None, defaults to the minimum spacing between positions divided by 2.
overlap (float, default: 0.5) – Amount of overlap between ridges, from 0 (no overlap) to 1 (full overlap). Higher values create more dramatic visual overlapping. Only used in categorical positioning mode (when positions is None).
kde_kw (dict, optional) – Keyword arguments passed to scipy.stats.gaussian_kde. Common parameters include:
- bw_method : Bandwidth selection method (scalar, ‘scott’, ‘silverman’, or callable)
- weights : Array of weights for each data point
Only used when hist=False.
points (int, default: 200) – Number of evaluation points for KDE curves. Higher values create smoother curves but take longer to compute. Only used when hist=False.
hist (bool, default: False) – If True, uses histograms instead of kernel density estimation.
bins (int or sequence or str, default: 'auto') – Bin specification for histograms. Can be an integer (number of bins), a sequence defining bin edges, or a string method (‘auto’, ‘sturges’, etc.). Only used when hist=True.
fill (bool, default: True) – Whether to fill the area under each density curve.
alpha (float, default: 0.7) – Transparency level for filled areas (0=transparent, 1=opaque).
linewidth (float, default: 1.5) – Width of the outline for each ridge.
edgecolor (color, default: 'black') – Color of the ridge outlines.
facecolor (color or list of colors, optional) – Fill color(s) for the ridges. If a single color, applies to all ridges. If a list, must match the number of distributions. If None, uses the current color cycle or colormap.
cmap (str or Colormap, optional) – Colormap name or object to use for coloring ridges. Overridden by facecolor.

Returns:

list – List of artist objects for each ridge (PolyCollection or Line2D).

Examples

>>> import ultraplot as uplt
>>> import numpy as np
>>> fig, ax = uplt.subplots()
>>> data = [np.random.normal(i, 1, 1000) for i in range(5)]
>>> ax.ridgeline(data, labels=[f'Group {i+1}' for i in range(5)])

>>> # With colormap
>>> fig, ax = uplt.subplots()
>>> ax.ridgeline(data, cmap='viridis', overlap=0.7)

>>> # With histograms instead of KDE
>>> fig, ax = uplt.subplots()
>>> ax.ridgeline(data, hist=True, bins=20)

>>> # Continuous positioning (e.g., at specific depths)
>>> fig, ax = uplt.subplots()
>>> depths = [0, 10, 25, 50, 100]  # meters
>>> ax.ridgeline(data, positions=depths, height=8, labels=['Surface', '10m', '25m', '50m', '100m'])
>>> ax.format(ylabel='Depth (m)', xlabel='Temperature (°C)')

See also

violinplot: Violin plots for distribution visualization
hist: Histogram for single distribution

ridgelineh(data, **kwargs)[source]

Create a horizontal ridgeline plot (also known as a joyplot).

Ridgeline plots visualize distributions of multiple datasets as stacked, overlapping density curves. They are useful for comparing distributions across categories or over time.

Parameters:

data (list of array-like) – List of distributions to plot. Each element should be an array-like object containing the data points for one distribution.
labels (list of str, optional) – Labels for each distribution. If not provided, generates default labels.
positions (array-like, optional) – Y-coordinates for positioning each ridge. If provided, enables continuous (coordinate-based) positioning mode where ridges are anchored to specific numerical coordinates along the Y-axis. If None (default), uses categorical positioning with evenly-spaced ridges.
height (float or array-like, optional) – Height of each ridge in Y-axis units. Only used in continuous positioning mode (when positions is provided). Can be a single value applied to all ridges or an array of values (one per ridge). If None, defaults to the minimum spacing between positions divided by 2.
overlap (float, default: 0.5) – Amount of overlap between ridges, from 0 (no overlap) to 1 (full overlap). Higher values create more dramatic visual overlapping. Only used in categorical positioning mode (when positions is None).
kde_kw (dict, optional) – Keyword arguments passed to scipy.stats.gaussian_kde. Common parameters include:
- bw_method : Bandwidth selection method (scalar, ‘scott’, ‘silverman’, or callable)
- weights : Array of weights for each data point
Only used when hist=False.
points (int, default: 200) – Number of evaluation points for KDE curves. Higher values create smoother curves but take longer to compute. Only used when hist=False.
hist (bool, default: False) – If True, uses histograms instead of kernel density estimation.
bins (int or sequence or str, default: 'auto') – Bin specification for histograms. Can be an integer (number of bins), a sequence defining bin edges, or a string method (‘auto’, ‘sturges’, etc.). Only used when hist=True.
fill (bool, default: True) – Whether to fill the area under each density curve.
alpha (float, default: 0.7) – Transparency level for filled areas (0=transparent, 1=opaque).
linewidth (float, default: 1.5) – Width of the outline for each ridge.
edgecolor (color, default: 'black') – Color of the ridge outlines.
facecolor (color or list of colors, optional) – Fill color(s) for the ridges. If a single color, applies to all ridges. If a list, must match the number of distributions. If None, uses the current color cycle or colormap.
cmap (str or Colormap, optional) – Colormap name or object to use for coloring ridges. Overridden by facecolor.

Returns:

list – List of artist objects for each ridge (PolyCollection or Line2D).

Examples

>>> import ultraplot as uplt
>>> import numpy as np
>>> fig, ax = uplt.subplots()
>>> data = [np.random.normal(i, 1, 1000) for i in range(5)]
>>> ax.ridgeline(data, labels=[f'Group {i+1}' for i in range(5)])

>>> # With colormap
>>> fig, ax = uplt.subplots()
>>> ax.ridgeline(data, cmap='viridis', overlap=0.7)

>>> # With histograms instead of KDE
>>> fig, ax = uplt.subplots()
>>> ax.ridgeline(data, hist=True, bins=20)

>>> # Continuous positioning (e.g., at specific depths)
>>> fig, ax = uplt.subplots()
>>> depths = [0, 10, 25, 50, 100]  # meters
>>> ax.ridgeline(data, positions=depths, height=8, labels=['Surface', '10m', '25m', '50m', '100m'])
>>> ax.format(ylabel='Depth (m)', xlabel='Temperature (°C)')

See also

violinplot: Violin plots for distribution visualization
hist: Histogram for single distribution

scatter(**kwargs)[source]

Plot markers with flexible keyword arguments.

Parameters:

*args (y or x, y) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only y coordinates are passed, try to infer the x coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the x coordinates are np.arange(0, y.shape[0]).
- If the y coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with boxplot, violinplot, or when using means=True or medians=True).
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
s, size, ms, markersize (float or array-like or unit-spec, optional) – The marker size area(s). If this is an array matching the shape of x and y, the units are scaled by smin and smax. If this contains unit string(s), it is processed by units and represents the width rather than area.
c, color, colors, mc, markercolor, markercolors, fc, facecolor, facecolors (array-like or color-spec, optional) – The marker color(s). If this is an array matching the shape of x and y, the colors are generated using cmap, norm, vmin, and vmax. Otherwise, this should be a valid matplotlib color.
smin, smax (float, optional) – The minimum and maximum marker size area in units points ** 2. Ignored if absolute_size is True. Default value for smin is 1 and for smax is the square of rc['lines.markersize'] = 6.0.
area_size (bool, default: True) – Whether the marker sizes s are scaled by area or by radius. The default True is consistent with matplotlib. When absolute_size is True, the s units are points ** 2 if area_size is True and points if area_size is False.
absolute_size (bool, default: True or False) – Whether s should be taken to represent “absolute” marker sizes in units points or points ** 2 or “relative” marker sizes scaled by smin and smax. Default is True if s is scalar and False if s is array-like or smin or smax were passed.
vmin, vmax (float, optional) – The minimum and maximum color scale values used with the norm normalizer. If discrete is False these are the absolute limits, and if discrete is True these are the approximate limits used to automatically determine levels or values lists at “nice” intervals. If levels or values were already passed as lists, these are ignored, and vmin and vmax are set to the minimum and maximum of the lists. If robust was passed, the default vmin and vmax are some percentile range of the data values. Otherwise, the default vmin and vmax are the minimum and maximum of the data values.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

cmap (colormap-spec, default: rc['cmap.sequential'] = 'Fire' or rc['cmap.diverging'] = 'BuRd') – The colormap specifer, passed to the Colormap constructor function. If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then rc['cmap.diverging'] is used. Otherwise rc['cmap.sequential'] is used.
cmap_kw (dict-like, optional) – Passed to Colormap.
c, color, colors (color-spec or sequence of color-spec, optional) – The color(s) used to create a DiscreteColormap. If not passed, cmap is used.
norm (norm-spec, default: Normalize or DivergingNorm) – The data value normalizer, passed to the Norm constructor function. If discrete is True then 1) this affects the default level-generation algorithm (e.g. norm='log' builds levels in log-space) and 2) this is passed to DiscreteNorm to scale the colors before they are discretized (if norm is not already a DiscreteNorm). If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then DivergingNorm is used. Otherwise Normalize is used.
norm_kw (dict-like, optional) – Passed to Norm.
extend ({'neither', 'both', 'min', 'max'}, default: 'neither') – Direction for drawing colorbar “extensions” indicating out-of-bounds data on the end of the colorbar.
discrete (bool, default: rc['cmap.discrete'] = None) – If False, then DiscreteNorm is not applied to the colormap. Instead, for non-contour plots, the number of levels will be roughly controlled by rc['cmap.lut']. This has a similar effect to using levels=large_number but it may improve rendering speed. Default is True only for contouring commands like contourf and pseudocolor commands like pcolor.
sequential, diverging, cyclic, qualitative (bool, default: None) – Boolean arguments used if cmap is not passed. Set these to True to use the default rc['cmap.sequential'], rc['cmap.diverging'], rc['cmap.cyclic'], and rc['cmap.qualitative'] colormaps. The diverging option also applies DivergingNorm as the default continuous normalizer.
N – Shorthand for levels.
levels (int or sequence of float, default: rc['cmap.levels'] = 11) – The number of level edges or a sequence of level edges. If the former, locator is used to generate this many level edges at “nice” intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing levels fail with contour plots).
values (int or sequence of float, default: None) – The number of level centers or a sequence of level centers. If the former, locator is used to generate this many level centers at “nice” intervals. If the latter, levels are inferred using edges. This will override any levels input.
center_levels (bool, default False) – If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented.
robust (bool, float, or 2-tuple, default: rc['cmap.robust'] = False) – If True and vmin or vmax were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, 90 corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers.
inbounds (bool, default: rc['cmap.inbounds'] = True) – If True and vmin or vmax were not provided, when axis limits have been explicitly restricted with set_xlim() or set_ylim(), out-of-bounds data is ignored. See also rc['cmap.inbounds'] and rc['axes.inbounds'].
locator (locator-spec, default: matplotlib.ticker.MaxNLocator) – The locator used to determine level locations if levels or values were not already passed as lists. Passed to the Locator constructor. Default is MaxNLocator with levels integer levels.
locator_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Locator class.
symmetric (bool, default: False) – If True, the normalization range or discrete colormap levels are symmetric about zero.
positive (bool, default: False) – If True, the normalization range or discrete colormap levels are positive with a minimum at zero.
negative (bool, default: False) – If True, the normaliation range or discrete colormap levels are negative with a minimum at zero.
nozero (bool, default: False) – If True, 0 is removed from the level list. This is mainly useful for single-color contour plots.
cycle (cycle-spec, optional) – The cycle specifer, passed to the Cycle constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use cycle=False, cycle='none', or cycle=() (analogous to disabling ticks with e.g. xformatter='none'). To restore the default property cycler, use cycle=True.
cycle_kw (dict-like, optional) – Passed to Cycle.
lw, linewidth, linewidths, mew, markeredgewidth, markeredgewidths (float or sequence, optional) – The marker edge width(s).
edgecolors, markeredgecolor, markeredgecolors (color-spec or sequence, optional) – The marker edge color(s).
mean, means (bool, default: False) – Whether to plot the means of each column for 2D y coordinates. Means are calculated with numpy.nanmean. If no other arguments are specified, this also sets barstd=True (and boxstd=True for violin plots).
median, medians (bool, default: False) – Whether to plot the medians of each column for 2D y coordinates. Medians are calculated with numpy.nanmedian. If no other arguments arguments are specified, this also sets barstd=True (and boxstd=True for violin plots).
bars (bool, default: None) – Shorthand for barstd, barstds.
barstd, barstds (bool, float, or 2-tuple of float, optional) – Valid only if mean or median is True. Standard deviation multiples for thin error bars with optional whiskers (i.e., caps). If scalar, then +/- that multiple is used. If True, the default standard deviation range of +/-3 is used.
barpctile, barpctiles (bool, float, or 2-tuple of float, optional) – Valid only if mean or median is True. As with barstd, but instead using percentiles for the error bars. If scalar, that percentile range is used (e.g., 90 shows the 5th to 95th percentiles). If True, the default percentile range of 0 to 100 is used.
bardata (array-like, optional) – Valid only if mean and median are False. If shape is 2 x N, these are the lower and upper bounds for the thin error bars. If shape is N, these are the absolute, symmetric deviations from the central points.
boxes (bool, default: None) – Shorthand for boxstd, boxstds.
boxstd, boxstds, boxpctile, boxpctiles, boxdata (optional) – As with barstd, barpctile, and bardata, but for thicker error bars representing a smaller interval than the thin error bars. If boxstds is True, the default standard deviation range of +/-1 is used. If boxpctiles is True, the default percentile range of 25 to 75 is used (i.e., the interquartile range). When “boxes” and “bars” are combined, this has the effect of drawing miniature box-and-whisker plots.
capsize (float, default: rc['errorbar.capsize'] = 3.0) – The cap size for thin error bars in points.
barz, barzorder, boxz, boxzorder (float, default: 2.5) – The “zorder” for the thin and thick error bars.
barc, barcolor, boxc, boxcolor (color-spec, default: rc['boxplot.whiskerprops.color'] = 'black') – Colors for the thin and thick error bars.
barlw, barlinewidth, boxlw, boxlinewidth (float, default: rc['boxplot.whiskerprops.linewidth'] = 1.0) – Line widths for the thin and thick error bars, in points. The default for boxes is 4 times rc['boxplot.whiskerprops.linewidth'].
boxm, boxmarker (bool or marker-spec, default: 'o') – Whether to draw a small marker in the middle of the box denoting the mean or median position. Ignored if boxes is False.
boxms, boxmarkersize (size-spec, default: (2 * boxlinewidth) ** 2) – The marker size for the boxmarker marker in points ** 2.
boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor (color-spec, default: 'w') – Color, face color, and edge color for the boxmarker marker.
shade (bool, default: None) – Shorthand for shadestd.
shadestd, shadestds, shadepctile, shadepctiles, shadedata (optional) – As with barstd, barpctile, and bardata, but using shading to indicate the error range. If shadestds is True, the default standard deviation range of +/-2 is used. If shadepctiles is True, the default percentile range of 10 to 90 is used.
fade (bool, default: None) – Shorthand for fadestd.
fadestd, fadestds, fadepctile, fadepctiles, fadedata (optional) – As with shadestd, shadepctile, and shadedata, but for an additional, more faded, secondary shaded region. If fadestds is True, the default standard deviation range of +/-3 is used. If fadepctiles is True, the default percentile range of 0 to 100 is used.
shadec, shadecolor, fadec, fadecolor (color-spec, default: None) – Colors for the different shaded regions. The parent artist color is used by default.
shadez, shadezorder, fadez, fadezorder (float, default: 1.5) – The “zorder” for the different shaded regions.
shadea, shadealpha, fadea, fadealpha (float, default: 0.4, 0.2) – The opacity for the different shaded regions.
shadelw, shadelinewidth, fadelw, fadelinewidth (float, default: rc['patch.linewidth'] = 0.6.) – The edge line width for the shading patches.
shdeec, shadeedgecolor, fadeec, fadeedgecolor (float, default: 'none') – The edge color for the shading patches.
shadelabel, fadelabel (bool or str, optional) – Labels for the shaded regions to be used as separate legend entries. To toggle labels “on” and apply a default label, use e.g. shadelabel=True. To apply a custom label, use e.g. shadelabel='label'. Otherwise, the shading is drawn underneath the line and/or marker in the legend entry.
inbounds (bool, default: rc['axes.inbounds'] = True) – Whether to restrict the default y (x) axis limits to account for only in-bounds data when the x (y) axis limits have been locked. See also rc['axes.inbounds'] and rc['cmap.inbounds'].
label, value (float or str, optional) – The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally used with 1D positional arguments.
labels, values (sequence of float or sequence of str, optional) – The legend labels or colorbar coordinates used for each plotted element. Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to scatter.

scatterx(*args, **kwargs)[source]

Plot markers with flexible keyword arguments.

Parameters:

*args (x or y, x) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only x coordinates are passed, try to infer the y coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the y coordinates are np.arange(0, x.shape[0]).
- If the x coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with boxplot, violinplot, or when using means=True or medians=True).
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
s, size, ms, markersize (float or array-like or unit-spec, optional) – The marker size area(s). If this is an array matching the shape of x and y, the units are scaled by smin and smax. If this contains unit string(s), it is processed by units and represents the width rather than area.
c, color, colors, mc, markercolor, markercolors, fc, facecolor, facecolors (array-like or color-spec, optional) – The marker color(s). If this is an array matching the shape of x and y, the colors are generated using cmap, norm, vmin, and vmax. Otherwise, this should be a valid matplotlib color.
smin, smax (float, optional) – The minimum and maximum marker size area in units points ** 2. Ignored if absolute_size is True. Default value for smin is 1 and for smax is the square of rc['lines.markersize'] = 6.0.
area_size (bool, default: True) – Whether the marker sizes s are scaled by area or by radius. The default True is consistent with matplotlib. When absolute_size is True, the s units are points ** 2 if area_size is True and points if area_size is False.
absolute_size (bool, default: True or False) – Whether s should be taken to represent “absolute” marker sizes in units points or points ** 2 or “relative” marker sizes scaled by smin and smax. Default is True if s is scalar and False if s is array-like or smin or smax were passed.
vmin, vmax (float, optional) – The minimum and maximum color scale values used with the norm normalizer. If discrete is False these are the absolute limits, and if discrete is True these are the approximate limits used to automatically determine levels or values lists at “nice” intervals. If levels or values were already passed as lists, these are ignored, and vmin and vmax are set to the minimum and maximum of the lists. If robust was passed, the default vmin and vmax are some percentile range of the data values. Otherwise, the default vmin and vmax are the minimum and maximum of the data values.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

cmap (colormap-spec, default: rc['cmap.sequential'] = 'Fire' or rc['cmap.diverging'] = 'BuRd') – The colormap specifer, passed to the Colormap constructor function. If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then rc['cmap.diverging'] is used. Otherwise rc['cmap.sequential'] is used.
cmap_kw (dict-like, optional) – Passed to Colormap.
c, color, colors (color-spec or sequence of color-spec, optional) – The color(s) used to create a DiscreteColormap. If not passed, cmap is used.
norm (norm-spec, default: Normalize or DivergingNorm) – The data value normalizer, passed to the Norm constructor function. If discrete is True then 1) this affects the default level-generation algorithm (e.g. norm='log' builds levels in log-space) and 2) this is passed to DiscreteNorm to scale the colors before they are discretized (if norm is not already a DiscreteNorm). If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then DivergingNorm is used. Otherwise Normalize is used.
norm_kw (dict-like, optional) – Passed to Norm.
extend ({'neither', 'both', 'min', 'max'}, default: 'neither') – Direction for drawing colorbar “extensions” indicating out-of-bounds data on the end of the colorbar.
discrete (bool, default: rc['cmap.discrete'] = None) – If False, then DiscreteNorm is not applied to the colormap. Instead, for non-contour plots, the number of levels will be roughly controlled by rc['cmap.lut']. This has a similar effect to using levels=large_number but it may improve rendering speed. Default is True only for contouring commands like contourf and pseudocolor commands like pcolor.
sequential, diverging, cyclic, qualitative (bool, default: None) – Boolean arguments used if cmap is not passed. Set these to True to use the default rc['cmap.sequential'], rc['cmap.diverging'], rc['cmap.cyclic'], and rc['cmap.qualitative'] colormaps. The diverging option also applies DivergingNorm as the default continuous normalizer.
N – Shorthand for levels.
levels (int or sequence of float, default: rc['cmap.levels'] = 11) – The number of level edges or a sequence of level edges. If the former, locator is used to generate this many level edges at “nice” intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing levels fail with contour plots).
values (int or sequence of float, default: None) – The number of level centers or a sequence of level centers. If the former, locator is used to generate this many level centers at “nice” intervals. If the latter, levels are inferred using edges. This will override any levels input.
center_levels (bool, default False) – If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented.
robust (bool, float, or 2-tuple, default: rc['cmap.robust'] = False) – If True and vmin or vmax were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, 90 corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers.
inbounds (bool, default: rc['cmap.inbounds'] = True) – If True and vmin or vmax were not provided, when axis limits have been explicitly restricted with set_xlim() or set_ylim(), out-of-bounds data is ignored. See also rc['cmap.inbounds'] and rc['axes.inbounds'].
locator (locator-spec, default: matplotlib.ticker.MaxNLocator) – The locator used to determine level locations if levels or values were not already passed as lists. Passed to the Locator constructor. Default is MaxNLocator with levels integer levels.
locator_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Locator class.
symmetric (bool, default: False) – If True, the normalization range or discrete colormap levels are symmetric about zero.
positive (bool, default: False) – If True, the normalization range or discrete colormap levels are positive with a minimum at zero.
negative (bool, default: False) – If True, the normaliation range or discrete colormap levels are negative with a minimum at zero.
nozero (bool, default: False) – If True, 0 is removed from the level list. This is mainly useful for single-color contour plots.
cycle (cycle-spec, optional) – The cycle specifer, passed to the Cycle constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use cycle=False, cycle='none', or cycle=() (analogous to disabling ticks with e.g. xformatter='none'). To restore the default property cycler, use cycle=True.
cycle_kw (dict-like, optional) – Passed to Cycle.
lw, linewidth, linewidths, mew, markeredgewidth, markeredgewidths (float or sequence, optional) – The marker edge width(s).
edgecolors, markeredgecolor, markeredgecolors (color-spec or sequence, optional) – The marker edge color(s).
mean, means (bool, default: False) – Whether to plot the means of each column for 2D x coordinates. Means are calculated with numpy.nanmean. If no other arguments are specified, this also sets barstd=True (and boxstd=True for violin plots).
median, medians (bool, default: False) – Whether to plot the medians of each column for 2D x coordinates. Medians are calculated with numpy.nanmedian. If no other arguments arguments are specified, this also sets barstd=True (and boxstd=True for violin plots).
bars (bool, default: None) – Shorthand for barstd, barstds.
barstd, barstds (bool, float, or 2-tuple of float, optional) – Valid only if mean or median is True. Standard deviation multiples for thin error bars with optional whiskers (i.e., caps). If scalar, then +/- that multiple is used. If True, the default standard deviation range of +/-3 is used.
barpctile, barpctiles (bool, float, or 2-tuple of float, optional) – Valid only if mean or median is True. As with barstd, but instead using percentiles for the error bars. If scalar, that percentile range is used (e.g., 90 shows the 5th to 95th percentiles). If True, the default percentile range of 0 to 100 is used.
bardata (array-like, optional) – Valid only if mean and median are False. If shape is 2 x N, these are the lower and upper bounds for the thin error bars. If shape is N, these are the absolute, symmetric deviations from the central points.
boxes (bool, default: None) – Shorthand for boxstd, boxstds.
boxstd, boxstds, boxpctile, boxpctiles, boxdata (optional) – As with barstd, barpctile, and bardata, but for thicker error bars representing a smaller interval than the thin error bars. If boxstds is True, the default standard deviation range of +/-1 is used. If boxpctiles is True, the default percentile range of 25 to 75 is used (i.e., the interquartile range). When “boxes” and “bars” are combined, this has the effect of drawing miniature box-and-whisker plots.
capsize (float, default: rc['errorbar.capsize'] = 3.0) – The cap size for thin error bars in points.
barz, barzorder, boxz, boxzorder (float, default: 2.5) – The “zorder” for the thin and thick error bars.
barc, barcolor, boxc, boxcolor (color-spec, default: rc['boxplot.whiskerprops.color'] = 'black') – Colors for the thin and thick error bars.
barlw, barlinewidth, boxlw, boxlinewidth (float, default: rc['boxplot.whiskerprops.linewidth'] = 1.0) – Line widths for the thin and thick error bars, in points. The default for boxes is 4 times rc['boxplot.whiskerprops.linewidth'].
boxm, boxmarker (bool or marker-spec, default: 'o') – Whether to draw a small marker in the middle of the box denoting the mean or median position. Ignored if boxes is False.
boxms, boxmarkersize (size-spec, default: (2 * boxlinewidth) ** 2) – The marker size for the boxmarker marker in points ** 2.
boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor (color-spec, default: 'w') – Color, face color, and edge color for the boxmarker marker.
shade (bool, default: None) – Shorthand for shadestd.
shadestd, shadestds, shadepctile, shadepctiles, shadedata (optional) – As with barstd, barpctile, and bardata, but using shading to indicate the error range. If shadestds is True, the default standard deviation range of +/-2 is used. If shadepctiles is True, the default percentile range of 10 to 90 is used.
fade (bool, default: None) – Shorthand for fadestd.
fadestd, fadestds, fadepctile, fadepctiles, fadedata (optional) – As with shadestd, shadepctile, and shadedata, but for an additional, more faded, secondary shaded region. If fadestds is True, the default standard deviation range of +/-3 is used. If fadepctiles is True, the default percentile range of 0 to 100 is used.
shadec, shadecolor, fadec, fadecolor (color-spec, default: None) – Colors for the different shaded regions. The parent artist color is used by default.
shadez, shadezorder, fadez, fadezorder (float, default: 1.5) – The “zorder” for the different shaded regions.
shadea, shadealpha, fadea, fadealpha (float, default: 0.4, 0.2) – The opacity for the different shaded regions.
shadelw, shadelinewidth, fadelw, fadelinewidth (float, default: rc['patch.linewidth'] = 0.6.) – The edge line width for the shading patches.
shdeec, shadeedgecolor, fadeec, fadeedgecolor (float, default: 'none') – The edge color for the shading patches.
shadelabel, fadelabel (bool or str, optional) – Labels for the shaded regions to be used as separate legend entries. To toggle labels “on” and apply a default label, use e.g. shadelabel=True. To apply a custom label, use e.g. shadelabel='label'. Otherwise, the shading is drawn underneath the line and/or marker in the legend entry.
inbounds (bool, default: rc['axes.inbounds'] = True) – Whether to restrict the default y (x) axis limits to account for only in-bounds data when the x (y) axis limits have been locked. See also rc['axes.inbounds'] and rc['cmap.inbounds'].
label, value (float or str, optional) – The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally used with 1D positional arguments.
labels, values (sequence of float or sequence of str, optional) – The legend labels or colorbar coordinates used for each plotted element. Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to scatter.

semilogx(*args, **kwargs)[source]

Plot semilogx

UltraPlot is optimized for visualizing logarithmic scales by default. For cases with large differences in magnitude, we recommend setting rc["formatter.log"] = True to enhance axis label formatting. Make a plot with log scaling on the x-axis.

Call signatures:

semilogx([x], y, [fmt], data=None, **kwargs)
semilogx([x], y, [fmt], [x2], y2, [fmt2], ..., **kwargs)

This is just a thin wrapper around plot which additionally changes the x-axis to log scaling. All the concepts and parameters of plot can be used here as well.

The additional parameters base, subs, and nonpositive control the x-axis properties. They are just forwarded to Axes.set_xscale.

Parameters:

base (float, default: 10) – Base of the x logarithm.
subs (array-like, optional) – The location of the minor xticks. If None, reasonable locations are automatically chosen depending on the number of decades in the plot. See Axes.set_xscale for details.
nonpositive ({'mask', 'clip'}, default: 'clip') – Non-positive values in x can be masked as invalid, or clipped to a very small positive number.
**kwargs – All parameters supported by plot.

Returns:

list of Line2D – Objects representing the plotted data.

Notes

Note

This is the pyplot wrapper for axes.Axes.semilogx.

semilogy(*args, **kwargs)[source]

Plot semilogy

UltraPlot is optimized for visualizing logarithmic scales by default. For cases with large differences in magnitude, we recommend setting rc["formatter.log"] = True to enhance axis label formatting. Make a plot with log scaling on the y-axis.

Call signatures:

semilogy([x], y, [fmt], data=None, **kwargs)
semilogy([x], y, [fmt], [x2], y2, [fmt2], ..., **kwargs)

This is just a thin wrapper around plot which additionally changes the y-axis to log scaling. All the concepts and parameters of plot can be used here as well.

The additional parameters base, subs, and nonpositive control the y-axis properties. They are just forwarded to Axes.set_yscale.

Parameters:

base (float, default: 10) – Base of the y logarithm.
subs (array-like, optional) – The location of the minor yticks. If None, reasonable locations are automatically chosen depending on the number of decades in the plot. See Axes.set_yscale for details.
nonpositive ({'mask', 'clip'}, default: 'clip') – Non-positive values in y can be masked as invalid, or clipped to a very small positive number.
**kwargs – All parameters supported by plot.

Returns:

list of Line2D – Objects representing the plotted data.

Notes

Note

This is the pyplot wrapper for axes.Axes.semilogy.

set(*, adjustable=<UNSET>, agg_filter=<UNSET>, alpha=<UNSET>, anchor=<UNSET>, animated=<UNSET>, aspect=<UNSET>, autoscale_on=<UNSET>, autoscalex_on=<UNSET>, autoscaley_on=<UNSET>, axes_locator=<UNSET>, axisbelow=<UNSET>, box_aspect=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, external=<UNSET>, facecolor=<UNSET>, forward_navigation_events=<UNSET>, frame_on=<UNSET>, gid=<UNSET>, in_layout=<UNSET>, label=<UNSET>, mouseover=<UNSET>, navigate=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, position=<UNSET>, prop_cycle=<UNSET>, rasterization_zorder=<UNSET>, rasterized=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, subplotspec=<UNSET>, title=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, xbound=<UNSET>, xlabel=<UNSET>, xlim=<UNSET>, xmargin=<UNSET>, xscale=<UNSET>, xticklabels=<UNSET>, xticks=<UNSET>, ybound=<UNSET>, ylabel=<UNSET>, ylim=<UNSET>, ymargin=<UNSET>, yscale=<UNSET>, yticklabels=<UNSET>, yticks=<UNSET>, zorder=<UNSET>)

Set multiple properties at once.

Supported properties are

Property

Description

adjustable

{‘box’, ‘datalim’}

agg_filter

a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image

alpha

float or None

anchor

(float, float) or {‘C’, ‘SW’, ‘S’, ‘SE’, ‘E’, ‘NE’, …}

animated

bool

aspect

{‘auto’, ‘equal’} or float

autoscale_on

bool

autoscalex_on

unknown

autoscaley_on

unknown

axes_locator

Callable[[Axes, Renderer], Bbox]

axisbelow

bool or ‘line’

box_aspect

float or None

clip_box

BboxBase or None

clip_on

bool

clip_path

Patch or (Path, Transform) or None

external

unknown

facecolor or fc

:mpltype:`color`

figure

Figure or SubFigure

forward_navigation_events

bool or “auto”

frame_on

bool

gid

str

in_layout

bool

label

object

mouseover

bool

navigate

bool

navigate_mode

unknown

path_effects

list of AbstractPathEffect

picker

None or bool or float or callable

position

[left, bottom, width, height] or Bbox

prop_cycle

Cycler

rasterization_zorder

float or None

rasterized

bool

sketch_params

(scale: float, length: float, randomness: float)

snap

bool or None

subplotspec

unknown

title

str

transform

Transform

url

str

visible

bool

xbound

(lower: float, upper: float)

xlabel

str

xlim

(left: float, right: float)

xmargin

float greater than -0.5

xscale

unknown

xticklabels

unknown

xticks

unknown

ybound

(lower: float, upper: float)

ylabel

str

ylim

(bottom: float, top: float)

ymargin

float greater than -0.5

yscale

unknown

yticklabels

unknown

yticks

unknown

zorder

float

spy(**kwargs)[source]

Plot a sparcity pattern.

Parameters:

z (array-like) – The data passed as a positional argument or keyword argument.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

cmap (colormap-spec, default: rc['cmap.sequential'] = 'Fire' or rc['cmap.diverging'] = 'BuRd') – The colormap specifer, passed to the Colormap constructor function. If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then rc['cmap.diverging'] is used. Otherwise rc['cmap.sequential'] is used.
cmap_kw (dict-like, optional) – Passed to Colormap.
c, color, colors (color-spec or sequence of color-spec, optional) – The color(s) used to create a DiscreteColormap. If not passed, cmap is used.
norm (norm-spec, default: Normalize or DivergingNorm) – The data value normalizer, passed to the Norm constructor function. If discrete is True then 1) this affects the default level-generation algorithm (e.g. norm='log' builds levels in log-space) and 2) this is passed to DiscreteNorm to scale the colors before they are discretized (if norm is not already a DiscreteNorm). If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then DivergingNorm is used. Otherwise Normalize is used.
norm_kw (dict-like, optional) – Passed to Norm.
extend ({'neither', 'both', 'min', 'max'}, default: 'neither') – Direction for drawing colorbar “extensions” indicating out-of-bounds data on the end of the colorbar.
discrete (bool, default: rc['cmap.discrete'] = None) – If False, then DiscreteNorm is not applied to the colormap. Instead, for non-contour plots, the number of levels will be roughly controlled by rc['cmap.lut']. This has a similar effect to using levels=large_number but it may improve rendering speed. Default is True only for contouring commands like contourf and pseudocolor commands like pcolor.
sequential, diverging, cyclic, qualitative (bool, default: None) – Boolean arguments used if cmap is not passed. Set these to True to use the default rc['cmap.sequential'], rc['cmap.diverging'], rc['cmap.cyclic'], and rc['cmap.qualitative'] colormaps. The diverging option also applies DivergingNorm as the default continuous normalizer.
vmin, vmax (float, optional) – The minimum and maximum color scale values used with the norm normalizer. If discrete is False these are the absolute limits, and if discrete is True these are the approximate limits used to automatically determine levels or values lists at “nice” intervals. If levels or values were already passed as lists, these are ignored, and vmin and vmax are set to the minimum and maximum of the lists. If robust was passed, the default vmin and vmax are some percentile range of the data values. Otherwise, the default vmin and vmax are the minimum and maximum of the data values.
N – Shorthand for levels.
levels (int or sequence of float, default: rc['cmap.levels'] = 11) – The number of level edges or a sequence of level edges. If the former, locator is used to generate this many level edges at “nice” intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing levels fail with contour plots).
values (int or sequence of float, default: None) – The number of level centers or a sequence of level centers. If the former, locator is used to generate this many level centers at “nice” intervals. If the latter, levels are inferred using edges. This will override any levels input.
center_levels (bool, default False) – If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented.
robust (bool, float, or 2-tuple, default: rc['cmap.robust'] = False) – If True and vmin or vmax were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, 90 corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers.
inbounds (bool, default: rc['cmap.inbounds'] = True) – If True and vmin or vmax were not provided, when axis limits have been explicitly restricted with set_xlim() or set_ylim(), out-of-bounds data is ignored. See also rc['cmap.inbounds'] and rc['axes.inbounds'].
locator (locator-spec, default: matplotlib.ticker.MaxNLocator) – The locator used to determine level locations if levels or values were not already passed as lists. Passed to the Locator constructor. Default is MaxNLocator with levels integer levels.
locator_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Locator class.
symmetric (bool, default: False) – If True, the normalization range or discrete colormap levels are symmetric about zero.
positive (bool, default: False) – If True, the normalization range or discrete colormap levels are positive with a minimum at zero.
negative (bool, default: False) – If True, the normaliation range or discrete colormap levels are negative with a minimum at zero.
nozero (bool, default: False) – If True, 0 is removed from the level list. This is mainly useful for single-color contour plots.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to matplotlib.axes.Axes.spy.

stem(**kwargs)[source]

Plot stem lines.

Parameters:

*args (x or y, x) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only x coordinates are passed, try to infer the y coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the y coordinates are np.arange(0, x.shape[0]).
- If the x coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with boxplot, violinplot, or when using means=True or medians=True).
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

cycle (cycle-spec, optional) – The cycle specifer, passed to the Cycle constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use cycle=False, cycle='none', or cycle=() (analogous to disabling ticks with e.g. xformatter='none'). To restore the default property cycler, use cycle=True.
cycle_kw (dict-like, optional) – Passed to Cycle.
inbounds (bool, default: rc['axes.inbounds'] = True) – Whether to restrict the default y (x) axis limits to account for only in-bounds data when the x (y) axis limits have been locked. See also rc['axes.inbounds'] and rc['cmap.inbounds'].
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to stem.

stemx(*args, **kwargs)[source]

Plot stem lines.

Parameters:

*args (x or y, x) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only x coordinates are passed, try to infer the y coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the y coordinates are np.arange(0, x.shape[0]).
- If the x coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with boxplot, violinplot, or when using means=True or medians=True).
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

cycle (cycle-spec, optional) – The cycle specifer, passed to the Cycle constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use cycle=False, cycle='none', or cycle=() (analogous to disabling ticks with e.g. xformatter='none'). To restore the default property cycler, use cycle=True.
cycle_kw (dict-like, optional) – Passed to Cycle.
inbounds (bool, default: rc['axes.inbounds'] = True) – Whether to restrict the default y (x) axis limits to account for only in-bounds data when the x (y) axis limits have been locked. See also rc['axes.inbounds'] and rc['cmap.inbounds'].
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to stem.

step(**kwargs)[source]

Plot step lines.

Parameters:

*args (y or x, y) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only y coordinates are passed, try to infer the x coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the x coordinates are np.arange(0, y.shape[0]).
- If the y coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with boxplot, violinplot, or when using means=True or medians=True).
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

cycle (cycle-spec, optional) – The cycle specifer, passed to the Cycle constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use cycle=False, cycle='none', or cycle=() (analogous to disabling ticks with e.g. xformatter='none'). To restore the default property cycler, use cycle=True.
cycle_kw (dict-like, optional) – Passed to Cycle.
lw, linewidth, linewidths (unit-spec, default: rc['lines.linewidth'] = 1.5) – The width of the line(s). If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: rc['lines.linestyle'] = '-') – The style of the line(s).
c, color, colors (color-spec, optional) – The color of the line(s). The property cycle is used by default.
a, alpha, alphas (float, optional) – The opacity of the line(s). Inferred from color by default.
inbounds (bool, default: rc['axes.inbounds'] = True) – Whether to restrict the default y (x) axis limits to account for only in-bounds data when the x (y) axis limits have been locked. See also rc['axes.inbounds'] and rc['cmap.inbounds'].
label, value (float or str, optional) – The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally used with 1D positional arguments.
labels, values (sequence of float or sequence of str, optional) – The legend labels or colorbar coordinates used for each plotted element. Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to step.

stepx(*args, **kwargs)[source]

Plot step lines.

Parameters:

*args (x or y, x) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only x coordinates are passed, try to infer the y coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the y coordinates are np.arange(0, x.shape[0]).
- If the x coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with boxplot, violinplot, or when using means=True or medians=True).
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

cycle (cycle-spec, optional) – The cycle specifer, passed to the Cycle constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use cycle=False, cycle='none', or cycle=() (analogous to disabling ticks with e.g. xformatter='none'). To restore the default property cycler, use cycle=True.
cycle_kw (dict-like, optional) – Passed to Cycle.
lw, linewidth, linewidths (unit-spec, default: rc['lines.linewidth'] = 1.5) – The width of the line(s). If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: rc['lines.linestyle'] = '-') – The style of the line(s).
c, color, colors (color-spec, optional) – The color of the line(s). The property cycle is used by default.
a, alpha, alphas (float, optional) – The opacity of the line(s). Inferred from color by default.
inbounds (bool, default: rc['axes.inbounds'] = True) – Whether to restrict the default y (x) axis limits to account for only in-bounds data when the x (y) axis limits have been locked. See also rc['axes.inbounds'] and rc['cmap.inbounds'].
label, value (float or str, optional) – The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally used with 1D positional arguments.
labels, values (sequence of float or sequence of str, optional) – The legend labels or colorbar coordinates used for each plotted element. Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to step.

stream(*args, **kwargs)[source]

Plot streamlines.

Parameters:

*args (u, v or x, y, u, v) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only u and v coordinates are passed, try to infer the x and y coordinates from the DataFrame indices and columns or the DataArray coordinates. Otherwise, the y coordinates are np.arange(0, y.shape[0]) and the x coordinates are np.arange(0, y.shape[1]).
- For pcolor and pcolormesh, calculate coordinate edges using edges or :func:`~ultraplot.utils.edges2d` if centers were provided. For all other methods, calculate coordinate centers if edges were provided.
- If the x or y coordinates are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. If the u and v coordinates are pint.Quantity, pass the magnitude to the plotting command. A pint.Quantity embedded in an xarray.DataArray is also supported.
c, color, colors (array-like or color-spec, optional) – The colors of the streamlines passed as either a keyword argument or a fifth positional argument. This can be a single color or a color array to be scaled by cmap and norm.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.
transpose (bool, default: False) – Whether to transpose the input data. This should be used when passing datasets with column-major dimension order (x, y). Otherwise row-major dimension order (y, x) is expected.
order ({'C', 'F'}, default: 'C') – Alternative to transpose. 'C' corresponds to the default C-cyle row-major ordering (equivalent to transpose=False). 'F' corresponds to Fortran-style column-major ordering (equivalent to transpose=True).
globe (bool, default: False) – For ultraplot.axes.GeoAxes only. Whether to enforce global coverage. When set to True this does the following:
1. Interpolates input data to the North and South poles by setting the data values at the poles to the mean from latitudes nearest each pole.
2. Makes meridional coverage “circular”, i.e. the last longitude coordinate equals the first longitude coordinate plus 360°.
3. When basemap is the backend, cycles 1D longitude vectors to fit within the map edges. For example, if the central longitude is 90°, the data is shifted so that it spans -90° to 270°.

Other Parameters:

cmap (colormap-spec, default: rc['cmap.sequential'] = 'Fire' or rc['cmap.diverging'] = 'BuRd') – The colormap specifer, passed to the Colormap constructor function. If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then rc['cmap.diverging'] is used. Otherwise rc['cmap.sequential'] is used.
cmap_kw (dict-like, optional) – Passed to Colormap.
c, color, colors (color-spec or sequence of color-spec, optional) – The color(s) used to create a DiscreteColormap. If not passed, cmap is used.
norm (norm-spec, default: Normalize or DivergingNorm) – The data value normalizer, passed to the Norm constructor function. If discrete is True then 1) this affects the default level-generation algorithm (e.g. norm='log' builds levels in log-space) and 2) this is passed to DiscreteNorm to scale the colors before they are discretized (if norm is not already a DiscreteNorm). If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then DivergingNorm is used. Otherwise Normalize is used.
norm_kw (dict-like, optional) – Passed to Norm.
extend ({'neither', 'both', 'min', 'max'}, default: 'neither') – Direction for drawing colorbar “extensions” indicating out-of-bounds data on the end of the colorbar.
discrete (bool, default: rc['cmap.discrete'] = None) – If False, then DiscreteNorm is not applied to the colormap. Instead, for non-contour plots, the number of levels will be roughly controlled by rc['cmap.lut']. This has a similar effect to using levels=large_number but it may improve rendering speed. Default is True only for contouring commands like contourf and pseudocolor commands like pcolor.
sequential, diverging, cyclic, qualitative (bool, default: None) – Boolean arguments used if cmap is not passed. Set these to True to use the default rc['cmap.sequential'], rc['cmap.diverging'], rc['cmap.cyclic'], and rc['cmap.qualitative'] colormaps. The diverging option also applies DivergingNorm as the default continuous normalizer.
vmin, vmax (float, optional) – The minimum and maximum color scale values used with the norm normalizer. If discrete is False these are the absolute limits, and if discrete is True these are the approximate limits used to automatically determine levels or values lists at “nice” intervals. If levels or values were already passed as lists, these are ignored, and vmin and vmax are set to the minimum and maximum of the lists. If robust was passed, the default vmin and vmax are some percentile range of the data values. Otherwise, the default vmin and vmax are the minimum and maximum of the data values.
N – Shorthand for levels.
levels (int or sequence of float, default: rc['cmap.levels'] = 11) – The number of level edges or a sequence of level edges. If the former, locator is used to generate this many level edges at “nice” intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing levels fail with contour plots).
values (int or sequence of float, default: None) – The number of level centers or a sequence of level centers. If the former, locator is used to generate this many level centers at “nice” intervals. If the latter, levels are inferred using edges. This will override any levels input.
center_levels (bool, default False) – If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented.
robust (bool, float, or 2-tuple, default: rc['cmap.robust'] = False) – If True and vmin or vmax were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, 90 corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers.
inbounds (bool, default: rc['cmap.inbounds'] = True) – If True and vmin or vmax were not provided, when axis limits have been explicitly restricted with set_xlim() or set_ylim(), out-of-bounds data is ignored. See also rc['cmap.inbounds'] and rc['axes.inbounds'].
locator (locator-spec, default: matplotlib.ticker.MaxNLocator) – The locator used to determine level locations if levels or values were not already passed as lists. Passed to the Locator constructor. Default is MaxNLocator with levels integer levels.
locator_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Locator class.
symmetric (bool, default: False) – If True, the normalization range or discrete colormap levels are symmetric about zero.
positive (bool, default: False) – If True, the normalization range or discrete colormap levels are positive with a minimum at zero.
negative (bool, default: False) – If True, the normaliation range or discrete colormap levels are negative with a minimum at zero.
nozero (bool, default: False) – If True, 0 is removed from the level list. This is mainly useful for single-color contour plots.
**kwargs – Passed to matplotlib.axes.Axes.streamplot

streamplot(**kwargs)[source]

Plot streamlines.

Parameters:

*args (u, v or x, y, u, v) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only u and v coordinates are passed, try to infer the x and y coordinates from the DataFrame indices and columns or the DataArray coordinates. Otherwise, the y coordinates are np.arange(0, y.shape[0]) and the x coordinates are np.arange(0, y.shape[1]).
- For pcolor and pcolormesh, calculate coordinate edges using edges or :func:`~ultraplot.utils.edges2d` if centers were provided. For all other methods, calculate coordinate centers if edges were provided.
- If the x or y coordinates are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. If the u and v coordinates are pint.Quantity, pass the magnitude to the plotting command. A pint.Quantity embedded in an xarray.DataArray is also supported.
c, color, colors (array-like or color-spec, optional) – The colors of the streamlines passed as either a keyword argument or a fifth positional argument. This can be a single color or a color array to be scaled by cmap and norm.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.
transpose (bool, default: False) – Whether to transpose the input data. This should be used when passing datasets with column-major dimension order (x, y). Otherwise row-major dimension order (y, x) is expected.
order ({'C', 'F'}, default: 'C') – Alternative to transpose. 'C' corresponds to the default C-cyle row-major ordering (equivalent to transpose=False). 'F' corresponds to Fortran-style column-major ordering (equivalent to transpose=True).
globe (bool, default: False) – For ultraplot.axes.GeoAxes only. Whether to enforce global coverage. When set to True this does the following:
1. Interpolates input data to the North and South poles by setting the data values at the poles to the mean from latitudes nearest each pole.
2. Makes meridional coverage “circular”, i.e. the last longitude coordinate equals the first longitude coordinate plus 360°.
3. When basemap is the backend, cycles 1D longitude vectors to fit within the map edges. For example, if the central longitude is 90°, the data is shifted so that it spans -90° to 270°.

Other Parameters:

cmap (colormap-spec, default: rc['cmap.sequential'] = 'Fire' or rc['cmap.diverging'] = 'BuRd') – The colormap specifer, passed to the Colormap constructor function. If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then rc['cmap.diverging'] is used. Otherwise rc['cmap.sequential'] is used.
cmap_kw (dict-like, optional) – Passed to Colormap.
c, color, colors (color-spec or sequence of color-spec, optional) – The color(s) used to create a DiscreteColormap. If not passed, cmap is used.
norm (norm-spec, default: Normalize or DivergingNorm) – The data value normalizer, passed to the Norm constructor function. If discrete is True then 1) this affects the default level-generation algorithm (e.g. norm='log' builds levels in log-space) and 2) this is passed to DiscreteNorm to scale the colors before they are discretized (if norm is not already a DiscreteNorm). If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then DivergingNorm is used. Otherwise Normalize is used.
norm_kw (dict-like, optional) – Passed to Norm.
extend ({'neither', 'both', 'min', 'max'}, default: 'neither') – Direction for drawing colorbar “extensions” indicating out-of-bounds data on the end of the colorbar.
discrete (bool, default: rc['cmap.discrete'] = None) – If False, then DiscreteNorm is not applied to the colormap. Instead, for non-contour plots, the number of levels will be roughly controlled by rc['cmap.lut']. This has a similar effect to using levels=large_number but it may improve rendering speed. Default is True only for contouring commands like contourf and pseudocolor commands like pcolor.
sequential, diverging, cyclic, qualitative (bool, default: None) – Boolean arguments used if cmap is not passed. Set these to True to use the default rc['cmap.sequential'], rc['cmap.diverging'], rc['cmap.cyclic'], and rc['cmap.qualitative'] colormaps. The diverging option also applies DivergingNorm as the default continuous normalizer.
vmin, vmax (float, optional) – The minimum and maximum color scale values used with the norm normalizer. If discrete is False these are the absolute limits, and if discrete is True these are the approximate limits used to automatically determine levels or values lists at “nice” intervals. If levels or values were already passed as lists, these are ignored, and vmin and vmax are set to the minimum and maximum of the lists. If robust was passed, the default vmin and vmax are some percentile range of the data values. Otherwise, the default vmin and vmax are the minimum and maximum of the data values.
N – Shorthand for levels.
levels (int or sequence of float, default: rc['cmap.levels'] = 11) – The number of level edges or a sequence of level edges. If the former, locator is used to generate this many level edges at “nice” intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing levels fail with contour plots).
values (int or sequence of float, default: None) – The number of level centers or a sequence of level centers. If the former, locator is used to generate this many level centers at “nice” intervals. If the latter, levels are inferred using edges. This will override any levels input.
center_levels (bool, default False) – If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented.
robust (bool, float, or 2-tuple, default: rc['cmap.robust'] = False) – If True and vmin or vmax were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, 90 corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers.
inbounds (bool, default: rc['cmap.inbounds'] = True) – If True and vmin or vmax were not provided, when axis limits have been explicitly restricted with set_xlim() or set_ylim(), out-of-bounds data is ignored. See also rc['cmap.inbounds'] and rc['axes.inbounds'].
locator (locator-spec, default: matplotlib.ticker.MaxNLocator) – The locator used to determine level locations if levels or values were not already passed as lists. Passed to the Locator constructor. Default is MaxNLocator with levels integer levels.
locator_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Locator class.
symmetric (bool, default: False) – If True, the normalization range or discrete colormap levels are symmetric about zero.
positive (bool, default: False) – If True, the normalization range or discrete colormap levels are positive with a minimum at zero.
negative (bool, default: False) – If True, the normaliation range or discrete colormap levels are negative with a minimum at zero.
nozero (bool, default: False) – If True, 0 is removed from the level list. This is mainly useful for single-color contour plots.
**kwargs – Passed to matplotlib.axes.Axes.streamplot

tricontour(**kwargs)[source]

Plot contour lines on a triangular grid.

Parameters:

*args (z or x, y, z) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only z coordinates are passed, try to infer the x and y coordinates from the DataFrame indices and columns or the DataArray coordinates. Otherwise, the y coordinates are np.arange(0, y.shape[0]) and the x coordinates are np.arange(0, y.shape[1]).
- For pcolor and pcolormesh, calculate coordinate edges using edges or :func:`~ultraplot.utils.edges2d` if centers were provided. For all other methods, calculate coordinate centers if edges were provided.
- If the x or y coordinates are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. If the z coordinates are pint.Quantity, pass the magnitude to the plotting command. A pint.Quantity embedded in an xarray.DataArray is also supported.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.
transpose (bool, default: False) – Whether to transpose the input data. This should be used when passing datasets with column-major dimension order (x, y). Otherwise row-major dimension order (y, x) is expected.
order ({'C', 'F'}, default: 'C') – Alternative to transpose. 'C' corresponds to the default C-cyle row-major ordering (equivalent to transpose=False). 'F' corresponds to Fortran-style column-major ordering (equivalent to transpose=True).
globe (bool, default: False) – For ultraplot.axes.GeoAxes only. Whether to enforce global coverage. When set to True this does the following:
1. Interpolates input data to the North and South poles by setting the data values at the poles to the mean from latitudes nearest each pole.
2. Makes meridional coverage “circular”, i.e. the last longitude coordinate equals the first longitude coordinate plus 360°.
3. When basemap is the backend, cycles 1D longitude vectors to fit within the map edges. For example, if the central longitude is 90°, the data is shifted so that it spans -90° to 270°.

Other Parameters:

cmap (colormap-spec, default: rc['cmap.sequential'] = 'Fire' or rc['cmap.diverging'] = 'BuRd') – The colormap specifer, passed to the Colormap constructor function. If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then rc['cmap.diverging'] is used. Otherwise rc['cmap.sequential'] is used.
cmap_kw (dict-like, optional) – Passed to Colormap.
c, color, colors (color-spec or sequence of color-spec, optional) – The color(s) used to create a DiscreteColormap. If not passed, cmap is used.
norm (norm-spec, default: Normalize or DivergingNorm) – The data value normalizer, passed to the Norm constructor function. If discrete is True then 1) this affects the default level-generation algorithm (e.g. norm='log' builds levels in log-space) and 2) this is passed to DiscreteNorm to scale the colors before they are discretized (if norm is not already a DiscreteNorm). If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then DivergingNorm is used. Otherwise Normalize is used.
norm_kw (dict-like, optional) – Passed to Norm.
extend ({'neither', 'both', 'min', 'max'}, default: 'neither') – Direction for drawing colorbar “extensions” indicating out-of-bounds data on the end of the colorbar.
discrete (bool, default: rc['cmap.discrete'] = None) – If False, then DiscreteNorm is not applied to the colormap. Instead, for non-contour plots, the number of levels will be roughly controlled by rc['cmap.lut']. This has a similar effect to using levels=large_number but it may improve rendering speed. Default is True only for contouring commands like contourf and pseudocolor commands like pcolor.
sequential, diverging, cyclic, qualitative (bool, default: None) – Boolean arguments used if cmap is not passed. Set these to True to use the default rc['cmap.sequential'], rc['cmap.diverging'], rc['cmap.cyclic'], and rc['cmap.qualitative'] colormaps. The diverging option also applies DivergingNorm as the default continuous normalizer.
vmin, vmax (float, optional) – The minimum and maximum color scale values used with the norm normalizer. If discrete is False these are the absolute limits, and if discrete is True these are the approximate limits used to automatically determine levels or values lists at “nice” intervals. If levels or values were already passed as lists, these are ignored, and vmin and vmax are set to the minimum and maximum of the lists. If robust was passed, the default vmin and vmax are some percentile range of the data values. Otherwise, the default vmin and vmax are the minimum and maximum of the data values.
N – Shorthand for levels.
levels (int or sequence of float, default: rc['cmap.levels'] = 11) – The number of level edges or a sequence of level edges. If the former, locator is used to generate this many level edges at “nice” intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing levels fail with contour plots).
values (int or sequence of float, default: None) – The number of level centers or a sequence of level centers. If the former, locator is used to generate this many level centers at “nice” intervals. If the latter, levels are inferred using edges. This will override any levels input.
center_levels (bool, default False) – If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented.
robust (bool, float, or 2-tuple, default: rc['cmap.robust'] = False) – If True and vmin or vmax were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, 90 corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers.
inbounds (bool, default: rc['cmap.inbounds'] = True) – If True and vmin or vmax were not provided, when axis limits have been explicitly restricted with set_xlim() or set_ylim(), out-of-bounds data is ignored. See also rc['cmap.inbounds'] and rc['axes.inbounds'].
locator (locator-spec, default: matplotlib.ticker.MaxNLocator) – The locator used to determine level locations if levels or values were not already passed as lists. Passed to the Locator constructor. Default is MaxNLocator with levels integer levels.
locator_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Locator class.
symmetric (bool, default: False) – If True, the normalization range or discrete colormap levels are symmetric about zero.
positive (bool, default: False) – If True, the normalization range or discrete colormap levels are positive with a minimum at zero.
negative (bool, default: False) – If True, the normaliation range or discrete colormap levels are negative with a minimum at zero.
nozero (bool, default: False) – If True, 0 is removed from the level list. This is mainly useful for single-color contour plots.
lw, linewidth, linewidths (unit-spec, default: 0.3 or rc['lines.linewidth'] = 1.5) – The width of the line contours. Default is 0.3 when adding to filled contours or rc['lines.linewidth'] = 1.5 otherwise. If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: '-' or rc['contour.negative_linestyle'] = 'dashed') – The style of the line contours. Default is '-' for positive contours and rc['contour.negative_linestyle'] for negative contours.
ec, edgecolor, edgecolors (color-spec, default: 'k' or inferred) – The color of the line contours. Default is 'k' when adding to filled contours or inferred from color or cmap otherwise.
a, alpha, alpha (float, optional) – The opacity of the contours. Inferred from edgecolor by default.
label (str, optional) – The legend label to be used for this object. In the case of contours, this is paired with the the central artist in the artist list returned by matplotlib.contour.ContourSet.legend_elements.
labels (bool, optional) – Whether to apply labels to contours and grid boxes. The text will be white when the luminance of the underlying filled contour or grid box is less than 50 and black otherwise.
labels_kw (dict-like, optional) – Ignored if labels is False. Extra keyword args for the labels. For contour plots, this is passed to clabel. Otherwise, this is passed to text.
formatter, fmt (formatter-spec, optional) – The Formatter used to format number labels. Passed to the Formatter constructor.
formatter_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Formatter class.
precision (int, optional) – The maximum number of decimal places for number labels generated with the default formatter Simpleformatter.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to matplotlib.axes.Axes.tricontour.

tricontourf(**kwargs)[source]

Plot filled contours on a triangular grid.

Parameters:

*args (z or x, y, z) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only z coordinates are passed, try to infer the x and y coordinates from the DataFrame indices and columns or the DataArray coordinates. Otherwise, the y coordinates are np.arange(0, y.shape[0]) and the x coordinates are np.arange(0, y.shape[1]).
- For pcolor and pcolormesh, calculate coordinate edges using edges or :func:`~ultraplot.utils.edges2d` if centers were provided. For all other methods, calculate coordinate centers if edges were provided.
- If the x or y coordinates are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. If the z coordinates are pint.Quantity, pass the magnitude to the plotting command. A pint.Quantity embedded in an xarray.DataArray is also supported.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.
transpose (bool, default: False) – Whether to transpose the input data. This should be used when passing datasets with column-major dimension order (x, y). Otherwise row-major dimension order (y, x) is expected.
order ({'C', 'F'}, default: 'C') – Alternative to transpose. 'C' corresponds to the default C-cyle row-major ordering (equivalent to transpose=False). 'F' corresponds to Fortran-style column-major ordering (equivalent to transpose=True).
globe (bool, default: False) – For ultraplot.axes.GeoAxes only. Whether to enforce global coverage. When set to True this does the following:
1. Interpolates input data to the North and South poles by setting the data values at the poles to the mean from latitudes nearest each pole.
2. Makes meridional coverage “circular”, i.e. the last longitude coordinate equals the first longitude coordinate plus 360°.
3. When basemap is the backend, cycles 1D longitude vectors to fit within the map edges. For example, if the central longitude is 90°, the data is shifted so that it spans -90° to 270°.

Other Parameters:

cmap (colormap-spec, default: rc['cmap.sequential'] = 'Fire' or rc['cmap.diverging'] = 'BuRd') – The colormap specifer, passed to the Colormap constructor function. If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then rc['cmap.diverging'] is used. Otherwise rc['cmap.sequential'] is used.
cmap_kw (dict-like, optional) – Passed to Colormap.
c, color, colors (color-spec or sequence of color-spec, optional) – The color(s) used to create a DiscreteColormap. If not passed, cmap is used.
norm (norm-spec, default: Normalize or DivergingNorm) – The data value normalizer, passed to the Norm constructor function. If discrete is True then 1) this affects the default level-generation algorithm (e.g. norm='log' builds levels in log-space) and 2) this is passed to DiscreteNorm to scale the colors before they are discretized (if norm is not already a DiscreteNorm). If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then DivergingNorm is used. Otherwise Normalize is used.
norm_kw (dict-like, optional) – Passed to Norm.
extend ({'neither', 'both', 'min', 'max'}, default: 'neither') – Direction for drawing colorbar “extensions” indicating out-of-bounds data on the end of the colorbar.
discrete (bool, default: rc['cmap.discrete'] = None) – If False, then DiscreteNorm is not applied to the colormap. Instead, for non-contour plots, the number of levels will be roughly controlled by rc['cmap.lut']. This has a similar effect to using levels=large_number but it may improve rendering speed. Default is True only for contouring commands like contourf and pseudocolor commands like pcolor.
sequential, diverging, cyclic, qualitative (bool, default: None) – Boolean arguments used if cmap is not passed. Set these to True to use the default rc['cmap.sequential'], rc['cmap.diverging'], rc['cmap.cyclic'], and rc['cmap.qualitative'] colormaps. The diverging option also applies DivergingNorm as the default continuous normalizer.
vmin, vmax (float, optional) – The minimum and maximum color scale values used with the norm normalizer. If discrete is False these are the absolute limits, and if discrete is True these are the approximate limits used to automatically determine levels or values lists at “nice” intervals. If levels or values were already passed as lists, these are ignored, and vmin and vmax are set to the minimum and maximum of the lists. If robust was passed, the default vmin and vmax are some percentile range of the data values. Otherwise, the default vmin and vmax are the minimum and maximum of the data values.
N – Shorthand for levels.
levels (int or sequence of float, default: rc['cmap.levels'] = 11) – The number of level edges or a sequence of level edges. If the former, locator is used to generate this many level edges at “nice” intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing levels fail with contour plots).
values (int or sequence of float, default: None) – The number of level centers or a sequence of level centers. If the former, locator is used to generate this many level centers at “nice” intervals. If the latter, levels are inferred using edges. This will override any levels input.
center_levels (bool, default False) – If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented.
robust (bool, float, or 2-tuple, default: rc['cmap.robust'] = False) – If True and vmin or vmax were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, 90 corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers.
inbounds (bool, default: rc['cmap.inbounds'] = True) – If True and vmin or vmax were not provided, when axis limits have been explicitly restricted with set_xlim() or set_ylim(), out-of-bounds data is ignored. See also rc['cmap.inbounds'] and rc['axes.inbounds'].
locator (locator-spec, default: matplotlib.ticker.MaxNLocator) – The locator used to determine level locations if levels or values were not already passed as lists. Passed to the Locator constructor. Default is MaxNLocator with levels integer levels.
locator_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Locator class.
symmetric (bool, default: False) – If True, the normalization range or discrete colormap levels are symmetric about zero.
positive (bool, default: False) – If True, the normalization range or discrete colormap levels are positive with a minimum at zero.
negative (bool, default: False) – If True, the normaliation range or discrete colormap levels are negative with a minimum at zero.
nozero (bool, default: False) – If True, 0 is removed from the level list. This is mainly useful for single-color contour plots.
lw, linewidth, linewidths (unit-spec, default: 0.3 or rc['lines.linewidth'] = 1.5) – The width of the line contours. Default is 0.3 when adding to filled contours or rc['lines.linewidth'] = 1.5 otherwise. If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: '-' or rc['contour.negative_linestyle'] = 'dashed') – The style of the line contours. Default is '-' for positive contours and rc['contour.negative_linestyle'] for negative contours.
ec, edgecolor, edgecolors (color-spec, default: 'k' or inferred) – The color of the line contours. Default is 'k' when adding to filled contours or inferred from color or cmap otherwise.
a, alpha, alpha (float, optional) – The opacity of the contours. Inferred from edgecolor by default.
edgefix (bool or float, default: rc.edgefix = True) – Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). See this github repo for a demonstration of the problem. If True, a small default linewidth of 0.3 is used to cover up the white lines. If float (e.g. edgefix=0.5), this specific linewidth is used to cover up the white lines. This feature is automatically disabled when the patches have transparency.
label (str, optional) – The legend label to be used for this object. In the case of contours, this is paired with the the central artist in the artist list returned by matplotlib.contour.ContourSet.legend_elements.
labels (bool, optional) – Whether to apply labels to contours and grid boxes. The text will be white when the luminance of the underlying filled contour or grid box is less than 50 and black otherwise.
labels_kw (dict-like, optional) – Ignored if labels is False. Extra keyword args for the labels. For contour plots, this is passed to clabel. Otherwise, this is passed to text.
formatter, fmt (formatter-spec, optional) – The Formatter used to format number labels. Passed to the Formatter constructor.
formatter_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Formatter class.
precision (int, optional) – The maximum number of decimal places for number labels generated with the default formatter Simpleformatter.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to matplotlib.axes.Axes.tricontourf.

tripcolor(**kwargs)[source]

Plot triangular grid boxes.

Parameters:

*args (z or x, y, z) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only z coordinates are passed, try to infer the x and y coordinates from the DataFrame indices and columns or the DataArray coordinates. Otherwise, the y coordinates are np.arange(0, y.shape[0]) and the x coordinates are np.arange(0, y.shape[1]).
- For pcolor and pcolormesh, calculate coordinate edges using edges or :func:`~ultraplot.utils.edges2d` if centers were provided. For all other methods, calculate coordinate centers if edges were provided.
- If the x or y coordinates are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. If the z coordinates are pint.Quantity, pass the magnitude to the plotting command. A pint.Quantity embedded in an xarray.DataArray is also supported.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.
transpose (bool, default: False) – Whether to transpose the input data. This should be used when passing datasets with column-major dimension order (x, y). Otherwise row-major dimension order (y, x) is expected.
order ({'C', 'F'}, default: 'C') – Alternative to transpose. 'C' corresponds to the default C-cyle row-major ordering (equivalent to transpose=False). 'F' corresponds to Fortran-style column-major ordering (equivalent to transpose=True).
globe (bool, default: False) – For ultraplot.axes.GeoAxes only. Whether to enforce global coverage. When set to True this does the following:
1. Interpolates input data to the North and South poles by setting the data values at the poles to the mean from latitudes nearest each pole.
2. Makes meridional coverage “circular”, i.e. the last longitude coordinate equals the first longitude coordinate plus 360°.
3. When basemap is the backend, cycles 1D longitude vectors to fit within the map edges. For example, if the central longitude is 90°, the data is shifted so that it spans -90° to 270°.

Other Parameters:

cmap (colormap-spec, default: rc['cmap.sequential'] = 'Fire' or rc['cmap.diverging'] = 'BuRd') – The colormap specifer, passed to the Colormap constructor function. If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then rc['cmap.diverging'] is used. Otherwise rc['cmap.sequential'] is used.
cmap_kw (dict-like, optional) – Passed to Colormap.
c, color, colors (color-spec or sequence of color-spec, optional) – The color(s) used to create a DiscreteColormap. If not passed, cmap is used.
norm (norm-spec, default: Normalize or DivergingNorm) – The data value normalizer, passed to the Norm constructor function. If discrete is True then 1) this affects the default level-generation algorithm (e.g. norm='log' builds levels in log-space) and 2) this is passed to DiscreteNorm to scale the colors before they are discretized (if norm is not already a DiscreteNorm). If rc['cmap.autodiverging'] is True and the normalization range contains negative and positive values then DivergingNorm is used. Otherwise Normalize is used.
norm_kw (dict-like, optional) – Passed to Norm.
extend ({'neither', 'both', 'min', 'max'}, default: 'neither') – Direction for drawing colorbar “extensions” indicating out-of-bounds data on the end of the colorbar.
discrete (bool, default: rc['cmap.discrete'] = None) – If False, then DiscreteNorm is not applied to the colormap. Instead, for non-contour plots, the number of levels will be roughly controlled by rc['cmap.lut']. This has a similar effect to using levels=large_number but it may improve rendering speed. Default is True only for contouring commands like contourf and pseudocolor commands like pcolor.
sequential, diverging, cyclic, qualitative (bool, default: None) – Boolean arguments used if cmap is not passed. Set these to True to use the default rc['cmap.sequential'], rc['cmap.diverging'], rc['cmap.cyclic'], and rc['cmap.qualitative'] colormaps. The diverging option also applies DivergingNorm as the default continuous normalizer.
vmin, vmax (float, optional) – The minimum and maximum color scale values used with the norm normalizer. If discrete is False these are the absolute limits, and if discrete is True these are the approximate limits used to automatically determine levels or values lists at “nice” intervals. If levels or values were already passed as lists, these are ignored, and vmin and vmax are set to the minimum and maximum of the lists. If robust was passed, the default vmin and vmax are some percentile range of the data values. Otherwise, the default vmin and vmax are the minimum and maximum of the data values.
N – Shorthand for levels.
levels (int or sequence of float, default: rc['cmap.levels'] = 11) – The number of level edges or a sequence of level edges. If the former, locator is used to generate this many level edges at “nice” intervals. If the latter, the levels should be monotonically increasing or decreasing (note decreasing levels fail with contour plots).
values (int or sequence of float, default: None) – The number of level centers or a sequence of level centers. If the former, locator is used to generate this many level centers at “nice” intervals. If the latter, levels are inferred using edges. This will override any levels input.
center_levels (bool, default False) – If set to true, the discrete color bar bins will be centered on the level values instead of using the level values as the edges of the discrete bins. This option can be used for diverging, discrete color bars with both positive and negative data to ensure data near zero is properly represented.
robust (bool, float, or 2-tuple, default: rc['cmap.robust'] = False) – If True and vmin or vmax were not provided, they are determined from the 2nd and 98th data percentiles rather than the minimum and maximum. If float, this percentile range is used (for example, 90 corresponds to the 5th to 95th percentiles). If 2-tuple of float, these specific percentiles should be used. This feature is useful when your data has large outliers.
inbounds (bool, default: rc['cmap.inbounds'] = True) – If True and vmin or vmax were not provided, when axis limits have been explicitly restricted with set_xlim() or set_ylim(), out-of-bounds data is ignored. See also rc['cmap.inbounds'] and rc['axes.inbounds'].
locator (locator-spec, default: matplotlib.ticker.MaxNLocator) – The locator used to determine level locations if levels or values were not already passed as lists. Passed to the Locator constructor. Default is MaxNLocator with levels integer levels.
locator_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Locator class.
symmetric (bool, default: False) – If True, the normalization range or discrete colormap levels are symmetric about zero.
positive (bool, default: False) – If True, the normalization range or discrete colormap levels are positive with a minimum at zero.
negative (bool, default: False) – If True, the normaliation range or discrete colormap levels are negative with a minimum at zero.
nozero (bool, default: False) – If True, 0 is removed from the level list. This is mainly useful for single-color contour plots.
lw, linewidth, linewidths (unit-spec, default: 0.3) – The width of lines between grid boxes. If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: '-') – The style of lines between grid boxes.
ec, edgecolor, edgecolors (color-spec, default: 'k') – The color of lines between grid boxes.
a, alpha, alphas (float, optional) – The opacity of the grid boxes. Inferred from cmap by default.
edgefix (bool or float, default: rc.edgefix = True) – Whether to fix the common issue where white lines appear between adjacent patches in saved vector graphics (this can slow down figure rendering). See this github repo for a demonstration of the problem. If True, a small default linewidth of 0.3 is used to cover up the white lines. If float (e.g. edgefix=0.5), this specific linewidth is used to cover up the white lines. This feature is automatically disabled when the patches have transparency.
label (str, optional) – The legend label to be used for this object. In the case of contours, this is paired with the the central artist in the artist list returned by matplotlib.contour.ContourSet.legend_elements.
labels (bool, optional) – Whether to apply labels to contours and grid boxes. The text will be white when the luminance of the underlying filled contour or grid box is less than 50 and black otherwise.
labels_kw (dict-like, optional) – Ignored if labels is False. Extra keyword args for the labels. For contour plots, this is passed to clabel. Otherwise, this is passed to text.
formatter, fmt (formatter-spec, optional) – The Formatter used to format number labels. Passed to the Formatter constructor.
formatter_kw (dict-like, optional) – Keyword arguments passed to matplotlib.ticker.Formatter class.
precision (int, optional) – The maximum number of decimal places for number labels generated with the default formatter Simpleformatter.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to matplotlib.axes.Axes.tripcolor.

violin(*args, **kwargs)[source]

Plot vertical violins with a nice default style matching this matplotlib example.

Parameters:

*args (y or x, y) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only y coordinates are passed, try to infer the x coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the x coordinates are np.arange(0, y.shape[0]).
- If the y coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with boxplot, violinplot, or when using means=True or medians=True).
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

cycle (cycle-spec, optional) – The cycle specifer, passed to the Cycle constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use cycle=False, cycle='none', or cycle=() (analogous to disabling ticks with e.g. xformatter='none'). To restore the default property cycler, use cycle=True.
cycle_kw (dict-like, optional) – Passed to Cycle.
lw, linewidth, linewidths (unit-spec, default: rc['patch.linewidth'] = 0.6) – The edge width of the patch(es). If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: '-') – The edge style of the patch(es).
ec, edgecolor, edgecolors (color-spec, default: 'black') – The edge color of the patch(es).
fc, facecolor, facecolors, fillcolor, fillcolors (color-spec, optional) – The face color of the patch(es). The property cycle is used by default.
a, alpha, alphas (float, optional) – The opacity of the patch(es). Inferred from facecolor and edgecolor by default.
label, value (float or str, optional) – The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally used with 1D positional arguments.
labels, values (sequence of float or sequence of str, optional) – The legend labels or colorbar coordinates used for each plotted element. Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments.
showmeans, showmedians (bool, optional) – Interpreted as means=True and medians=True when passed.
showextrema (bool, optional) – Interpreted as barpctiles=True when passed (i.e. shows minima and maxima).
bars (bool, default: None) – Shorthand for barstd, barstds.
barstd, barstds (bool, float, or 2-tuple of float, optional) – Valid only if mean or median is True. Standard deviation multiples for thin error bars with optional whiskers (i.e., caps). If scalar, then +/- that multiple is used. If True, the default standard deviation range of +/-3 is used.
barpctile, barpctiles (bool, float, or 2-tuple of float, optional) – Valid only if mean or median is True. As with barstd, but instead using percentiles for the error bars. If scalar, that percentile range is used (e.g., 90 shows the 5th to 95th percentiles). If True, the default percentile range of 0 to 100 is used.
bardata (array-like, optional) – Valid only if mean and median are False. If shape is 2 x N, these are the lower and upper bounds for the thin error bars. If shape is N, these are the absolute, symmetric deviations from the central points.
boxes (bool, default: None) – Shorthand for boxstd, boxstds.
boxstd, boxstds, boxpctile, boxpctiles, boxdata (optional) – As with barstd, barpctile, and bardata, but for thicker error bars representing a smaller interval than the thin error bars. If boxstds is True, the default standard deviation range of +/-1 is used. If boxpctiles is True, the default percentile range of 25 to 75 is used (i.e., the interquartile range). When “boxes” and “bars” are combined, this has the effect of drawing miniature box-and-whisker plots.
capsize (float, default: rc['errorbar.capsize'] = 3.0) – The cap size for thin error bars in points.
barz, barzorder, boxz, boxzorder (float, default: 2.5) – The “zorder” for the thin and thick error bars.
barc, barcolor, boxc, boxcolor (color-spec, default: rc['boxplot.whiskerprops.color'] = 'black') – Colors for the thin and thick error bars.
barlw, barlinewidth, boxlw, boxlinewidth (float, default: rc['boxplot.whiskerprops.linewidth'] = 1.0) – Line widths for the thin and thick error bars, in points. The default for boxes is 4 times rc['boxplot.whiskerprops.linewidth'].
boxm, boxmarker (bool or marker-spec, default: 'o') – Whether to draw a small marker in the middle of the box denoting the mean or median position. Ignored if boxes is False.
boxms, boxmarkersize (size-spec, default: (2 * boxlinewidth) ** 2) – The marker size for the boxmarker marker in points ** 2.
boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor (color-spec, default: 'w') – Color, face color, and edge color for the boxmarker marker.
**kwargs – Passed to matplotlib.axes.Axes.violinplot.

violinh(*args, **kwargs)[source]

Plot horizontal violins with a nice default style matching this matplotlib example.

Parameters:

*args (x or y, x) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only x coordinates are passed, try to infer the y coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the y coordinates are np.arange(0, x.shape[0]).
- If the x coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with boxplot, violinplot, or when using means=True or medians=True).
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

cycle (cycle-spec, optional) – The cycle specifer, passed to the Cycle constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use cycle=False, cycle='none', or cycle=() (analogous to disabling ticks with e.g. xformatter='none'). To restore the default property cycler, use cycle=True.
cycle_kw (dict-like, optional) – Passed to Cycle.
lw, linewidth, linewidths (unit-spec, default: rc['patch.linewidth'] = 0.6) – The edge width of the patch(es). If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: '-') – The edge style of the patch(es).
ec, edgecolor, edgecolors (color-spec, default: 'black') – The edge color of the patch(es).
fc, facecolor, facecolors, fillcolor, fillcolors (color-spec, optional) – The face color of the patch(es). The property cycle is used by default.
a, alpha, alphas (float, optional) – The opacity of the patch(es). Inferred from facecolor and edgecolor by default.
label, value (float or str, optional) – The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally used with 1D positional arguments.
labels, values (sequence of float or sequence of str, optional) – The legend labels or colorbar coordinates used for each plotted element. Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments.
showmeans, showmedians (bool, optional) – Interpreted as means=True and medians=True when passed.
showextrema (bool, optional) – Interpreted as barpctiles=True when passed (i.e. shows minima and maxima).
bars (bool, default: None) – Shorthand for barstd, barstds.
barstd, barstds (bool, float, or 2-tuple of float, optional) – Valid only if mean or median is True. Standard deviation multiples for thin error bars with optional whiskers (i.e., caps). If scalar, then +/- that multiple is used. If True, the default standard deviation range of +/-3 is used.
barpctile, barpctiles (bool, float, or 2-tuple of float, optional) – Valid only if mean or median is True. As with barstd, but instead using percentiles for the error bars. If scalar, that percentile range is used (e.g., 90 shows the 5th to 95th percentiles). If True, the default percentile range of 0 to 100 is used.
bardata (array-like, optional) – Valid only if mean and median are False. If shape is 2 x N, these are the lower and upper bounds for the thin error bars. If shape is N, these are the absolute, symmetric deviations from the central points.
boxes (bool, default: None) – Shorthand for boxstd, boxstds.
boxstd, boxstds, boxpctile, boxpctiles, boxdata (optional) – As with barstd, barpctile, and bardata, but for thicker error bars representing a smaller interval than the thin error bars. If boxstds is True, the default standard deviation range of +/-1 is used. If boxpctiles is True, the default percentile range of 25 to 75 is used (i.e., the interquartile range). When “boxes” and “bars” are combined, this has the effect of drawing miniature box-and-whisker plots.
capsize (float, default: rc['errorbar.capsize'] = 3.0) – The cap size for thin error bars in points.
barz, barzorder, boxz, boxzorder (float, default: 2.5) – The “zorder” for the thin and thick error bars.
barc, barcolor, boxc, boxcolor (color-spec, default: rc['boxplot.whiskerprops.color'] = 'black') – Colors for the thin and thick error bars.
barlw, barlinewidth, boxlw, boxlinewidth (float, default: rc['boxplot.whiskerprops.linewidth'] = 1.0) – Line widths for the thin and thick error bars, in points. The default for boxes is 4 times rc['boxplot.whiskerprops.linewidth'].
boxm, boxmarker (bool or marker-spec, default: 'o') – Whether to draw a small marker in the middle of the box denoting the mean or median position. Ignored if boxes is False.
boxms, boxmarkersize (size-spec, default: (2 * boxlinewidth) ** 2) – The marker size for the boxmarker marker in points ** 2.
boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor (color-spec, default: 'w') – Color, face color, and edge color for the boxmarker marker.
**kwargs – Passed to matplotlib.axes.Axes.violinplot.

violinplot(**kwargs)[source]

Plot vertical violins with a nice default style matching this matplotlib example.

Parameters:

*args (y or x, y) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only y coordinates are passed, try to infer the x coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the x coordinates are np.arange(0, y.shape[0]).
- If the y coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with boxplot, violinplot, or when using means=True or medians=True).
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

cycle (cycle-spec, optional) – The cycle specifer, passed to the Cycle constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use cycle=False, cycle='none', or cycle=() (analogous to disabling ticks with e.g. xformatter='none'). To restore the default property cycler, use cycle=True.
cycle_kw (dict-like, optional) – Passed to Cycle.
lw, linewidth, linewidths (unit-spec, default: rc['patch.linewidth'] = 0.6) – The edge width of the patch(es). If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: '-') – The edge style of the patch(es).
ec, edgecolor, edgecolors (color-spec, default: 'black') – The edge color of the patch(es).
fc, facecolor, facecolors, fillcolor, fillcolors (color-spec, optional) – The face color of the patch(es). The property cycle is used by default.
a, alpha, alphas (float, optional) – The opacity of the patch(es). Inferred from facecolor and edgecolor by default.
label, value (float or str, optional) – The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally used with 1D positional arguments.
labels, values (sequence of float or sequence of str, optional) – The legend labels or colorbar coordinates used for each plotted element. Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments.
showmeans, showmedians (bool, optional) – Interpreted as means=True and medians=True when passed.
showextrema (bool, optional) – Interpreted as barpctiles=True when passed (i.e. shows minima and maxima).
bars (bool, default: None) – Shorthand for barstd, barstds.
barstd, barstds (bool, float, or 2-tuple of float, optional) – Valid only if mean or median is True. Standard deviation multiples for thin error bars with optional whiskers (i.e., caps). If scalar, then +/- that multiple is used. If True, the default standard deviation range of +/-3 is used.
barpctile, barpctiles (bool, float, or 2-tuple of float, optional) – Valid only if mean or median is True. As with barstd, but instead using percentiles for the error bars. If scalar, that percentile range is used (e.g., 90 shows the 5th to 95th percentiles). If True, the default percentile range of 0 to 100 is used.
bardata (array-like, optional) – Valid only if mean and median are False. If shape is 2 x N, these are the lower and upper bounds for the thin error bars. If shape is N, these are the absolute, symmetric deviations from the central points.
boxes (bool, default: None) – Shorthand for boxstd, boxstds.
boxstd, boxstds, boxpctile, boxpctiles, boxdata (optional) – As with barstd, barpctile, and bardata, but for thicker error bars representing a smaller interval than the thin error bars. If boxstds is True, the default standard deviation range of +/-1 is used. If boxpctiles is True, the default percentile range of 25 to 75 is used (i.e., the interquartile range). When “boxes” and “bars” are combined, this has the effect of drawing miniature box-and-whisker plots.
capsize (float, default: rc['errorbar.capsize'] = 3.0) – The cap size for thin error bars in points.
barz, barzorder, boxz, boxzorder (float, default: 2.5) – The “zorder” for the thin and thick error bars.
barc, barcolor, boxc, boxcolor (color-spec, default: rc['boxplot.whiskerprops.color'] = 'black') – Colors for the thin and thick error bars.
barlw, barlinewidth, boxlw, boxlinewidth (float, default: rc['boxplot.whiskerprops.linewidth'] = 1.0) – Line widths for the thin and thick error bars, in points. The default for boxes is 4 times rc['boxplot.whiskerprops.linewidth'].
boxm, boxmarker (bool or marker-spec, default: 'o') – Whether to draw a small marker in the middle of the box denoting the mean or median position. Ignored if boxes is False.
boxms, boxmarkersize (size-spec, default: (2 * boxlinewidth) ** 2) – The marker size for the boxmarker marker in points ** 2.
boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor (color-spec, default: 'w') – Color, face color, and edge color for the boxmarker marker.
**kwargs – Passed to matplotlib.axes.Axes.violinplot.

violinploth(*args, **kwargs)[source]

Plot horizontal violins with a nice default style matching this matplotlib example.

Parameters:

*args (x or y, x) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only x coordinates are passed, try to infer the y coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the y coordinates are np.arange(0, x.shape[0]).
- If the x coordinates are a 2D array, plot each column of data in succession (except where each column of data represents a statistical distribution, as with boxplot, violinplot, or when using means=True or medians=True).
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

cycle (cycle-spec, optional) – The cycle specifer, passed to the Cycle constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use cycle=False, cycle='none', or cycle=() (analogous to disabling ticks with e.g. xformatter='none'). To restore the default property cycler, use cycle=True.
cycle_kw (dict-like, optional) – Passed to Cycle.
lw, linewidth, linewidths (unit-spec, default: rc['patch.linewidth'] = 0.6) – The edge width of the patch(es). If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: '-') – The edge style of the patch(es).
ec, edgecolor, edgecolors (color-spec, default: 'black') – The edge color of the patch(es).
fc, facecolor, facecolors, fillcolor, fillcolors (color-spec, optional) – The face color of the patch(es). The property cycle is used by default.
a, alpha, alphas (float, optional) – The opacity of the patch(es). Inferred from facecolor and edgecolor by default.
label, value (float or str, optional) – The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally used with 1D positional arguments.
labels, values (sequence of float or sequence of str, optional) – The legend labels or colorbar coordinates used for each plotted element. Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments.
showmeans, showmedians (bool, optional) – Interpreted as means=True and medians=True when passed.
showextrema (bool, optional) – Interpreted as barpctiles=True when passed (i.e. shows minima and maxima).
bars (bool, default: None) – Shorthand for barstd, barstds.
barstd, barstds (bool, float, or 2-tuple of float, optional) – Valid only if mean or median is True. Standard deviation multiples for thin error bars with optional whiskers (i.e., caps). If scalar, then +/- that multiple is used. If True, the default standard deviation range of +/-3 is used.
barpctile, barpctiles (bool, float, or 2-tuple of float, optional) – Valid only if mean or median is True. As with barstd, but instead using percentiles for the error bars. If scalar, that percentile range is used (e.g., 90 shows the 5th to 95th percentiles). If True, the default percentile range of 0 to 100 is used.
bardata (array-like, optional) – Valid only if mean and median are False. If shape is 2 x N, these are the lower and upper bounds for the thin error bars. If shape is N, these are the absolute, symmetric deviations from the central points.
boxes (bool, default: None) – Shorthand for boxstd, boxstds.
boxstd, boxstds, boxpctile, boxpctiles, boxdata (optional) – As with barstd, barpctile, and bardata, but for thicker error bars representing a smaller interval than the thin error bars. If boxstds is True, the default standard deviation range of +/-1 is used. If boxpctiles is True, the default percentile range of 25 to 75 is used (i.e., the interquartile range). When “boxes” and “bars” are combined, this has the effect of drawing miniature box-and-whisker plots.
capsize (float, default: rc['errorbar.capsize'] = 3.0) – The cap size for thin error bars in points.
barz, barzorder, boxz, boxzorder (float, default: 2.5) – The “zorder” for the thin and thick error bars.
barc, barcolor, boxc, boxcolor (color-spec, default: rc['boxplot.whiskerprops.color'] = 'black') – Colors for the thin and thick error bars.
barlw, barlinewidth, boxlw, boxlinewidth (float, default: rc['boxplot.whiskerprops.linewidth'] = 1.0) – Line widths for the thin and thick error bars, in points. The default for boxes is 4 times rc['boxplot.whiskerprops.linewidth'].
boxm, boxmarker (bool or marker-spec, default: 'o') – Whether to draw a small marker in the middle of the box denoting the mean or median position. Ignored if boxes is False.
boxms, boxmarkersize (size-spec, default: (2 * boxlinewidth) ** 2) – The marker size for the boxmarker marker in points ** 2.
boxmc, boxmarkercolor, boxmec, boxmarkeredgecolor (color-spec, default: 'w') – Color, face color, and edge color for the boxmarker marker.
**kwargs – Passed to matplotlib.axes.Axes.violinplot.

violins(*, new_obj=<function PlotAxes.violin>, message="'violins' was deprecated in version 0.8.0 and may be removed in the next major release (version 2.0.0). Please use 'violin' instead.", **kwargs)

vlines(*args, **kwargs)[source]

Plot vertical lines.

Parameters:

*args (y2 or x, y2, or x, y1, y2) – The data passed as positional or keyword arguments. Interpreted as follows:
- If only y coordinates are passed, try to infer the x coordinates from the Series or DataFrame indices or the DataArray coordinates. Otherwise, the x coordinates are np.arange(0, y2.shape[0]).
- If only x and y2 coordinates are passed, set the y1 coordinates to zero. This draws elements originating from the zero line.
- If both y1 and y2 are provided, draw elements between these points. If either are 2D, draw elements by iterating over each column.
- If any arguments are pint.Quantity, auto-add the pint unit registry to matplotlib’s unit registry using setup_matplotlib. A pint.Quantity embedded in an xarray.DataArray is also supported.
data (dict-like, optional) – A dict-like dataset container (e.g., DataFrame or Dataset). If passed, each data argument can optionally be a string key and the arrays used for plotting are retrieved with data[key]. This is a native matplotlib feature.
autoformat (bool, default: rc.autoformat = True) – Whether the x axis labels, y axis labels, axis formatters, axes titles, legend titles, and colorbar labels are automatically configured when a Series, DataFrame, DataArray, or Quantity is passed to the plotting command. Formatting of pint.Quantity unit strings is controlled by rc.unitformat = 'L'.

Other Parameters:

stack, stacked (bool, default: False) – Whether to “stack” lines from successive columns of y data or plot lines on top of each other.
cycle (cycle-spec, optional) – The cycle specifer, passed to the Cycle constructor. If the returned cycler is unchanged from the current cycler, the axes cycler will not be reset to its first position. To disable property cycling and just use black for the default color, use cycle=False, cycle='none', or cycle=() (analogous to disabling ticks with e.g. xformatter='none'). To restore the default property cycler, use cycle=True.
cycle_kw (dict-like, optional) – Passed to Cycle.
lw, linewidth, linewidths (unit-spec, default: rc['lines.linewidth'] = 1.5) – The width of the line(s). If float, units are points. If string, interpreted by units.
ls, linestyle, linestyles (str, default: rc['lines.linestyle'] = '-') – The style of the line(s).
c, color, colors (color-spec, optional) – The color of the line(s). The property cycle is used by default.
a, alpha, alphas (float, optional) – The opacity of the line(s). Inferred from color by default.
negpos (bool, default: False) – Whether to shade lines where ymax >= ymin with poscolor and where ymax < ymin with negcolor. If True this function will return a length-2 silent list of handles.
negcolor, poscolor (color-spec, default: rc.negcolor = 'blue7', rc.poscolor = 'red7') – Colors to use for the negative and positive lines. Ignored if negpos is False.
inbounds (bool, default: rc['axes.inbounds'] = True) – Whether to restrict the default y (x) axis limits to account for only in-bounds data when the x (y) axis limits have been locked. See also rc['axes.inbounds'] and rc['cmap.inbounds'].
label, value (float or str, optional) – The single legend label or colorbar coordinate to be used for this plotted element. Can be numeric or string. This is generally used with 1D positional arguments.
labels, values (sequence of float or sequence of str, optional) – The legend labels or colorbar coordinates used for each plotted element. Can be numeric or string, and must match the number of plotted elements. This is generally used with 2D positional arguments.
colorbar (bool, int, or str, optional) – If not None, this is a location specifying where to draw an inset or outer colorbar from the resulting object(s). If True, the default rc['colorbar.loc'] = 'right' is used. If the same location is used in successive plotting calls, object(s) will be added to the existing colorbar in that location (valid for colorbars built from lists of artists). Valid locations are shown in in colorbar.
colorbar_kw (dict-like, optional) – Extra keyword args for the call to colorbar.
legend (bool, int, or str, optional) – Location specifying where to draw an inset or outer legend from the resulting object(s). If True, the default rc['legend.loc'] = 'best' is used. If the same location is used in successive plotting calls, object(s) will be added to existing legend in that location. Valid locations are shown in legend().
legend_kw (dict-like, optional) – Extra keyword args for the call to legend.
**kwargs – Passed to vlines.