API reference

Top-level functions

Primary functions used to interactively work with figures. Modeled after the pyplot versions.

close(*args, **kwargs)

Pass the input arguments to matplotlib.pyplot.close.


Call matplotlib.pyplot.show.

subplots([array, ncols, nrows, ref, order, …])

Create a figure with a single subplot or arbitrary grids of subplots, analogous to matplotlib.pyplot.subplots.

Figure classes

The figure class and a couple related classes.

subplot_grid(objs[, n, order])

List subclass and pseudo-2d array that is used as a container for the list of axes returned by subplots.

Figure([tight, ref, pad, axpad, panelpad, …])

The Figure class returned by subplots.

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.

Axes classes

The axes classes used for all ProPlot figures.

Axes(*args[, number, main])

Lowest-level axes subclass.

BasemapAxes(*args[, map_projection])

Axes subclass for plotting basemap projections.

GeoAxes(*args[, map_projection])

Axes subclass for plotting cartopy projections.

PolarAxes(*args, **kwargs)

Intermediate class, mixes ProjAxes with PolarAxes.

ProjAxes(*args, **kwargs)

Intermediate class, shared by GeoAxes and BasemapAxes.

XYAxes(*args, **kwargs)

Axes subclass for ordinary 2D cartesian coordinates.

Plotting wrappers

Wrapper functions applied to various Axes plotting methods. In a future version these features will be documented on the individual plotting methods, but for now they are documented separately.

add_errorbars(self, func, *args[, medians, …])

Wraps plot, scatter, bar, and violinplot, adds support for drawing error bars.

bar_wrapper(self, func[, x, height, width, …])

Wraps bar, permits bar stacking and bar grouping.

barh_wrapper(self, func[, y, width, height, …])

Wraps barh, usage is same as bar_wrapper.

boxplot_wrapper(self, func, *args[, color, …])

Wraps boxplot, adds convenient keyword args.

default_crs(self, func, *args[, crs])

Wraps get_extent, set_extent, set_xticks, and set_yticks for GeoAxes and fixes a set_extent bug associated with tight bounding boxes.

default_latlon(self, func, *args[, latlon])

Wraps plot, scatter, contour, contourf, pcolor, pcolormesh, quiver, streamplot, and barbs for BasemapAxes.

default_transform(self, func, *args[, transform])

Wraps plot, scatter, contour, contourf, pcolor, pcolormesh, quiver, streamplot, barbs, tripcolor, tricontour, and tricontourf for GeoAxes.

cmap_changer(self, func, *args[, cmap, …])

Wraps methods that take a cmap argument (parametric, hexbin, contour, contourf, pcolor, pcolormesh, quiver, streamplot, barbs, imshow, tripcolor, tricontour, tricontourf, hist2d, spy, and matshow), adds several new keyword args and features.

cycle_changer(self, func, *args[, cycle, …])

Wraps methods that use the property cycler (plot, scatter, bar, hist, boxplot, violinplot, fill_between, fill_betweenx, pie, stem, and step), adds features for controlling colors in the property cycler and drawing legends or colorbars in one go.

colorbar_wrapper(self, mappable[, values, …])

Wraps Axes colorbar and Figure colorbar, adds some handy features.

fill_between_wrapper(self, func, *args, **kwargs)

Wraps fill_between, also accessible via the area alias.

fill_betweenx_wrapper(self, func, *args, …)

Wraps fill_betweenx, also accessible via the areax alias.

hist_wrapper(self, func, x[, bins])

Wraps hist, enforces that all arguments after bins are keyword-only and sets the default patch linewidth to 0.

legend_wrapper(self[, handles, labels, …])

Wraps Axes legend and Figure legend, adds some handy features.

plot_wrapper(self, func, *args[, cmap, values])

Wraps plot, draws a “colormap line” if the cmap argument was passed.

scatter_wrapper(self, func, *args[, s, …])

Wraps scatter, adds optional keyword args more consistent with the plot keywords.

standardize_1d(self, func, *args, **kwargs)

Wraps parametric, plot, scatter, bar, hist, boxplot, violinplot, fill_between, fill_betweenx, pie, stem, step, and hexbin, standardizes acceptable positional args and optionally modifies the x axis label, y axis label, title, and axis ticks if a DataArray, DataFrame, or Series is passed.

standardize_2d(self, func, *args[, order, globe])

Wraps contour, contourf, pcolor, pcolormesh, quiver, streamplot, and barbs, standardizes acceptable positional args and optionally modifies the x axis label, y axis label, title, and axis ticks if the a DataArray, DataFrame, or Series is passed.

text_wrapper(self, func[, x, y, text, …])

Wraps text, and enables specifying tranform with a string name and adds feature for drawing borders around text.

violinplot_wrapper(self, func, *args[, lw, …])

Wraps violinplot, adds convenient keyword args.

Projection tools

New cartopy projection classes and a projection constructor function for generating Basemap and cartopy Projection classes.



Default keyword args for Basemap projections.


Mapping of “projection names” to cartopy Projection classes.


Proj(name[, basemap])

Returns a Basemap or cartopy.crs.Projection instance, used to interpret the proj and proj_kw arguments when passed to subplots.


Aitoff([central_longitude, globe, …])

The Aitoff projection.

Hammer([central_longitude, globe, …])

The Hammer projection.

KavrayskiyVII([central_longitude, globe, …])

The Kavrayskiy VII projection.


Analogous to NorthPolarStereo.

NorthPolarGnomonic([central_longitude, globe])

Analogous to SouthPolarStereo.


Analogous to NorthPolarStereo.


Analogous to SouthPolarStereo.

SouthPolarGnomonic([central_longitude, globe])

Analogous to SouthPolarStereo.


Analogous to SouthPolarStereo.

WinkelTripel([central_longitude, globe, …])

The Winkel tripel (Winkel III) projection.

Axis tools

Various axis Formatter and ScaleBase classes. Includes constructor functions so that these classes can be selected with a shorthand syntax.



Mapping of strings to Formatter classes.


Mapping of strings to Locator classes.


The registered scale names and their associated ScaleBase classes.


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.

FracFormatter([symbol, number])

Return a FuncFormatter that formats numbers as fractions or multiples of some arbitrary value.

SimpleFormatter(*args[, precision, zerotrim])

Return a FuncFormatter instance that replicates the zerotrim feature from AutoFormatter.


AutoFormatter(*args[, zerotrim, precision, …])

The new default formatter, a simple wrapper around ScalarFormatter.

CutoffScale(*args, **kwargs)

Axis scale composed of arbitrary piecewise linear transformations.

ExpScale([a, b, c, inverse, minpos])

“Exponential scale” that performs either of two transformations.

FuncScale(arg[, invert, parent_scale, …])

An axis scale comprised of arbitrary forward and inverse transformations.


Axis scale that is linear in the inverse of x.


As with LinearScale but with AutoFormatter as the default major formatter.


As with LogitScale but with AutoFormatter as the default major formatter.


As with LogScale but with AutoFormatter as the default major formatter.


Axis scale that transforms coordinates as with latitude in the Mercator projection.

PowerScale([power, inverse, minpos])

“Power scale” that performs the transformation


Axis scale that is linear in the sine of x.


As with SymmetricLogScale.

Color and font tools

Tools for registering and visualizing colormaps, color cycles, color string names, and fonts. New colormap classes, new colormap normalizer classes, and new constructor functions for generating instances of these classes. Related utilities for manipulating colors. See Colormaps, Color cycles, and Colors and fonts for details.



List of registered colormap names.


Lists of registered color names by category.


List of registered color cycle names.


Registered font names.


make_mapping_array(N, data[, gamma, inverse])

Similar to makeMappingArray but permits circular hue gradations along 0-360, disables clipping of out-of-bounds channel values, and uses fancier “gamma” scaling.


Register colormaps packaged with ProPlot or saved to the ~/.proplot/cmaps folder.


Add color names packaged with ProPlot or saved to the ~/.proplot/colors folder.


Register color cycles packaged with ProPlot or saved to the ~/.proplot/cycles folder.


Add fonts packaged with ProPlot or saved to the ~/.proplot/fonts folder, if they are not already added.

saturate(color[, scale])

Scale the saturation channel of the input color.

shade(color[, scale])

Scale the luminance channel of the input color.

show_cmaps(*args[, N])

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])

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.

to_rgb(color[, space, cycle, alpha])

Translate the color in any format and from any colorspace to an RGB tuple.

to_xyz(color[, space, alpha])

Translate color in any format to a tuple of channel values in any colorspace.

Colormap(*args[, name, listmode, fade, …])

Generate or retrieve colormaps and optionally merge and manipulate them in a variety of ways.

Colors(*args, **kwargs)

Pass all arguments to Cycle and return the list of colors from the resulting Cycler object.

Cycle(*args[, N, name, marker, alpha, …])

Generate and merge Cycler instances in a variety of ways.

Norm(norm[, levels])

Return an arbitrary Normalize instance.


BinNorm(levels[, norm, clip, step, extend])

This normalizer is used for all colormap plots.


Dictionary subclass used to replace the matplotlib.cm.cmap_d colormap dictionary.


This class overrides the builtin matplotlib color cache, allowing users to draw colors from named colormaps and color cycles for any plotting command that accepts a color keyword arg.

LinearSegmentedNorm(levels[, vmin, vmax])

This is the default normalizer paired with BinNorm whenever levels are non-linearly spaced.

LinearSegmentedColormap(*args[, cyclic, alpha])

New base class for all LinearSegmentedColormaps.

ListedColormap(*args[, alpha])

New base class for all ListedColormaps.

MidpointNorm([midpoint, vmin, vmax, clip])

Ensures a “midpoint” always lies at the central colormap color.

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.

Rc configuration tools

Utilities for configuring matplotlib and ProPlot global settings. See Configuring proplot for details.


Instance of rc_configurator.


Magical abstract class for managing matplotlib rcParams and additional ProPlot rcParamsLong and rcParamsShort settings.


Set up the ipython autosave utility by running the following ipython magic.


Set up the ipython autoreload utility by running the following ipython magic.

ipython_matplotlib([backend, fmt])

Set up the matplotlib backend for ipython sessions and apply the following %config InlineBackend magic commands.

Miscellaneous tools

Simple tools used in various places across this package.

arange(min_, *args)

Identical to numpy.arange but with inclusive endpoints.

edges(Z[, axis])

Calculate the approximate “edge” values along an arbitrary axis, given “center” values.


Like edges but for 2d arrays.

units(value[, units, axes, figure, width])

Convert values and lists of values between arbitrary physical units.