Using ProPlot

This page offers a condensed overview of ProPlot’s features. It is populated with links to the API reference and User Guide. For a more in-depth discussion, see Why ProPlot?

Background

ProPlot is an object-oriented matplotlib wrapper. The “wrapper” part means that ProPlot’s features are largely a superset of matplotlib. You can use your favorite plotting commands like plot, scatter, contour, and pcolor like you always have. The “object-oriented” part means that ProPlot’s features are implemented with subclasses of the Figure and Axes classes.

If you tend to use pyplot and are not familiar with figure and axes classes, check out this guide. from the matplotlib documentation. Working with objects directly tends to be more clear and concise than pyplot, makes things easier when working with multiple figures and axes, and is certainly more “pythonic”. Therefore, although some ProPlot features may still work, we do not officially support the pyplot API.

Importing proplot

Importing ProPlot immediately adds several new colormaps, property cycles, color names, and fonts to matplotlib. If you are only interested in these features, you may want to simply import ProPlot at the top of your script and do nothing else! We recommend importing ProPlot as follows:

  1. import proplot as plot

This differentiates ProPlot from the usual plt abbreviation reserved for the pyplot module.

Figure and axes classes

Creating plots with ProPlot always begins with a call to the subplots command:

  1. fig, axs = plot.subplots(...)

The subplots command is modeled after matplotlib’s native matplotlib.pyplot.subplots command and is packed with new features.

Instead of native matplotlib.figure.Figure and matplotlib.axes.Axes classes, subplots returns an instance of the proplot.figure.Figure subclass populated with instances of proplot.axes.Axes subclasses. Also, all ProPlot axes belong to one of the following three child classes:

Most of ProPlot’s features are added via the figure and axes subclasses. They include several brand new methods and add to the functionality of several existing methods.

Integration with other packages

ProPlot includes optional integration features with four external packages: the pandas and xarray packages, used for working with annotated tables and arrays, and the cartopy and basemap cartographic plotting packages.

Since these features are optional, ProPlot can be used without installing any of these packages.

New functions and classes

Outside of the Figure and Axes subclasses, ProPlot includes several useful constructor functions and subclasses.