Advanced control and Matplotlib interoperability#

The concise API handles common publication work. Advanced functions expose explicit layout, styling, colored-artist, configuration, and output controls without replacing Matplotlib’s object model.

Keep ambient Matplotlib behavior#

Disable gsplot’s paper size, layout, or style explicitly when integrating with an existing application:

fig, ax = gs.subplots(size=None, layout="none", style=None)

For a reused Figure, omitted automatic values preserve its existing size, layout, and style. clear=False prevents accidental destruction of artists.

Mix native Matplotlib and gsplot#

import matplotlib.pyplot as plt
import gsplot as gs

fig, ax = plt.subplots()
ax.plot(x, reference, color="0.5", label="reference")
gs.line(ax, x, measured, series=0, label="measured")
gs.label(ax, "time (s)", "response")
gs.legend(ax)
fig.canvas.draw()

gsplot returns ordinary Matplotlib artists. Continue using Axes, Figure, and Artist methods directly whenever that is clearer.

Finite advanced operations#

  • style_axes, AxisSpec, minor_ticks, box_aspect, panel_labels, and set_theme expose explicit styling plans.

  • cmap_line, cmap_dash, cmap_scatter, sample_cmap, and cmap_legend cover data-mapped colors.

  • inset_axes with InsetSpec supports placement beyond concise normalized bounds.

  • read_array exposes the reviewed NumPy loader option mapping.

  • savefig retains conservative one-format output and explicit advanced Matplotlib save properties. save is the concise PNG+PDF workflow.

The compatibility-only props mapping remains accepted through 1.x, but new line, scatter, and legend calls should use their typed direct options. Unknown options and duplicate short/long aliases fail before artist mutation.

Colormap legends#

cmap_legend adds native Matplotlib Legend entries whose handle is a horizontal gradient of adjacent rectangles. stripes is clamped to 256, and reverse=True reverses the final left-to-right RGBA sequence. label, cmap, stripes, and reverse accept one shared value or one value per row, so two gradients stay visible in one Legend after a single call; norm stays shared by every row. Repeated labeled calls on the same Axes append rows in call order instead; replace=True resets to the requested entries. Set presentation properties on the first call: appended calls accept none. A later gs.legend call on the same Axes absorbs recorded gradient rows instead: fresh line entries and gradient rows interleave in creation order (each row follows the labeled entries already present when it was created; reverse permutes the fresh entries while rows stay pinned), in one native Legend owned by the legend call; gs.legends absorbs per Axes the same way. Extending gradient rows after such a merge means re-issuing the row batch, because merged Legends carry no row record and nothing is silently dropped. With label=None, the function returns an empty native Legend. Appending to a foreign or ambiguous existing Legend still requires replace=True: in particular cmap_legend after an ordinary legend raises, so write cmap_legend calls first. A merged Legend replaces the absorbed one, so only the newly returned Legend object is live; measure and move that object, never a previously returned one.

fig, ax = gs.subplots()
gs.cmap_legend(ax, label=["4.7 K", "4.8 K"], cmap=["viridis", "plasma"], stripes=100)

The deprecated gsplot.legend_colormap and gsplot.style.legend_colormap.legend_colormap routes retain the historical num_stripes, vmin, and vmax arguments, including positional calls. Their finite raw values are passed directly to the colormap as linspace(vmin, vmax, N_effective); this is intentionally different from the canonical synthetic [0, 1] positions and norm behavior. The legacy function always safely replaces the current Legend because it has no replace argument. Neither route mutates Matplotlib’s default handler map or adds an invisible proxy patch to the Axes.

Automatic gradient Legends for cmap_line, cmap_dash, cmap_scatter, and the legacy colored plotter classes are outside this compatibility repair and remain a separate task.

Multiple figures and lifecycle#

Every operation receives its target explicitly. Keep each Figure reference, save or show the intended Figure, and close Figures that your script owns:

import matplotlib.pyplot as plt
import gsplot as gs

first, ax1 = gs.subplots()
second, ax2 = gs.subplots()
gs.line(ax1, x, y1)
gs.line(ax2, x, y2)
gs.save(first, "first", show=False)
gs.save(second, "second", show=False)
plt.close(first)
plt.close(second)

show(target) is display-only. save(..., close=True) is available only when show=False; gsplot never silently closes a displayed user-owned Figure.