An easy-to-use matplotlib wrapper that can help you make 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 with

import proplot as plot

to differentiate ProPlot from the usual "plt" abbreviation used for the pyplot module.

The documentation is published here.

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:

• Specify figure, axes, panel, etc. sizes with arbitrary physical units -- not just inches or "relative" units.
• A smarter "tight layout" feature. Figure width or height alternately scales so that subplot aspect ratios are fixed, inner space between subplots automatically scaled so subplot tick labels, etc. do not overlap with each other.
• Axes panels and figure panels, for global colorbars, global legends, or tertiary data. Panel widths always held fixed during "tight layout" scaling.
• 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.
• Easy setting customization with a user .proplotrc file. Option to save custom colormaps, and they will be loaded every time on startup.
• Perceptually distinct named colors with easy-to-remember names, a ton of beautiful new colormaps, new property cycle colors.
• Tools for merging existing colormaps and making new "perceptually uniform" colormaps on-the-fly. Tools for slicing and modifying existing colormaps.
• Making colorbars from lists of lines or colors. Making axes "inset" colorbars. Making legends with centered rows instead of aligned columns.
• Integration with basemap and cartopy. Generate arbitrary grids of arbitrary map projections in one go. Switch between the cartopy and basemap backends painlessly. Use the axes methods directly for basemap plotting, instead of the Basemap object.
• Add geographic features with the format command. Customize geographic gridlines and gridline labels.

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 convenience plotting tools offered by pandas and xarray. What makes this project different?

While parts of ProPlot were inspired by these wrappers, the goals are largely different. Seaborn, pandas, and xarray introduce new functions for generating useful visualizations quickly, and they require your data to be stored in special objects (pandas.DataFrame and xarray.DataArray) to be effective. ProPlot includes this automation as an option and gives you nice-looking plots out of the box -- but critically, it also permits the user to build highly customized plots and complex grids of subplots, and allows users to work painlessly with geographic data. While existing projects exist as separate toolsets on top of matplotlib, ProPlot is built right 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.

This entire package has so far been written by just me -- but I have a day job as a graduate student. If you have any ideas for new features or come across any bugs, I'd love to receive a pull request!

Shout out to bradyrx for being the guinea pig and helping me fix a lot of initial bugs. If your field is atmospheric science, check out his awesome decadal climate prediction package.

At well over 10,000 lines of code, this package took a huge amount of time to write and document. If ProPlot has been useful for you, consider sending me a small donation.