Why UltraPlot?#
Matplotlib is an incredibly powerful plotting engine, but creating multi-panel, publication-ready figures often requires repetitive boilerplate code. UltraPlot solves this by adding a concise, intuitive layer for layout and formatting, while letting you keep the familiar Matplotlib object-oriented methods you already know.
Note
If you just need a quick, exploratory plot, vanilla Matplotlib is perfect. UltraPlot truly shines when you are managing multi-panel figures or need consistent, publication-quality styling across your work.
The comparison below uses a straightforward two-panel figure to illustrate the difference. This isn’t about code golf or minimizing lines; it’s about the separation of concerns. Matplotlib handles the plotting primitives, while UltraPlot gives you a streamlined syntax to orchestrate the broader figure layout.
Setting up the data#
To keep things fully reproducible without needing external downloads, we will generate some basic synthetic data locally. The data itself is intentionally simple so we can focus entirely on the plotting mechanics.
[1]:
import numpy as np
rng = np.random.RandomState(51423)
x = np.linspace(0, 10, 100)
line = np.sin(x) + 0.08 * rng.randn(x.size)
image = np.outer(np.sin(x / 2), np.cos(x / 3))
The Matplotlib approach#
Matplotlib’s explicit API is fantastic when you need surgical control over every individual artist on the canvas. Here is how you would conventionally build and format this two-panel figure using standard Matplotlib.
For a deep dive into this approach, see the Matplotlib subplots tutorial.
[2]:
import matplotlib.pyplot as plt
mpl_fig, mpl_axs = plt.subplots(1, 2, figsize=(7, 3), constrained_layout=True)
mpl_axs[0].plot(x, line, label="signal", color="tab:blue")
mpl_axs[0].set(xlabel="x", ylabel="value", title="Line")
mpl_axs[0].legend(loc="upper right")
mpl_mesh = mpl_axs[1].imshow(image, origin="lower", aspect="auto", cmap="viridis")
mpl_axs[1].set(xlabel="column", ylabel="row", title="Image")
mpl_fig.colorbar(mpl_mesh, ax=mpl_axs[1], label="intensity")
mpl_fig.suptitle("The same two-panel figure")
mpl_fig.show()
The UltraPlot approach#
Notice that the actual drawing commands,
plot() and
imshow(), are identical to the Matplotlib
version above. UltraPlot adds subplots() for figure
construction and format() for panel formatting.
Instead of scattering setter methods across your script, UltraPlot lets you define figure layouts and shared labels cohesively. As your figures grow in complexity, this centralized formatting keeps your code clean and readable.
Discover more in the format command guide and the
subplots() API reference.
[3]:
import ultraplot as uplt
fig, ax = uplt.subplots(ncols=2, share=False, refwidth=2.3)
ax[0].plot(x, line, label="signal", color="tab:blue")
ax[1].imshow(
image,
origin="lower",
aspect="auto",
cmap="viridis",
colorbar="r",
colorbar_kw=dict(label="Intensity"),
)
ax.format(
title=["Line", "Image"],
xlabel=["x", "column"],
ylabel=["value", "row"],
)
ax[0].legend(loc="ur")
fig.format(suptitle="The same two-panel figure")
fig.show()
The takeaway#
UltraPlot does not reinvent the wheel—it just makes it easier to steer. A good mental model for your workflow looks like this:
Use standard axes methods such as
plot(),imshow(), andscatter()to draw data.Use
format()throughaxs.format()to apply consistent labels, ticks, and styling at the panel level.Use
format()throughfig.format()for global aesthetics, andcolorbar()for a shared colorbar.
For a single, fast plot, stick with Matplotlib. When layout scaling and repetitive formatting become a chore, let UltraPlot handle the heavy lifting.