Skip to content

usage.rst

Latest commit

 

History

History
247 lines (195 loc) · 11.3 KB

usage.rst

File metadata and controls

247 lines (195 loc) · 11.3 KB

Using UltraPlot

This page offers a condensed overview of UltraPlot's features. It is populated with links to the :ref:`API reference` and :ref:`User Guide <ug_basics>`. For a more in-depth discussion, see :ref:`why`.

Background

UltraPlot is an object-oriented matplotlib wrapper. The "wrapper" part means that UltraPlot's features are largely a superset of matplotlib. You can use plotting commands like :func:`~matplotlib.axes.Axes.plot`, :func:`~matplotlib.axes.Axes.scatter`, :func:`~matplotlib.axes.Axes.contour`, and :func:`~matplotlib.axes.Axes.pcolor` like you always have. The "object-oriented" part means that UltraPlot's features are implemented with subclasses of the :class:`~matplotlib.figure.Figure` and :class:`~matplotlib.axes.Axes` classes.

If you tend to use :obj:`~matplotlib.pyplot` and are not familiar with the figure and axes classes, check out this guide. Directly working with matplotlib classes tends to be more clear and concise than :obj:`~matplotlib.pyplot`, makes things easier when working with multiple figures and axes, and is certainly more "pythonic". Therefore, although many UltraPlot features may still work, we do not officially support the :obj:`~matplotlib.pyplot` interface.

Importing UltraPlot

Importing UltraPlot immediately adds several new :ref:`colormaps <ug_cmaps>`, :ref:`property cycles <ug_cycles>`, :ref:`color names <ug_colors>`, and :ref:`fonts <ug_fonts>` to matplotlib. If you are only interested in these features, you may want to import UltraPlot at the top of your script and do nothing else! We recommend importing UltraPlot as follows:

import ultraplot as uplt

This differentiates UltraPlot from the usual plt abbreviation reserved for the :obj:`~matplotlib.pyplot` module.

Figure and axes classes

Creating figures with UltraPlot is very similar to matplotlib. You can either create the figure and all of its subplots at once:

fig, axs = uplt.subplots(...)

or create an empty figure then fill it with subplots:

fig = uplt.figure(...)
axs = fig.add_subplots(...)  # add several subplots
ax = fig.add_subplot(...)  # add a single subplot
# axs = fig.subplots(...)  # shorthand
# ax = fig.subplot(...)  # shorthand

These commands are modeled after matplotlib.pyplot.subplots and matplotlib.pyplot.figure and are :ref:`packed with new features <ug_layout>`. One highlight is the :func:`~ultraplot.figure.Figure.auto_layout` algorithm that :ref:`automatically adjusts the space between subplots <ug_tight>` (similar to matplotlib's tight layout) and :ref:`automatically adjusts the figure size <ug_autosize>` to preserve subplot sizes and aspect ratios (particularly useful for grids of map projections and images). All sizing arguments take :ref:`arbitrary units <ug_units>`, including metric units like cm and mm.

Instead of the native matplotlib.figure.Figure and matplotlib.axes.Axes classes, UltraPlot uses the :class:`~ultraplot.figure.Figure`, :class:`~ultraplot.axes.Axes`, and :class:`~ultraplot.axes.PlotAxes` subclasses. UltraPlot figures are saved with :func:`~ultraplot.figure.Figure.save` or ~matplotlib.figure.Figure.savefig, and UltraPlot axes belong to one of the following three child classes:

Most of UltraPlot's features are implemented using these subclasses. They include several new figure and axes methods and added functionality to existing figure and axes methods.

Integration features

UltraPlot includes optional integration features with four external packages: the pandas and xarray packages, used for working with annotated tables and arrays, and the cartopy and basemap geographic plotting packages.

Since these features are optional, UltraPlot can be used without installing any of these packages.

External axes containers (mpltern, others)

UltraPlot can wrap third-party Matplotlib projections (e.g., mpltern's "ternary" projection) in a lightweight container. The container keeps UltraPlot's figure/labeling behaviors while delegating plotting calls to the external axes.

Basic usage mirrors standard subplots:

import mpltern
import ultraplot as uplt

fig, axs = uplt.subplots(ncols=2, projection="ternary")
axs.format(title="Ternary example", abc=True, abcloc="left")
axs[0].plot([0.1, 0.7, 0.2], [0.2, 0.2, 0.6], [0.7, 0.1, 0.2])
axs[1].scatter([0.2, 0.3], [0.5, 0.4], [0.3, 0.3])

Controlling the external content size

Use external_shrink_factor (or the rc setting external.shrink) to shrink the external axes inside the container, creating margin space for titles and annotations without resizing the subplot itself:

uplt.rc["external.shrink"] = 0.8
fig, axs = uplt.subplots(projection="ternary")
axs.format(external_shrink_factor=0.7)

Notes and performance

  • Titles and a-b-c labels are rendered by the container, not the external axes, so they behave like normal UltraPlot subplots.
  • For mpltern with external_shrink_factor < 1, UltraPlot skips the costly tight-bbox fitting pass and relies on the shrink factor for layout. This keeps rendering fast and stable.

Additional features

Outside of the features provided by the :class:`~ultraplot.figure.Figure` and :class:`~ultraplot.axes.Axes` subclasses, UltraPlot includes several useful classes and :ref:`constructor functions <why_constructor>`.