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 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 the figure and axes classes, check out this guide. Directly working with matplotlib classes 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 many ProPlot features may still work, we do not officially support the pyplot interface.

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 import ProPlot at the top of your script and do nothing else! We recommend importing ProPlot as follows:

import proplot as pplt

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

Figure and axes classes

Creating figures with ProPlot is very similar to matplotlib. You can either create the figure and all of its subplots at once:

fig, axs = pplt.subplots(...)

or create an empty figure then fill it with subplots:

fig = pplt.figure(...)
axs = fig.add_subplots(...)  # add several subplots
ax = fig.add_subplot(...)  # add a single subplot
# axs = fig.subplots(...)  # shorthand
# ax = fig.subplot(...)  # shorthand

These commands are modeled after matplotlib.pyplot.subplots and matplotlib.pyplot.figure and are packed with new features. One highlight is the auto_layout algorithm that automatically adjusts the space between subplots (similar to matplotlib’s tight layout) and automatically adjusts the figure size to preserve subplot sizes and aspect ratios (particularly useful for grids of map projections and images). All sizing arguments take arbitrary units, including metric units like cm and mm.

Instead of the native matplotlib.figure.Figure and matplotlib.axes.Axes classes, ProPlot uses the proplot.figure.Figure, proplot.axes.Axes, and proplot.axes.PlotAxes subclasses. ProPlot figures are saved with save or savefig, and ProPlot axes belong to one of the following three child classes:

Most of ProPlot’s features are implemented using these subclasses. They include several new figure and axes methods and added functionality to existing figure and axes methods.

Integration features

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 geographic plotting packages.

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

Additional features

Outside of the features provided by the proplot.figure.Figure and proplot.axes.Axes subclasses, ProPlot includes several useful classes and constructor functions.