A powerful, 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 (coming soon!). However, feel free to install directly from Github using:

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

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

I recommend importing ProPlot with

import proplot as plot

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

The documentation is published on readthedocs.

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.

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:

• A smarter "tight layout" feature. Figure width or height changed so that subplot aspect ratios are fixed. Inner space between subplots automatically scaled so subplot tick labels, etc. do not overlap. Arbitrary physical units (e.g. cm, mm) when specifying dimensions and sizes.
• 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.

This project can be thought of as "matplotlib for power users." Many of its features represent an alternative to the existing matplotlib API -- and following TOOWTDI philosophy, they should perhaps remain here as a side project. For example: the format and format_partial methods, which are meant to replace existing axes and axis methods.

There are also some philosophical differences and more direct conflicts. ProPlot enforces static figure scaffoldings, while matplotlib encourages successively adding axes to an existing figure instance. The "smart tight layout" feature conflicts directly with matplotlib's tight layout, with more options and the ability to preserve axes aspect ratios by sacrificing fixed figure dimensions. And much of subplots could be seen as a more flexible alternative to the axes_grid1 toolkit.

Despite all this, if there are any matplotlib developers out there that think some ProPlot features could be added to matplotlib directly, please contact me!

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, 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). ProPlot also uses the metadata from these special objects, and also gives you nice-looking plots out of the box -- but critically, it also permits a high level of cusomtization, 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.