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?
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
pcolor like you always have. The “object-oriented”
part means that ProPlot’s features are implemented with subclasses of the
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
although some ProPlot features may still work, we do not officially support
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:
import proplot as plot
This differentiates ProPlot from the usual
plt abbreviation reserved for
Figure and axes classes¶
Creating plots with ProPlot always begins with a call to the
fig, axs = plot.subplots(...)
subplots command is modeled after
and is packed with new features.
Instead of native
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:
proplot.axes.CartesianAxes: For plotting ordinary data with x and y coordinates.
proplot.axes.GeoAxes: For geographic plots with longitude and latitude coordinates.
proplot.axes.PolarAxes: For polar plots with radius and azimuth coordinates.
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.
formatmethod is used to fine-tune various axes settings. Think of this as a dedicated
updatemethod for axes artists. See formatting subplots for a broad overview, along with the individual sections on formatting Cartesian plots, polar plots, and geographic projections.
proplot.axes.Axes.legendcommands are used to add colorbars and legends inside of subplots and along the outside edge of subplots. The
proplot.figure.Figure.legendcommands are used to draw colorbars and legends along the edge of an entire figure, centered between subplot boundaries. These commands considerably simplify the process of drawing colorbars and legends.
ProPlot adds a huge variety of features for working with the
parametricplotting methods by “wrapping” them. See the 1D plotting and 2D plotting sections for details.
Integration with other packages¶
ProPlot includes optional integration features with four external
xarray packages, used for working with annotated
tables and arrays, and the
When you pass a
xarray.DataArrayto any plotting command, the axis labels, tick labels, titles, colorbar labels, and legend labels are automatically applied from the metadata. This works just like the native
pandas.DataFrame.plotmethods. A demonstration of this feature is given in the sections on 1D plotting and 2D plotting.
GeoAxesclass uses the
basemappackages to plot geophysical data, add geographic features, and format projections. This is a much simpler, smoother interface than the original
basemapinterfaces. Figures can be filled with
GeoAxesby using the
projkeyword argument with
Since these features are optional, ProPlot can be used without installing any of these packages.
New functions and classes¶
Outside of the
ProPlot includes several useful constructor functions and subclasses.
Cycleconstructor functions can be used to slice, and merge existing colormaps and color cycles. It can also make new colormaps and color cycles from scratch.
ListedColormapsubclasses replace the default matplotlib colormap classes and add several methods. The new
PerceptuallyUniformColormapclass is used to make colormaps with perceptually uniform transitions.
show_colorspacesfunctions are used to visualize your color scheme and font options and inspect individual colormaps.
Normconstructor function generates colormap normalizers from shorthand names. The new
LinearSegmentedNormnormalizer scales colors evenly w.r.t. index for arbitrarily spaced monotonic levels, and the new
DiscreteNormmeta-normalizer is used to break up colormap colors into discrete levels.
Scaleconstructor functions return corresponding class instances from flexible input types. These are used to interpret keyword arguments passed to
format, and can be used to quickly and easily modify x and y axis settings.
rcobject, an instance of
RcConfigurator, is used for modifying individual settings, changing settings in bulk, and temporarily changing settings in context blocks. It also introduces several new setings and sets up the inline plotting backend with
inline_backend_fmtso that your inline figures look the same as your saved figures.