DOCSEARCHbyAlgolia
Submit Docs

Proplot Documentation

repository·master·Indexed 22 days ago

https://github.com/proplot-dev/proplot

A succinct matplotlib wrapper for creating publication-quality graphics. It provides specialized subclasses of matplotlib.figure.Figure and matplotlib.axes.Axes, a comprehensive configuration system via proplot.config.rc, and integrated support for geophysical plotting and custom colormaps. Note: development is currently halted; users are encouraged to use its successor, Ultraplot.

Tokens
18.1K
Snippets
43
Records
121
Agent score
76%

What's inside Proplot

  2. Note on proplot maintenance and Ultraplot

    master
    Development on proplot has been indefinitely halted since summer 2023. For a modernized version that supports recent versions of matplotlib, cartopy, and python, use Ultraplot, which is the spiritual successor to proplot.

  3. Handle colormaps and normalization

    master

    Proplot provides specialized colormap classes and automatic handling:

    • Colormap Types:
      • proplot.colors.ContinuousColormap (formerly LinearSegmentedColormap)
      • proplot.colors.PerceptualColormap (formerly PerceptuallyUniformColormap)
      • proplot.colors.DiscreteColormap (formerly ListedColormap)
    • Automatic Diverging Maps: If cmap.autodiverging is enabled, Proplot automatically applies proplot.colors.DivergingNorm based on input data when a diverging colormap is detected.
    • Robust Scaling: Use the robust keyword argument (or cmap.robust setting) to ignore outliers when selecting colormap ranges. It accepts True, a percentile range, or a 2-tuple percentile interval.
    • Discrete Handling: Passing colors=colors or qualitative=True triggers special qualitative colormap handling using DiscreteNorm.

  4. Work with Pint quantities and Xarray data

    master

    Proplot has built-in support for physical units and data structures:

    • Pint Integration: Passing pint.Quantity arguments automatically applies setup_matplotlib with the quantity's unit registry. You can also use proplot.utils.units(num, 'in', 'cm') for manual conversion.
    • Xarray Support: Proplot can accept xarray.DataArray arguments. It automatically accesses the .data attribute rather than .values to preserve metadata and units.
    • Unit Formatting: Use the unitformat setting to control how pint.Quantity default unit labels are formatted on plots.

  5. Use DiscreteLocator for colorbar ticks

    master
    In version 0.10.0, Proplot introduced proplot.ticker.DiscreteLocator. This is used for major/minor discrete colorbar ticks and automatically updates tick selection whenever the axes are drawn. It is an alternative to matplotlib's FixedLocator that allows ticking from a subset of fixed values. You can also register it as 'discrete' in proplot.constructor.Locator.

  6. Use physical units for spacing and sizing

    master

    Proplot replaces Matplotlib's relative figure/axes units with a physical units engine (proplot.utils.units), allowing for more intuitive layout control.

    GridSpec Spacing

    The following proplot.gridspec.GridSpec keywords accept physical units:

    • left, right, top, bottom
    • wspace, hspace
    • pad, outerpad, innerpad

    By default, numeric arguments are treated as em-widths.

    Figure Sizing

    The following proplot.figure.Figure keywords accept physical units:

    • figsize, figwidth, figheight, refwidth, refheight

    Supported Units

    Acceptable units include:

    • inches
    • centimeters
    • millimeters
    • pixels
    • points
    • picas

    Proplot also translates these units when assigned to proplot.config.rc_matplotlib and proplot.config.rc_proplot settings (e.g., subplots.refwidth, legend.columnspacing, axes.labelpad).

  7. Use custom colormaps and color cycles in Proplot

    master

    Proplot provides tools to manage and display colormaps and color cycles:

    • Loading from files: You can load colormaps from files using proplot.styletools.LinearSegmentedColormap.from_file. You can also pass a name directly to proplot.styletools.Colormap to load it.
    • Shifting colormaps: You can shift an arbitrary colormap by 180 degrees by appending _shifted to its name (e.g., 'viridis_shifted'), similar to the matplotlib _r suffix.
    • Displaying tools: Use proplot.styletools.show_cmaps and proplot.styletools.show_cycles to visualize available colormaps and color cycles. In newer versions, these display using colorbars rather than lines.

  8. Use PlotAxes methods instead of deprecated wrapper functions

    master

    In Proplot versions 0.8.0 and later, many former top-level 'wrapper' functions have been moved directly onto the proplot.axes.PlotAxes class.

    Instead of using standalone functions like standardize_1d or cmap_changer, you should use the corresponding methods on your axes object (e.g., ax.plot() or ax.pcolor()).

  9. Manage flexible global settings with proplot.config.rc

    master

    Proplot provides a unified proplot.config.rc object to manage both native matplotlib settings (via proplot.config.rc_matplotlib) and additional proplot-specific settings (via proplot.config.rc_proplot).

    Key Features

    • Validation: All assigned settings are automatically validated.
    • Meta Settings: You can use "meta" settings to update multiple related properties at once. Examples include meta.edgecolor, meta.linewidth, and font.smallsize.
    • Persistence: You can save modified settings to a file using proplot.config.Configurator.save (check proplot.config.Configurator.changed to see what has been modified) and load settings using proplot.config.Configurator.load.

    Ways to change settings

    You can modify settings using several methods:

    • Direct assignment: pplt.rc.key = value or pplt.rc[key] = value
    • Bulk update: pplt.rc.update(key=value)
    • Via Axes: Using proplot.axes.Axes.format
    • Context management: Using proplot.config.Configurator.context
    import proplot as pplt

# Direct assignment
pplt.rc.font.size = 12

# Bulk update
pplt.rc.update(font.size=12, axes.linewidth=1.5)

# Using meta settings to update multiple properties
pplt.rc.meta.edgecolor = 'red'
pplt.rc.meta.linewidth = 2

  10. Understanding proplot axes types

    master

    Proplot axes are subclasses of proplot.axes.PlotAxes. Depending on the coordinate system required, they fall into one of three main categories:

    1. proplot.axes.CartesianAxes: For standard plots with x and y coordinates.
    2. proplot.axes.GeoAxes: For geographic plots using longitude and latitude coordinates.
    3. proplot.axes.PolarAxes: For polar plots using azimuth and radius coordinates.

    Most proplot features are implemented through these subclasses, providing enhanced functionality to standard plotting commands like .plot(), .scatter(), .bar(), .area(), .box(), .violin(), .contour(), .pcolor(), and .imshow().

  11. How Proplot integrates with Matplotlib

    master

    Proplot is not a standalone library used separately from Matplotlib; instead, it is built directly into the Matplotlib API. It achieves this by providing specialized subclasses of:

    • matplotlib.figure.Figure
    • matplotlib.axes.Axes

    This allows users to leverage Proplot's enhanced features (like improved layout algorithms and specialized formatting) while remaining within the standard Matplotlib ecosystem.

  12. Integrate Pandas, Xarray, and Pint with Proplot

    master

    Proplot provides native support for scientific data containers like xarray.DataArray, pandas.DataFrame, pandas.Series, and pint.Quantity. Unlike standard Matplotlib, Proplot automatically extracts metadata from these objects to populate axis labels, tick labels, subplot titles, colorbar labels, and legend labels.

    Key features include:

    • Automatic Metadata Mapping: Labels are automatically updated from the container's metadata.
    • Pint Integration: For pint.Quantity objects, Proplot automatically generates unit strings based on the unitformat setting. It also handles pint.UnitRegistry.setup_matplotlib automatically for $x$ and $y$ coordinates.
    • Advanced Plotting: Reproduces features like grouped/stacked bar plots and area plots from 2D input data directly on proplot.axes.PlotAxes commands.
    • On-the-fly Guides: Supports colorbar and legend keywords for automatic guide placement.

    You can disable this automatic behavior by setting autoformat=False in the global configuration or by passing autoformat=False as a keyword argument to any plotting command.