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:
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 anXYAxes
,PolarAxes
, orProjAxes
. Think of this as a dedicatedupdate
method for axes artists. See Formatting subplots and Changing rc settings for details.The
Figure
colorbar
andlegend
andAxes
colorbar
andlegend
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, andparametric
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
, orpandas.Series
object to any plotting command. This works just like the nativexarray.DataArray.plot
andpandas.DataFrame.plot
methods. See 1d plotting and 2d plotting for details.The
Proj
function lets you make arbitrary grids of basemapBasemap
and cartopyProjection
projections. It is used to interpret theproj
keyword arg passed tosubplots
. The resulting axes are instances ofProjAxes
withformat
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
andCycle
constructor functions can slice, merge, and modify colormaps and color cycles. See Colormaps, Color cycles, and Colors and fonts for details.The
LinearSegmentedColormap
andListedColormap
subclasses replace the default matplotlib colormap classes and add several methods. The newPerceptuallyUniformColormap
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
, andshow_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 newLinearSegmentedNorm
normalizer scales colors evenly w.r.t. index for arbitrarily spaced monotonic levels, and the newBinNorm
meta-normalizer is used to discretized colormap colors. See 2d plotting for details.The
Locator
,Formatter
, andScale
constructor functions, used to generate class instances from variable input types. These are used to interpret keyword arguments passed toformat
andcolorbar
. See X and Y axis settings for details.The
rc
object, an instance ofrc_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.