API reference

The comprehensive API reference. All of the below objects are imported into the top-level namespace. Use help(uplt.object) to read the docs during a python session.

Please note that UltraPlot removes the associated documentation when functionality is deprecated (see What’s New). However, UltraPlot adheres to effort versioning, which means old code that uses deprecated functionality will still work and issue warnings rather than errors.

Important

The documentation for “wrapper” functions like standardize_1d and cmap_changer from UltraPlot < 0.8.0 can now be found under individual PlotAxes methods like plot() and pcolor(). Note that calling help(ax.method) in a python session will show both the UltraPlot documentation and the original matplotlib documentation.

Figure class

The figure class used for all ultraplot figures.

Figure()

The Figure subclass used by ultraplot.

Grid classes

The gridspec and subplot grid classes used throughout ultraplot.

GridSpec([nrows, ncols])	A GridSpec subclass that permits variable spacing between successive rows and columns and hides "panel slots" from indexing.
SubplotGrid([sequence])	List-like, array-like object used to store subplots returned by subplots.

Axes classes

The various axes classes used throughout ultraplot.

Axes(*args, **kwargs)	The lowest-level Axes subclass used by ultraplot.
PlotAxes(*args, **kwargs)	The second lowest-level Axes subclass used by ultraplot.
CartesianAxes(*args, **kwargs)	Axes subclass for plotting in ordinary Cartesian coordinates.
PolarAxes(*args, **kwargs)	Axes subclass for plotting in polar coordinates.
GeoAxes(*args, **kwargs)	Axes subclass for plotting in geographic projections.
ThreeAxes(*args, **kwargs)	Simple mix-in of ultraplot.axes.Axes with Axes3D.

Top-level functions

The starting point for creating ultraplot figures.

figure(**kwargs)	Create an empty figure.
subplot(**kwargs)	Return a figure and a single subplot.
subplots(*args, **kwargs)	Return a figure and an arbitrary grid of subplots.
show(*args, **kwargs)	Call matplotlib.pyplot.show.
close(*args, **kwargs)	Call matplotlib.pyplot.close.
switch_backend(*args, **kwargs)	Call matplotlib.pyplot.switch_backend.
ion()	Call matplotlib.pyplot.ion.
ioff()	Call matplotlib.pyplot.ioff.
isinteractive()	Call matplotlib.pyplot.isinteractive.

Configuration tools

Tools for setting up ultraplot and configuring global settings. See the configuration guide for details.

Configurator([local, user, default])	A dictionary-like class for managing matplotlib settings stored in rc_matplotlib and ultraplot settings stored in rc_ultraplot.
rc	Instance of Configurator.
rc_ultraplot	A dictionary-like container of ultraplot settings.
rc_matplotlib	A dictionary-like container of matplotlib settings.
use_style(style)	Apply the matplotlib style(s) with matplotlib.style.use.
config_inline_backend([fmt])	Set up the ipython inline backend display format and ensure that inline figures always look the same as saved figures.
register_cmaps(*args[, user, local, default])	Register named colormaps.
register_cycles(*args[, user, local, default])	Register named color cycles.
register_colors(*args[, user, local, ...])	Register named colors.
register_fonts(*args[, user, local, default])	Register font families.

Constructor functions

T”he constructor functions used to build class instances from simple shorthand arguments.

Proj(name[, backend, lon0, lon_0, lat0, ...])	Return a cartopy.crs.Projection or Basemap instance.
Locator(locator, *args[, discrete])	Return a Locator instance.
Formatter(formatter, *args[, date, index])	Return a Formatter instance.
Scale(scale, *args, **kwargs)	Return a ScaleBase instance.
Colormap(*args[, name, listmode, filemode, ...])	Generate, retrieve, modify, and/or merge instances of PerceptualColormap, ContinuousColormap, and DiscreteColormap.
Norm(norm, *args, **kwargs)	Return an arbitrary Normalize instance.
Cycle(*args[, N, samples, name])	Generate and merge Cycler instances in a variety of ways.

Locators and formatters

Various Locator and Formatter classes.

IndexLocator([base, offset])	Format numbers by assigning fixed strings to non-negative indices.
DiscreteLocator(locs, **kwargs)	A tick locator suitable for discretized colorbars.
DegreeLocator(*args, **kwargs)	Locate geographic gridlines with degree-minute-second support.
LongitudeLocator([lon0])	Locate longitude gridlines with degree-minute-second support.
LatitudeLocator(*args, **kwargs)	Locate latitude gridlines with degree-minute-second support.
AutoFormatter([zerotrim, tickrange, ...])	The default formatter used for ultraplot tick labels.
SimpleFormatter([precision, zerotrim, ...])	A general purpose number formatter.
IndexFormatter(labels)	Format numbers by assigning fixed strings to non-negative indices.
SciFormatter([precision, zerotrim])	Format numbers with scientific notation.
SigFigFormatter([sigfig, zerotrim, base])	Format numbers by retaining the specified number of significant digits.
FracFormatter([symbol, number])	Format numbers as integers or integer fractions.
CFDatetimeFormatter(fmt[, calendar, units])	Format dates using cftime.datetime.strftime format strings.
AutoCFDatetimeFormatter(locator, calendar[, ...])	Automatic formatter for cftime.datetime data.
AutoCFDatetimeLocator([maxticks, calendar, ...])	Determines tick locations when plotting cftime.datetime data.
DegreeFormatter(*args, **kwargs)	Formatter for longitude and latitude gridline labels.
LongitudeFormatter([lon0])	Format longitude gridline labels.
LatitudeFormatter(*args, **kwargs)	Format latitude gridline labels.

Axis scale classes

Various axis ScaleBase classes.

CutoffScale(*args)	Axis scale composed of arbitrary piecewise linear transformations.
ExpScale([a, b, c, inverse])	"Exponential scale" that performs either of two transformations.
FuncScale([transform, invert, parent_scale])	Axis scale composed of arbitrary forward and inverse transformations.
InverseScale()	Axis scale that is linear in the inverse of x.
LinearScale(**kwargs)	As with LinearScale but with AutoFormatter as the default major formatter.
LogitScale(**kwargs)	As with LogitScale but with AutoFormatter as the default major formatter.
LogScale(**kwargs)	As with LogScale but with AutoFormatter as the default major formatter.
MercatorLatitudeScale([thresh])	Axis scale that is linear in the Mercator projection latitude.
PowerScale([power, inverse])	"Power scale" that performs the transformation
SineLatitudeScale()	Axis scale that is linear in the sine transformation of x.
SymmetricalLogScale(**kwargs)	As with SymmetricalLogScale but with AutoFormatter as the default major formatter.

Colormaps and normalizers

Various colormap classes and colormap normalization classes.

DiscreteColormap(colors[, name, N, alpha])	Replacement for ListedColormap.
ContinuousColormap(*args[, gamma, alpha, cyclic])	Replacement for LinearSegmentedColormap.
PerceptualColormap(*args[, space, clip, ...])	A ContinuousColormap with linear transitions across hue, saturation, and luminance rather than red, blue, and green.
DiscreteNorm(levels[, norm, unique, step, ...])	Meta-normalizer that discretizes the possible color values returned by arbitrary continuous normalizers given a sequence of level boundaries.
DivergingNorm([vcenter, vmin, vmax, fair, clip])	Normalizer that ensures some central data value lies at the central colormap color.
SegmentedNorm(levels[, vmin, vmax, clip])	Normalizer that scales data linearly with respect to the interpolated index in an arbitrary monotonic level sequence.
ColorDatabase([mapping])	Dictionary subclass used to replace the builtin matplotlib color database.
ColormapDatabase(kwargs)	Dictionary subclass used to replace the matplotlib colormap registry.

Projection classes

Additional cartopy projection classes.

Aitoff([central_longitude, globe, ...])	The Aitoff projection.
Hammer([central_longitude, globe, ...])	The Hammer projection.
KavrayskiyVII([central_longitude, globe, ...])	The Kavrayskiy VII projection.
WinkelTripel([central_longitude, globe, ...])	The Winkel tripel (Winkel III) projection.
NorthPolarAzimuthalEquidistant([...])	Analogous to NorthPolarStereo.
SouthPolarAzimuthalEquidistant([...])	Analogous to SouthPolarStereo.
NorthPolarGnomonic([central_longitude, globe])	Analogous to NorthPolarStereo.
SouthPolarGnomonic([central_longitude, globe])	Analogous to SouthPolarStereo.
NorthPolarLambertAzimuthalEqualArea([...])	Analogous to NorthPolarStereo.
SouthPolarLambertAzimuthalEqualArea([...])	Analogous to SouthPolarStereo.

Demo functions

Functions for displaying colors and fonts.

show_cmaps(*args, **kwargs)	Generate a table of the registered colormaps or the input colormaps categorized by source.
show_channels(*args[, N, rgb, saturation, ...])	Show how arbitrary colormap(s) vary with respect to the hue, chroma, luminance, HSL saturation, and HPL saturation channels, and optionally the red, blue and green channels.
show_colors(*[, nhues, minsat, unknown, ...])	Generate tables of the registered color names.
show_colorspaces(*[, luminance, saturation, ...])	Generate hue-saturation, hue-luminance, and luminance-saturation cross-sections for the HCL, HSL, and HPL colorspaces.
show_cycles(*args, **kwargs)	Generate a table of registered color cycles or the input color cycles categorized by source.
show_fonts(*args[, family, user, text, ...])	Generate a table of fonts.

Miscellaneous functions

Various tools that may be useful while making plots.

arange(min_, *args)	Identical to numpy.arange but with inclusive endpoints.
edges(z[, axis])	Calculate the approximate "edge" values along an axis given "center" values.
edges2d(z)	Calculate the approximate "edge" values given a 2D grid of "center" values.
get_colors(*args, **kwargs)	Get the colors associated with a registered or on-the-fly color cycle or colormap.
set_hue(color, hue[, space])	Return a color with a different hue and the same luminance and saturation as the input color.
set_saturation(color, saturation[, space])	Return a color with a different saturation and the same hue and luminance as the input color.
set_luminance(color, luminance[, space])	Return a color with a different luminance and the same hue and saturation as the input color.
set_alpha(color, alpha)	Return a color with the opacity channel set to the specified value.
shift_hue(color[, shift, space])	Shift the hue channel of a color.
scale_saturation(color[, scale, space])	Scale the saturation channel of a color.
scale_luminance(color[, scale, space])	Scale the luminance channel of a color.
to_hex(color[, space, cycle, keep_alpha])	Translate the color from an arbitrary colorspace to a HEX string.
to_rgb(color[, space, cycle])	Translate the color from an arbitrary colorspace to an RGB tuple.
to_xyz(color[, space])	Translate color in any format to a tuple of channel values in any colorspace.
to_rgba(color[, space, cycle, clip])	Translate the color from an arbitrary colorspace to an RGBA tuple.
to_xyza(color[, space])	Translate color in any format to a tuple of channel values in any colorspace.
units(value[, numeric, dest, fontsize, ...])	Convert values between arbitrary physical units.