A comprehensive, easy-to-use matplotlib wrapper for making beautiful, publication-quality graphics.

This package is a work-in-progress. Currently there is no formal release on PyPi (ETA: January 2020). However, feel free to install directly from Github using:

pip install git+https://github.com/lukelbd/proplot.git

To upgrade to the latest version, run pip uninstall proplot, then re-install.

The dependencies are matplotlib and numpy. The optional geographic mapping features require cartopy and/or basemap.

The documentation is published on readthedocs.

I recommend importing ProPlot with

import proplot as plot

This differentiates ProPlot from the usual "plt" abbreviation used for the pyplot module.

Importing ProPlot registers a bunch of new colormaps and color names. If this is all you want and you don't care about other features, simply import ProPlot at the top of your script. See the documentation for details.

Most of ProPlot's features derive from the subplots command, inspired by the pyplot command of the same name. This generates a scaffolding of specially subclassed axes, and has a bunch of other useful features.

The next most important utility is the format method, available on every axes generated by subplots. Use this method to fine-tune your axis properties, titles, labels, limits, and much more.

Here are some highlights of the remaining features:

• Improvements to and automatic application of the tight layout feature. Figure width and height is allowed to vary so that subplot aspect ratios remain fixed, which is particularly useful for grids of map projections and images. Arbitrary physical units, including metric units like cm and mm, can be used for sizing arguments.
• Axes panels and figure panels, generally used for colorbars and legends that refer to multiple subplots at once. New "inset" colorbars. Colorbars from lists of lines or colors. Legends with centered rows instead of aligned columns.
• Helpful Locator, Formatter, Scale, Proj, Norm, Colormap, and Cycle constructor functions, integrated with the format command, subplots command, and plotting commands. More power and less boilerplate code.
• Automatic axes, colorbar, and legend formatting when xarray.DataArray, pandas.DataFrame, or pandas.Series objects are passed to a plotting command, just like their respective plot methods.
• Beautiful new colormaps, named "color cycles", and easy-to-remember color names. Tools for merging colormaps and making new "perceptually uniform" colormaps on-the-fly. Tools for slicing and modifying existing colormaps.
• Global setting customization with a user .proplotrc file. Save custom colormaps, color cycles, and fonts in a user .proplot folder, and they will be loaded every time on startup.
• Integration with basemap and cartopy. Generate arbitrary grids of arbitrary map projections in one go. Switch between the cartopy and basemap backends painlessly. Simplified plotting commands. Add geographic features and custom meridian and parallel gridlines and labels with the format command.

You can thank bradyrx for getting this project in working order and helping me fix a lot of the initial bugs. If your field is atmospheric science, check out his awesome decadal climate prediction package.

There is already a great matplotlib wrapper called seaborn, and pandas and xarray both offer convenient matplotlib plotting commands. What makes this project different?

While parts of ProPlot were inspired by these projects (in particular, rctools.py and colortools.py are modeled after seaborn), the goals are largely different. Seaborn, pandas, and xarray offer tools for generating rigid, simple, nice-looking plots from data stored in special objects (pandas.DataFrame and xarray.DataArray). Similarly, ProPlot uses metadata from these special objects and gives you nice-looking plots out of the box -- but critically, it also permits a high level of customization, permits building complex grids of subplots, and includes powerful tools for working with colors and geographic datasets. While seaborn, pandas, and xarray are meant to be used separately from the matplotlib API, ProPlot is built into the matplotlib API, thanks to special subclasses of the native matplotlib Figure and Axes classes.

In summary, this project is intended to unify the convenience of seaborn, pandas, and xarray plotting with the power and customizability of the underlying matplotlib API.

Certain parts of ProPlot conflict directly with the matplotlib API. ProPlot enforces a static figure layout with the entire subplot grid declared at figure creation time, so that we can implement subplot panels, exert more control on the subplot layout, and replace matplotlib's GridSpec class with the FlexibleGridSpec class. By contrast, matplotlib encourages successively adding subplots and panels to existing figures. ProPlot's "smart tight layout" conflicts with matplotlib's tight layout feature by permitting flexible figure dimensions to preserve subplot aspect ratios and by permitting variable subplot spacing with the FlexibleGridSpec class.

Other parts of ProPlot would arguably make the matplotlib API redundant if implemented directly. For example, Axes.format is convenient, but the same tasks can be accomplished with existing axes and axis "setter" methods. Also, some of the functionality of subplots can be replicated with axes_grid1. Following TOOWTDI philosophy, ProPlot should probably remain here as a separate project.

Nevertheless, if there are any core matplotlib developers reading this, and you think that some of ProPlot's features should be added to matplotlib, please contact me!

At well over 10,000 lines of code, this package took a huge amount of time to write and an equally huge amount of time to share online -- especially with my day job as a graduate student. If ProPlot has been useful for you, consider clicking the "donate" badge and sending me a small donation.