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

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

import proplot as plot
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.

• The new format method is used to fine-tune various axes settings. Its behavior depends on whether the axes is an XYAxes, PolarAxes, or ProjAxes. Think of this as a dedicated update method for axes artists. See The format command 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. They considerably simplify the process of drawing colorbars and legends. See Colorbars and legends for details.

• ProPlot adds a huge variety of features for working with contour plots, pcolor plots, plot lines, heatmap plots, errorbar bars, bar plots, area plots, and parametric plots. See 1d plotting and 2d plotting for details.

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.

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

New functions and classes

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

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

• The LinearSegmentedColormap and ListedColormap subclasses replace the default matplotlib colormap classes and add several methods. The new PerceptuallyUniformColormap class is used to make colormaps with perceptually uniform transitions. See Colormaps for details.

• The show_cmaps, show_cycles, show_colors, show_fonts, show_channels, and show_colorspaces functions are used to visualize your color scheme and font options and inspect individual colormaps.

• The Norm constructor function generates colormap normalizers from shorthand names. The new LinearSegmentedNorm normalizer scales colors evenly w.r.t. index for arbitrarily spaced monotonic levels, and the new BinNorm meta-normalizer is 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, is used for modifying individual global settings, changing settings in bulk, and temporarily changing settings in context blocks. You can also control settings with a ~/.proplotrc file. See Configuring proplot for details.