Usage overview

ProPlot is an object-oriented matplotlib wrapper, which means most of its features derive from subclasses of the Figure and Axes classes. If you tend to use the pyplot API and are not familiar with figure and axes “objects”, you should first take a look at this page. Using the objects directly tends to be more clear and concise than pyplot API, and makes life easier when working with multiple figures or axes.

Importing proplot

We recommend importing ProPlot with

import proplot as plot

This differentiates ProPlot from the usual plt abbreviation used for the pyplot module. Importing proplot immediately adds a bunch of new colormaps, property cyclers, color names, and fonts to matplotlib. See Colormaps, Color cycles, and Colors and fonts for details.

Figure and axes classes

ProPlot’s features derive from subplots, modeled after the native matplotlib.pyplot.subplots command. subplots creates a Figure subclass populated with special Axes subclasses. See Creating figures and Figure tight layout for details.

Each Axes class also belongs to one of the XYAxes, PolarAxes, or ProjAxes parent classes, depending on the projection used. See Geographic and polar plots for details.

The Figure and Axes subclasses include useful new methods and override several existing methods:

• The most important new method is format, whose behavior depends on whether the axes is an XYAxes, PolarAxes, or ProjAxes. This method fine-tunes various axes settings. See Customizing figures for details.

• The Figure colorbar and legend and Axes colorbar and legend commands are used to add colorbars and legends inside of subplots, along the outside edge of subplots, and along the edge of the figure. See Colorbars and legends for details.

• There is a huge variety of new features for working with contour plots, pcolor plots, heatmaps, line plots, error bars, bar plots, area plots, and parametric plots. See 1d plotting and 2d plotting for details.

Integration with other packages

ProPlot includes integration with xarray, pandas, cartopy, and basemap:

• Axis labels, tick labels, titles, colorbar labels, and legend labels are automatically applied when you pass an xarray.DataArray, pandas.DataFrame, or pandas.Series object to any plotting command. This works just like the native xarray.DataArray.plot and pandas.DataFrame.plot methods. See 1d plotting and 2d plotting for details.

• The Proj function lets you make arbitrary grids of basemap Basemap and cartopy Projection projections. It is used to interpret the proj keyword arg passed to subplots. The resulting axes are instances of ProjAxes with format methods that can be used to add geographic features and custom meridian and parallel gridlines. See Geographic and polar plots for details.

Other functions and classes

ProPlot includes a bunch of useful tools outside of the Figure and Axes subclasses:

• The Colormap and Cycle constructor functions. These can slice, merge, and modify colormaps and color cycles. See Colormaps, Color cycles, and Colors and fonts for details.

• The LinearSegmentedColormap and ListedColormap subclasses, used to wrap the default matplotlib colormaps, and the new PerceptuallyUniformColormap class, used for creating arbitrary colormaps with perceptually uniform transitions. See Colormaps for details.

• The Norm constructor function, used to generated colormap normalizers from shorthand names; the LinearSegmentedNorm normalizer, used to scale colors evenly w.r.t. index for arbitrarily spaced monotonic levels; and the BinNorm meta-normalizer, used to discretized colormap colors. See 2d plotting for details.

• The Locator, Formatter, and Scale constructor functions, used to generate class instances from variable input types. These are used to interpret keyword arguments passed to format and colorbar. See X and Y axis settings for details.

• The rc object, an instance of rc_configurator, for modifying global settings. You can also control settings with a ~/.proplotrc file. See Configuring proplot for details.