Usage overview¶
ProPlot is an object-oriented matplotlib wrapper, which means
most of its features derive from subclasses of the Figure
and Axes
classes. If you tend to use the pyplot
API and are not familiar with figure and axes “objects”, you should first take a look at this page. Using the objects directly tends to be more clear and concise than pyplot
API, and makes life easier when working with multiple figures or axes.
Importing proplot¶
We recommend importing ProPlot with
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¶
ProPlot’s features derive from subplots
, modeled after
the native matplotlib.pyplot.subplots
command.
subplots
creates a Figure
subclass
populated with special Axes
subclasses.
See Creating figures
and Figure tight layout for details.
Each Axes
class also belongs to
one of the XYAxes
, PolarAxes
,
or ProjAxes
parent classes, depending on the projection used. See
Geographic and polar plots for details.
The Figure
and Axes
subclasses
include useful new methods and override several existing methods:
The most important new method is
format
, whose behavior depends on whether the axes is anXYAxes
,PolarAxes
, orProjAxes
. This method fine-tunes various axes settings. See Customizing figures 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. See Colorbars and legends for details.There is a huge variety of new features for working with contour plots, pcolor plots, heatmaps, line plots, error bars, bar plots, area plots, and parametric plots. See 1d plotting and 2d plotting for details.
Integration with other packages¶
ProPlot includes integration with xarray
, pandas
, cartopy
, and basemap
:
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.
Other functions and classes¶
ProPlot includes a bunch of useful tools outside
of the Figure
and Axes
subclasses:
The
Colormap
andCycle
constructor functions. These can slice, merge, and modify colormaps and color cycles. See Colormaps, Color cycles, and Colors and fonts for details.The
LinearSegmentedColormap
andListedColormap
subclasses, used to wrap the default matplotlib colormaps, and the newPerceptuallyUniformColormap
class, used for creating arbitrary colormaps with perceptually uniform transitions. See Colormaps for details.The
Norm
constructor function, used to generated colormap normalizers from shorthand names; theLinearSegmentedNorm
normalizer, used to scale colors evenly w.r.t. index for arbitrarily spaced monotonic levels; and theBinNorm
meta-normalizer, 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
, for modifying global settings. You can also control settings with a~/.proplotrc
file. See Configuring proplot for details.