API reference

Top-level functions

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

close(*args, **kwargs)

Call matplotlib.pyplot.close.

show()

Call matplotlib.pyplot.show.

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

Analogous to matplotlib.pyplot.subplots, creates a figure with a single axes or arbitrary grids of axes, any of which can be map projections.

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, lists of figure panels, and lists of stacked axes panels.

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

The Figure class returned by subplots.

GridSpec(figure[, nrows, ncols])

GridSpec generalization that allows for grids with variable spacing between successive rows and columns of axes.

SubplotSpec(gridspec, num1[, num2])

Adds two helper methods to SubplotSpec that return the geometry excluding rows and columns allocated for spaces.

Axes classes

The axes classes used for all ProPlot figures.

Axes(*args[, number, sharex, sharey, spanx, …])

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

Plotting wrappers applied to various Axes plotting methods. In a future version these features will be integrated more closely with the individual plotting methods and documented on the plotting methods themselves, 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 related tools. Includes projection constructor function for generating Basemap and cartopy Projection classes with their PROJ.4 string name aliases, just like basemap.

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.

NorthPolarLambertAzimuthalEqualArea([…])

Analogous to NorthPolarStereo.

SouthPolarAzimuthalEquidistant([…])

Analogous to SouthPolarStereo.

SouthPolarLambertAzimuthalEqualArea([…])

Analogous to SouthPolarStereo.

WinkelTripel([central_longitude, globe])

The Winkel tripel (Winkel III) projection.

Functions

Proj(name[, basemap])

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

Variables

basemap_rc

Default keyword args for Basemap projections.

cartopy_projs

Mapping of “projection names” to cartopy Projection classes.

Axis tools

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

Classes

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

The new default formatter, a simple wrapper around ScalarFormatter.

CutoffScale(axis, scale, lower[, upper])

Axis scale with arbitrary cutoffs that “accelerate” parts of the axis, “decelerate” parts of the axes, or discretely jumps between numbers.

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

An “exponential scale”.

FuncScale(axis, functions[, transform, …])

Arbitrary scale with user-supplied forward and inverse functions and arbitrary additional transform applied thereafter.

InverseScale(axis, **kwargs)

Scales axis to be linear in the inverse of x.

LinearScale(axis, **kwargs)

As with LinearScale, but applies new default major formatter.

LogitScale(axis[, nonpos])

As with LogitScale, but applies new default major formatter.

LogScale(axis, **kwargs)

As with LogScale, but applies new default major formatter and fixes the inexplicable choice to have separate “x” and “y” versions of each keyword argument.

MercatorLatitudeScale(axis, *[, thresh])

Scales axis as with latitude in the Mercator projection.

PowerScale(axis[, power, inverse, minpos])

Returns a “power scale” that performs the transformation

SineLatitudeScale(axis)

Scales axis to be linear in the sine of x in degrees.

SymmetricalLogScale(axis, **kwargs)

As with SymmetricLogScale, but applies new default major formatter and fixes the inexplicable choice to have separate “x” and “y” versions of each keyword argument.

Functions

Formatter(formatter, *args[, date])

Returns a Formatter instance, used to interpret the xformatter, xformatter_kw, yformatter, and yformatter_kw arguments when passed to format, and the formatter and formatter_kw arguments when passed to colorbar methods wrapped by colorbar_wrapper.

Locator(locator, *args, **kwargs)

Returns a Locator instance, used to interpret the xlocator, xlocator_kw, ylocator, ylocator_kw, xminorlocator, xminorlocator_kw, yminorlocator, and yminorlocator_kw arguments when passed to format, and the locator, locator_kw minorlocator, and minorlocator_kw arguments when passed to colorbar methods wrapped by colorbar_wrapper.

Scale(scale, *args, **kwargs)

Returns a ScaleBase instance, used to interpret the xscale, xscale_kw, yscale, and yscale_kw arguments when passed to format.

FracFormatter([symbol, number])

Returns a FuncFormatter that formats numbers as fractions or multiples of some value, e.g.

SimpleFormatter(*args[, precision, prefix, …])

Replicates features of AutoFormatter, but as a simpler FuncFormatter instance.

Variables

formatters

Mapping of strings to Formatter classes.

locators

Mapping of strings to Locator classes.

scales

The registered scale names and their associated ScaleBase classes.

Color and font tools

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

Classes

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

This normalizer is used for all colormap plots.

CmapDict(kwargs)

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

ColorCacheDict

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.

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 HSLuv or HPLuv scalings of HCL.

ListedColormap(*args[, alpha])

New base class for all ListedColormaps.

LinearSegmentedColormap(*args[, alpha, cyclic])

New base class for all LinearSegmentedColormaps.

Functions

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

Generates or retrieves colormaps and optionally merges and manipulates them in a variety of ways; used to interpret the cmap and cmap_kw arguments when passed to any plotting method wrapped by cmap_wrapper.

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

Function for generating and merging Cycler instances in a variety of ways; used to interpret the cycle and cycle_kw arguments when passed to any plotting method wrapped by cycle_wrapper.

Norm(norm[, levels])

Returns an arbitrary Normalize instance, used to interpret the norm and norm_kw arguments when passed to any plotting method wrapped by cmap_wrapper.

colors(*args, **kwargs)

Identical to Cycle, but returns a list of colors instead of a Cycler object.

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

Mostly a copy of makeMappingArray, but allows circular hue gradations along 0-360, disables clipping of out-of-bounds channel values, and with fancier “gamma” scaling.

register_cmaps()

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

register_colors([nmax])

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

register_cycles()

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

register_fonts()

Adds fonts packaged with ProPlot or saved to the ~/.proplot/fonts folder.

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, length, width, unknown])

Visualizes all registered colormaps, or the list of colormap names if positional arguments are passed.

show_channels(*args[, N, rgb, saturation, …])

Shows 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([nbreak, minsat])

Visualizes the registered color names in two figures.

show_colorspaces([luminance, saturation, …])

Generates hue-saturation, hue-luminance, and luminance-saturation cross-sections for the HCL, HSLuv, and HPLuv colorspaces.

show_cycles(*args[, axwidth])

Visualizes all registered color cycles, or the list of cycle names if positional arguments are passed.

show_fonts([fonts, size])

Displays table of the fonts installed by ProPlot or in the user-supplied fonts list.

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

Translate 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.

Variables

cmaps

List of new registered colormap names.

cycles

List of registered color cycle names.

colordict

Registered color names by category.

fonts

All registered font names.

fonts_system

Names of fonts provided by matplotlib or your operating system.

fonts_proplot

Names of fonts added by ProPlot.

Rc configuration tools

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

rc

Instance of rc_configurator.

rc_configurator()

Magical abstract class for managing matplotlib rcParams settings, ProPlot rcParamsLong settings, and rcParamsShort “global” settings.

ipython_autosave([autosave])

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

ipython_autoreload([autoreload])

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(array[, axis])

Calculate approximate “edge” values given “center” values.

edges2d(z)

Like edges but for 2d arrays.

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

Convert values and lists of values between arbitrary physical units.