API reference

Comprehensive documentation of ProPlot functions and classes. All of these objects are imported into the top-level namespace, so you can read the documentation within python sessions using help(pplt.<function_or_class>).

Top-level functions

The starting point for creating ProPlot figures.

subplots([array, ncols, nrows, order, ref, …])	Create a figure with a single subplot or arbitrary grids of subplots, analogous to matplotlib.pyplot.subplots.
SubplotsContainer([iterable, n, order])	List-like class and pseudo-2d array used for the subplots returned by subplots.
close(*args, **kwargs)	Call matplotlib.pyplot.close.
ion()	Call matplotlib.pyplot.ion.
ioff()	Call matplotlib.pyplot.ioff.
isinteractive()	Call matplotlib.pyplot.isinteractive.
show(*args, **kwargs)	Call matplotlib.pyplot.show.
switch_backend(*args, **kwargs)	Call matplotlib.pyplot.switch_backend.

Figure class

The figure class used for all ProPlot figures.

Figure([tight, ref, outerpad, innerpad, …])

The Figure class returned by subplots.

Axes classes

The axes classes used for all ProPlot figures.

Axes(*args[, number, main, _subplotspec])	Lowest-level axes subclass.
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 on cartographic projections.
CartopyAxes(*args[, autoextent, circular, …])	Axes subclass for plotting cartopy projections.
BasemapAxes(*args[, map_projection])	Axes subclass for plotting basemap projections.
Axes3D(*args, **kwargs)	Simple mix-in of proplot.axes.Axes with Axes3D.

Constructor functions

The constructor functions used to build class instances from simple shorthand arguments.

Colormap(*args[, name, listmode, to_listed, …])	Generate, retrieve, modify, and/or merge instances of PerceptuallyUniformColormap, LinearSegmentedColormap, and ListedColormap.
Colors(*args, **kwargs)	Pass all arguments to Cycle and return the list of colors from the resulting Cycler object.
Cycle(*args[, N, samples, name])	Generate and merge Cycler instances in a variety of ways.
Norm(norm, *args, **kwargs)	Return an arbitrary Normalize instance.
Formatter(formatter, *args[, date, index])	Return a Formatter instance.
Locator(locator, *args, **kwargs)	Return a Locator instance.
Scale(scale, *args, **kwargs)	Return a ScaleBase instance.
Proj(name[, basemap])	Return a cartopy.crs.Projection or Basemap instance.

Configuration tools

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

rc	Instance of RcConfigurator.
RcConfigurator([local, user, default])	Dictionary-like class for managing matplotlib’s builtin settings and ProPlot’s added settings.
register_cmaps([user, default])	Register colormaps packaged with ProPlot or saved to the ~/.proplot/cmaps folder.
register_cycles([user, default])	Register color cycles packaged with ProPlot or saved to the ~/.proplot/cycles folder.
register_colors([user, default, space, margin])	Register the open-color colors, XKCD color survey colors, and colors saved to the ~/.proplot/colors folder.
register_fonts()	Add fonts packaged with ProPlot or saved to the ~/.proplot/fonts folder, if they are not already added.
config_inline_backend([fmt])	Set up the ipython inline backend format and ensure that inline figures always look the same as saved figures.
use_style(style)	Apply the matplotlib style(s) with matplotlib.style.use.

Plotting wrappers

The plotting wrappers that add functionality to various Axes methods. “Wrapped” Axes methods accept the additional arguments documented in the wrapper function.

default_latlon(self, *args[, latlon])	Makes latlon=True the default for basemap plots.
default_transform(self, *args[, transform])	Makes transform=cartopy.crs.PlateCarree() the default for cartopy plots.
standardize_1d(self, *args[, data, autoformat])	Interpret positional arguments for the “1D” plotting methods so usage is consistent.
standardize_2d(self, *args[, data, …])	Interpret positional arguments for the “2D” plotting methods so usage is consistent.
indicate_error(self, *args[, mean, means, …])	Adds support for drawing error bars and error shading on-the-fly.
apply_cmap(self, *args[, cmap, cmap_kw, …])	Adds several new keyword args and features for specifying the colormap, levels, and normalizers.
apply_cycle(self, *args[, cycle, cycle_kw, …])	Adds features for controlling colors in the property cycler and drawing legends or colorbars in one go.
colorbar_extras(self, mappable[, values, …])	Adds useful features for controlling colorbars.
legend_extras(self[, handles, labels, loc, …])	Adds useful features for controlling legends, including “centered-row” legends.
text_extras(self[, x, y, s, transform, …])	Enables specifying tranform with a string name and adds a feature for drawing borders and bbox around text.
vlines_extras(self, *args, **kwargs)	Plot vertical lines with flexible positional arguments and optionally use different colors for “negative” and “positive” lines.
hlines_extras(self, *args, **kwargs)	Plot horizontal lines with flexible positional arguments and optionally use different colors for “negative” and “positive” lines.
scatter_extras(self, *args, **kwargs)	Support apply_cmap features and support keywords that are more consistent with plot keywords.
bar_extras(self, *args, **kwargs)	Support grouping and stacking successive columns of data, and changes the default bar style.
barh_extras(self, *args, **kwargs)	Support grouping and stacking successive columns of data, and changes the default bar style.
fill_between_extras(self, *args, **kwargs)	Support overlaying and stacking successive columns of data, and permits using different colors for “negative” and “positive” regions.
fill_betweenx_extras(self, *args, **kwargs)	Support overlaying and stacking successive columns of data, and permits using different colors for “negative” and “positive” regions.
boxplot_extras(self, *args[, mean, means, …])	Support convenient keyword arguments and change the default boxplot style.
violinplot_extras(self, *args[, fillcolor, …])	Adds convenient keyword arguments and changes the default violinplot style to match this matplotlib example.

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, saturation, rgb, …])	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, categories, …])	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, text, size, …])	Generate a table of fonts.

Colormaps and normalizers

New colormap classes and colormap normalization classes.

ListedColormap(*args[, alpha])	New base class for all ListedColormaps.
LinearSegmentedColormap(name, segmentdata[, …])	New base class for all LinearSegmentedColormaps.
PerceptuallyUniformColormap(name, segmentdata)	Similar to LinearSegmentedColormap, but instead of varying the RGB channels, we vary hue, saturation, and luminance in either the HCL colorspace or the HSL or HPL scalings of HCL.
DiscreteNorm(levels[, norm, cmap, unique, …])	Meta-normalizer that discretizes the possible color values returned by arbitrary continuous normalizers given a list of level boundaries.
DivergingNorm([vcenter, vmin, vmax, fair, clip])	Normalizer that ensures some central data value lies at the central colormap color.
LinearSegmentedNorm(levels[, vmin, vmax, clip])	Normalizer that scales data linearly with respect to average position in an arbitrary monotonically increasing level lists.
ColorDatabase(mapping)	Dictionary subclass used to replace the builtin matplotlib color database.
ColormapDatabase(kwargs)	Dictionary subclass used to replace the matplotlib colormap registry.

Locators and formatters

Various Locator and Formatter classes.

AutoFormatter([zerotrim, tickrange, …])	The new default formatter.
FracFormatter([symbol, number])	Format numbers as fractions or multiples of some arbitrary value.
LongitudeLocator(*args, **kwargs)	A locator for determining longitude gridlines.
LatitudeLocator(*args, **kwargs)	A locator for determining latitude gridlines.
SciFormatter([precision, zerotrim])	Format numbers with scientific notation.
SigFigFormatter([sigfig, zerotrim])	Rounds numbers to the specified number of significant digits.
SimpleFormatter([precision, zerotrim, …])	Replicate various features from AutoFormatter.

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(arg[, invert, parent_scale, …])	An axis scale comprised 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.

Cartopy projections

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.
NorthPolarAzimuthalEquidistant([…])	Analogous to NorthPolarStereo.
NorthPolarGnomonic([central_longitude, globe])	Analogous to NorthPolarStereo.
NorthPolarLambertAzimuthalEqualArea([…])	Analogous to NorthPolarStereo.
SouthPolarAzimuthalEquidistant([…])	Analogous to SouthPolarStereo.
SouthPolarGnomonic([central_longitude, globe])	Analogous to SouthPolarStereo.
SouthPolarLambertAzimuthalEqualArea([…])	Analogous to SouthPolarStereo.
WinkelTripel([central_longitude, globe, …])	The Winkel tripel (Winkel III) projection.

Gridspec classes

New gridspec and subplotspec classes.

GridSpec(figure[, nrows, ncols])	Matplotlib GridSpec subclass that allows for grids with variable spacing between successive rows and columns of axes.
SubplotSpec(gridspec, num1[, num2])	Matplotlib SubplotSpec subclass that adds some helpful methods.

Miscellaneous tools

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.
units(value[, dest, axes, figure, width])	Convert values and lists of values between arbitrary physical units.
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 in any format and from any colorspace to a HEX string.
to_rgb(color[, space, cycle])	Translate the color in any format and from any 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])	Translate the color in any format and from any colorspace to an RGB tuple.
to_xyza(color[, space])	Translate color in any format to a tuple of channel values in any colorspace.