Figure#

anyplotlib.figure — Figure widget, grid spec, and subplots factory.

Classes

Figure

Multi-panel interactive figure widget.

Functions

subplots

Create a Figure and a grid of Axes.

Full Reference

class anyplotlib.figure.Figure(**kwargs)[source]

Bases: AnyWidget

Multi-panel interactive figure widget.

The top-level container for all plots and the only anywidget.AnyWidget subclass in anyplotlib. It owns all traitlets and acts as the Python ↔ JavaScript bridge via the figure_esm.js canvas renderer.

Create via subplots() (recommended) or directly:

fig = Figure(2, 2, figsize=(800, 600))
ax  = fig.add_subplot((0, 0))
v2d = ax.imshow(data)
Parameters:

  • nrows (int, optional) – Grid dimensions. Default 1 row, 1 column.

  • ncols (int, optional) – Grid dimensions. Default 1 row, 1 column.

  • figsize ((width, height), optional) – Figure size in CSS pixels. Default (640, 480).

  • width_ratios (list of float, optional) – Relative column widths. Length must equal ncols.

  • height_ratios (list of float, optional) – Relative row heights. Length must equal nrows.

  • sharex (bool, optional) – Link pan/zoom across all panels on the respective axis. Default False (independent pan/zoom per panel).

  • sharey (bool, optional) – Link pan/zoom across all panels on the respective axis. Default False (independent pan/zoom per panel).

See also

subplots

Recommended factory for creating Figure and Axes grid.

layout_json

A trait for unicode strings.

event_json

A trait for unicode strings.

fig_width

An int trait.

fig_height

An int trait.

display_stats

A boolean (True, False) trait.

help_text

A trait for unicode strings.

set_help(text)[source]

Set (or clear) the figure-level help text shown in the ? badge.

Parameters:

text (str) – Help string displayed when the user clicks the ? badge. Pass an empty string (or "" ) to remove the badge entirely. Newlines (\n) are respected in the card.

Return type:

None

Examples

>>> fig.set_help("Drag peak: move μ/A\nPress f: least-squares fit")
>>> fig.set_help("")   # hide the badge
subplots_adjust(hspace=None, wspace=None)[source]

Set the spacing between subplot panels.

Only the arguments that are explicitly provided are updated; omitting an argument leaves the current value unchanged.

Parameters:

  • hspace (float, optional) – Fraction of the average row height to use as vertical gap between panels. 0.1 adds a gap of 10 % of the mean row height. None (default) leaves the current hspace unchanged.

  • wspace (float, optional) – Fraction of the average column width to use as horizontal gap. None (default) leaves the current wspace unchanged.

Return type:

None

add_subplot(spec)[source]

Add a subplot cell and return its Axes.

Parameters:

spec (SubplotSpec or int or tuple of (row, col)) – Which grid cell(s) to occupy. A SubplotSpec is used directly (e.g. from GridSpec[r, c]). An int is converted via divmod(spec, ncols), matching matplotlib.Figure.add_subplot numbering. A (row, col) tuple selects a single cell.

Returns:

The subplot axes object. Call plotting methods like .imshow(), .plot(), .bar() to attach data.

Return type:

Axes

Raises:

TypeError – If spec is not a SubplotSpec, int, or tuple.

Examples

>>> fig = Figure(2, 2)
>>> ax1 = fig.add_subplot(0)       # top-left (via numbering)
>>> ax2 = fig.add_subplot((0, 1))  # top-right (via tuple)
batch()[source]

Coalesce all panel pushes within the block into one push per panel.

Use around multi-panel updates (e.g. a linked-view crosshair handler) so a single mouse event produces one serialise + transfer per panel instead of one per mutation — a large win under Pyodide / remote kernels where every push crosses a comm boundary.

with fig.batch():
    v_xz.set_data(slice_xz)
    v_yz.set_data(slice_yz)
    cross.set(cx=..., cy=...)
add_inset(w_frac, h_frac, *, corner='top-right', title='')[source]

Create and return a floating inset axes.

The inset overlays the figure at the specified corner. Call plot-factory methods on the returned InsetAxes to attach data:

inset = fig.add_inset(0.3, 0.25, corner="top-right", title="Zoom")
inset.imshow(data)    # returns Plot2D
inset.plot(profile)   # returns Plot1D
Parameters:

  • w_frac (float) – Width and height as fractions of the figure size (0–1).

  • h_frac (float) – Width and height as fractions of the figure size (0–1).

  • corner (str, optional) – Positioning corner: "top-right" (default), "top-left", "bottom-right", or "bottom-left".

  • title (str, optional) – Text displayed in the inset title bar.

Return type:

InsetAxes

get_axes()[source]

Return a list of all Axes, sorted by grid position.

Returns:

Axes sorted by (row_start, col_start) to match typical left-to-right, top-to-bottom iteration order.

Return type:

list of Axes

to_html(*, resizable=True)[source]

Return a self-contained HTML page rendering this figure.

The page inlines the JS renderer and all data — no Jupyter kernel or network needed at view time. Load it in any browser context, e.g. an Electron BrowserWindow or <webview>. See anyplotlib.embed for the full embedding guide (including live Python sync via FigureBridge).

Parameters:

resizable (bool)

Return type:

str

save_html(path, *, resizable=True)[source]

Write to_html() output to path; returns the Path.

Parameters:

resizable (bool)

close()[source]

Close the figure.

Fires a "close" event on every panel’s callbacks, then hides the widget by setting its CSS display to "none". Subsequent calls are no-ops.

Return type:

None

anyplotlib.figure.subplots(nrows=1, ncols=1, *, sharex=False, sharey=False, figsize=(640, 480), width_ratios=None, height_ratios=None, gridspec_kw=None, display_stats=False, help='')[source]

Create a Figure and a grid of Axes.

Mirrors matplotlib.pyplot.subplots().

Parameters:

  • nrows (int) – Number of rows and columns in the grid.

  • ncols (int) – Number of rows and columns in the grid.

  • sharex (bool) – Link pan/zoom across all panels on the respective axis.

  • sharey (bool) – Link pan/zoom across all panels on the respective axis.

  • figsize ((width, height)) – Figure size in CSS pixels. Default (640, 480).

  • width_ratios (list of float, optional) – Relative column widths. Equivalent to gridspec_kw={"width_ratios": ...}.

  • height_ratios (list of float, optional) – Relative row heights. Equivalent to gridspec_kw={"height_ratios": ...}.

  • gridspec_kw (dict, optional) – Extra keyword arguments forwarded to GridSpec. Recognised keys: width_ratios, height_ratios.

  • display_stats (bool, optional) – Show per-panel FPS / frame-time overlay. Default False.

  • help (str, optional) – Help text shown when the user clicks the ? badge on the figure. Newlines (\n) create separate lines in the card. The badge is hidden when help is empty (default). Suppressed globally when apl.show_help = False.

Returns:

  • fig (Figure)

  • axs (Axes or numpy array of Axes) –

    • Single cell → scalar Axes.

    • Single row → 1-D array of shape (ncols,).

    • Single column → 1-D array of shape (nrows,).

    • Otherwise → 2-D array of shape (nrows, ncols).

Examples

>>> import anyplotlib as apl
>>> import numpy as np
>>> fig, axs = apl.subplots(2, 1, figsize=(640, 600))
>>> v2d = axs[0].imshow(np.random.rand(128, 128))
>>> v1d = axs[1].plot(np.sin(np.linspace(0, 6.28, 256)))
>>> fig