Using 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

We recommend importing ProPlot as follows:

import proplot as plot

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

Importing ProPlot also configures your IPython environment by setting up the matplotlib backend and enabling the autoreload and autosave extensions (this feature can be disabled). See ipython_matplotlib, ipython_autoreload, and ipython_autosave for details.

Figure and axes classes

Making figures in ProPlot always begins with a call to the subplots command:

f, axs = plot.subplots(...)

subplots is modeled after matplotlib’s native matplotlib.pyplot.subplots command. It creates an instance of ProPlot’s Figure class populated with instances of ProPlot’s Axes classes. See The basics and Subplots features for details.

Each Axes returned by subplots belongs to one of the following three child classes:

  • XYAxes: For plotting simple data with x and y coordinates.

  • ProjAxes: For geographic plots with longitude and latitude coordinates.

  • PolarAxes: For polar plots with radius and azimuth coordinates.

See X and Y axis settings for details on working with XYAxes and Geographic and polar plots for details on working with ProjAxes and PolarAxes.

Figure and axes methods

The Figure and Axes subclasses include several brand new methods and add to the functionality of several existing methods.

Integration with other packages

ProPlot’s features are integrated with the data containers introduced by xarray and pandas and the cartopy and basemap geographic plotting toolkits.

New functions and classes

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