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
andmm
, 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
, andCycle
constructor functions, integrated with theformat
command,subplots
command, and plotting commands. More power and less boilerplate code. - Automatic axes, colorbar, and legend formatting when
xarray.DataArray
,pandas.DataFrame
, orpandas.Series
objects are passed to a plotting command, just like their respectiveplot
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.