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:
proplot.axes.CartesianAxes
: For ordinary plots with x and y coordinates.proplot.axes.GeoAxes
: For geographic plots with longitude and latitude coordinates.proplot.axes.PolarAxes
: For polar plots with azimuth and radius coordinates.
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.
The
proplot.axes.Axes.format
andproplot.figure.Figure.format
commands fine-tunes various axes and figure settings. Think of this as a dedicatedupdate
method for axes and figures. See formatting subplots for a broad overview, along with the individual sections on formatting Cartesian plots, geographic plots, and polar plots.The
proplot.axes.Axes.colorbar
andproplot.axes.Axes.legend
commands draw colorbars and legends inside of subplots or along the outside edges of subplots. Theproplot.figure.Figure.colorbar
andproplot.figure.Figure.legend
commands draw colorbars or legends along the edges of figures (aligned by subplot boundaries). These commands considerably simplify the process of drawing colorbars and legends.The
proplot.axes.PlotAxes
subclass (used for all proplot axes) adds many, many useful features to virtually every plotting command (includingplot
,scatter
,bar
,area
,box
,violin
,contour
,pcolor
, andimshow
). See the 1D plotting and 2D plotting sections for details.
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.
If you pass a
pandas.Series
,pandas.DataFrame
, orxarray.DataArray
to any plotting command, the axis labels, tick labels, titles, colorbar labels, and legend labels are automatically applied from the metadata. If you did not supply the x and y coordinates, they are also inferred from the metadata. This works just like the nativexarray.DataArray.plot
andpandas.DataFrame.plot
methods. A demonstration of this feature is given in the sections on 1D plotting and 2D plotting. This feature can be disabled by settingrc.autoformat
toFalse
.The
GeoAxes
class uses the cartopy or basemap packages to plot geophysical data, add geographic features, and format projections.GeoAxes
provides provides a simpler, cleaner interface than the original cartopy and basemap interfaces. Figures can be filled withGeoAxes
by passing theproj
keyword tosubplots
.
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.
The
Colormap
andCycle
constructor functions can be used to slice, and merge existing colormaps and color cycles. It can also make new colormaps and color cycles from scratch.The
ContinuousColormap
andDiscreteColormap
subclasses replace the default matplotlib colormap classes and add several methods. The newPerceptualColormap
class is used to make colormaps with perceptually uniform transitions.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 newSegmentedNorm
normalizer scales colors evenly w.r.t. index for arbitrarily spaced monotonic levels, and the newDiscreteNorm
meta-normalizer is used to break up colormap colors into discrete levels.The
Locator
,Formatter
, andScale
constructor functions return corresponding class instances from flexible input types. These are used to interpret keyword arguments passed toformat
, and can be used to quickly and easily modify x and y axis settings.The
rc
object, an instance ofConfigurator
, 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 withinline_backend_fmt
so that your inline figures look the same as your saved figures.