Figure Plots#

figure_plots.py#

Pure-Python plot objects returned by Axes.imshow() / Axes.plot().

These are NOT anywidget subclasses. They hold all state in plain dicts and push changes into the parent Figure’s per-panel traitlet via _push().

Public classes#

GridSpec – describes a grid layout (nrows x ncols, ratios). SubplotSpec – a slice of a GridSpec (row/col spans). Axes – a grid cell; .imshow() / .plot() return a plot object. Plot2D – 2-D image panel, full Viewer2D-compatible API. Plot1D – 1-D line panel, full Viewer1D-compatible API.

class anyplotlib.figure_plots.GridSpec(nrows, ncols, *, width_ratios=None, height_ratios=None)[source]#

Bases: object

Define a grid of subplot cells.

Parameters:

nrows (int) – Grid dimensions.
ncols (int) – Grid dimensions.
width_ratios (list of float, optional) – Relative column widths (length ncols). Defaults to equal widths.
height_ratios (list of float, optional) – Relative row heights (length nrows). Defaults to equal heights.

Examples

>>> gs = GridSpec(2, 3, width_ratios=[2, 1, 1])
>>> spec = gs[0, :]          # top row spanning all columns
>>> spec = gs[1, 1:3]        # bottom-right 2 columns

class anyplotlib.figure_plots.SubplotSpec(gs, row_start, row_stop, col_start, col_stop)[source]#

Bases: object

Describes which grid cells a subplot occupies.

Parameters:

gs (GridSpec)
row_start (int)
row_stop (int)
col_start (int)
col_stop (int)

class anyplotlib.figure_plots.Axes(fig, spec)[source]#

Bases: object

A single grid cell in a Figure.

Returned by Figure.add_subplot() and Figure.subplots(). Call .imshow() or .plot() to attach a data plot and get back a Plot2D or Plot1D object.

Parameters:

fig (Figure)
spec (SubplotSpec)

imshow(data, axes=None, units='px')[source]#

Attach a 2-D image to this axes cell.

Parameters:

data (np.ndarray shape (H, W) or (H, W, C))
axes ([x_axis, y_axis], optional)
units (str, optional)

Return type:

Plot2D

pcolormesh(data, x_edges=None, y_edges=None, units='')[source]#

Attach a 2-D mesh to this axes cell using edge coordinates.

Follows the matplotlib pcolormesh convention: x_edges and y_edges are the cell edge coordinates, so they have length N+1 and M+1 respectively for an (M, N) data array.

Parameters:

data (np.ndarray shape (M, N))
x_edges (array-like, length N+1, optional) – Column edge coordinates. Defaults to np.arange(N+1).
y_edges (array-like, length M+1, optional) – Row edge coordinates. Defaults to np.arange(M+1).
units (str, optional)

Return type:

PlotMesh

plot_surface(X, Y, Z, *, colormap='viridis', x_label='x', y_label='y', z_label='z', azimuth=-60.0, elevation=30.0, zoom=1.0)[source]#

Attach a 3-D surface to this axes cell.

Parameters:

X (array-like) – 2-D grid arrays of the same shape (e.g. from np.meshgrid), or 1-D centre arrays for X/Y with a 2-D Z.
Y (array-like) – 2-D grid arrays of the same shape (e.g. from np.meshgrid), or 1-D centre arrays for X/Y with a 2-D Z.
Z (array-like) – 2-D grid arrays of the same shape (e.g. from np.meshgrid), or 1-D centre arrays for X/Y with a 2-D Z.
colormap (str, optional Matplotlib colormap name. Default 'viridis'.)
x_label (str, optional Axis labels.)
y_label (str, optional Axis labels.)
z_label (str, optional Axis labels.)
azimuth (float, optional Initial camera angles in degrees.)
elevation (float, optional Initial camera angles in degrees.)
zoom (float, optional Initial zoom factor.)

Return type:

Plot3D

scatter3d(x, y, z, *, color='#4fc3f7', point_size=4.0, x_label='x', y_label='y', z_label='z', azimuth=-60.0, elevation=30.0, zoom=1.0)[source]#

Attach a 3-D scatter plot to this axes cell.

Parameters:

x (array-like, shape (N,) Point coordinates.)
y (array-like, shape (N,) Point coordinates.)
z (array-like, shape (N,) Point coordinates.)
color (str, optional CSS colour for all points.)
point_size (float, optional Radius of each point in pixels.)
x_label (str, optional Axis labels.)
y_label (str, optional Axis labels.)
z_label (str, optional Axis labels.)
azimuth (float, optional Initial camera angles in degrees.)
elevation (float, optional Initial camera angles in degrees.)
zoom (float, optional Initial zoom factor.)

Return type:

Plot3D

plot3d(x, y, z, *, color='#4fc3f7', linewidth=1.5, x_label='x', y_label='y', z_label='z', azimuth=-60.0, elevation=30.0, zoom=1.0)[source]#

Attach a 3-D line plot to this axes cell.

Parameters:

x (array-like, shape (N,) Point coordinates along the line.)
y (array-like, shape (N,) Point coordinates along the line.)
z (array-like, shape (N,) Point coordinates along the line.)
color (str, optional CSS colour.)
linewidth (float, optional Stroke width in pixels.)
x_label (str, optional Axis labels.)
y_label (str, optional Axis labels.)
z_label (str, optional Axis labels.)
azimuth (float, optional Initial camera angles in degrees.)
elevation (float, optional Initial camera angles in degrees.)
zoom (float, optional Initial zoom factor.)

Return type:

Plot3D

plot(data, axes=None, units='px', y_units='', color='#4fc3f7', linewidth=1.5, label='')[source]#

Attach a 1-D line to this axes cell.

Parameters:

data (np.ndarray shape (N,))
axes ([x_axis], optional)
units (str, optional)
y_units (str, optional)
color (str, optional)
linewidth (float, optional)
label (str, optional)

Return type:

Plot1D

bar(values, x_labels=None, x_centers=None, color='#4fc3f7', colors=None, bar_width=0.7, orient='v', baseline=0.0, show_values=False, units='', y_units='')[source]#

Attach a bar chart to this axes cell.

Parameters:

values (array-like, shape (N,)) – Bar heights (vertical) or widths (horizontal).
x_labels (list of str, optional) – Category labels for each bar. Shown on the categorical axis instead of numeric tick values.
x_centers (array-like, optional) – Numeric positions of bar centres. Defaults to 0, 1, … N-1.
color (str, optional) – Single CSS colour applied to every bar. Default "#4fc3f7".
colors (list of str, optional) – Per-bar colour list; overrides color where provided.
bar_width (float, optional) – Bar width as a fraction of the slot width (0–1). Default 0.7.
orient ("v" | "h", optional) – Vertical (default) or horizontal orientation.
baseline (float, optional) – Value at which bars are rooted. Default 0.
show_values (bool, optional) – Draw the numeric value above / beside each bar.
units (str, optional) – Label for the categorical axis.
y_units (str, optional) – Label for the value axis.

Return type:

PlotBar

class anyplotlib.figure_plots.Plot1D(data, x_axis=None, units='px', y_units='', color='#4fc3f7', linewidth=1.5, label='')[source]#

Bases: object

1-D line plot panel.

Holds state in _state dict; every mutation pushes to Figure trait. Exposes the full Viewer1D-compatible API plus the new marker API.

Parameters:

data (np.ndarray)
units (str)
y_units (str)
color (str)
linewidth (float)
label (str)

to_state_dict()[source]#

Return type:: dict

update(data, x_axis=None, units=None, y_units=None)[source]#

Parameters:

data (ndarray)
units (str | None)
y_units (str | None)

Return type:

None

add_line(data, x_axis=None, color='#ffffff', linewidth=1.5, label='')[source]#

Parameters:

data (ndarray)
color (str)
linewidth (float)
label (str)

Return type:

str

remove_line(lid)[source]#

Parameters:: lid (str)
Return type:: None

clear_lines()[source]#

Return type:: None

add_span(v0, v1, axis='x', color=None)[source]#

Parameters:

v0 (float)
v1 (float)
axis (str)
color (str | None)

Return type:

str

remove_span(sid)[source]#

Parameters:: sid (str)
Return type:: None

clear_spans()[source]#

Return type:: None

add_vline_widget(x, color='#00e5ff')[source]#

Parameters:

x (float)
color (str)

Return type:

VLineWidget

add_hline_widget(y, color='#00e5ff')[source]#

Parameters:

y (float)
color (str)

Return type:

HLineWidget

add_range_widget(x0, x1, color='#00e5ff')[source]#

Parameters:

x0 (float)
x1 (float)
color (str)

Return type:

RangeWidget

get_widget(wid)[source]#

Return the Widget object by ID string or Widget instance.

Return type:: Widget

remove_widget(wid)[source]#

Remove a widget by ID string or Widget instance.

Return type:: None

list_widgets()[source]#

Return type:: list

clear_widgets()[source]#

Return type:: None

on_changed(fn)[source]#

Decorator: fires on every drag/zoom frame on this panel.

Parameters:: fn (Callable)
Return type:: Callable

on_release(fn)[source]#

Decorator: fires once when drag/zoom settles on this panel.

Parameters:: fn (Callable)
Return type:: Callable

on_click(fn)[source]#

Decorator: fires on click on this panel.

Parameters:: fn (Callable)
Return type:: Callable

on_key(key_or_fn=None)[source]#

Two call forms are supported:

@plot.on_key('q')          # fires only when 'q' is pressed
def handler(event): ...

@plot.on_key               # fires for every registered key
def handler(event): ...

The event carries: key, mouse_x, mouse_y, phys_x, and last_widget_id.

Note

Registered keys take priority over the built-in r (reset view) shortcut.

Return type:: Callable

disconnect(cid)[source]#

Remove the callback registered under integer cid.

Parameters:: cid (int)
Return type:: None

set_view(x0=None, x1=None)[source]#

Parameters:

x0 (float | None)
x1 (float | None)

Return type:

None

reset_view()[source]#

Return type:: None

add_circles(offsets, name=None, *, radius=5, facecolors=None, edgecolors='#ff0000', linewidths=1.5, alpha=0.3, hover_edgecolors=None, hover_facecolors=None, labels=None, label=None)[source]#

Return type:: MarkerGroup

add_points(offsets, name=None, *, sizes=5, color='#ff0000', facecolors=None, linewidths=1.5, alpha=0.3, hover_edgecolors=None, hover_facecolors=None, labels=None, label=None)[source]#

Add point markers at (x, y) positions in data coordinates.

Return type:: MarkerGroup

add_hlines(y_values, name=None, *, color='#ff0000', linewidths=1.5, hover_edgecolors=None, labels=None, label=None)[source]#

Add static horizontal lines at the given y positions.

Return type:: MarkerGroup

add_vlines(x_values, name=None, *, color='#ff0000', linewidths=1.5, hover_edgecolors=None, labels=None, label=None)[source]#

Add static vertical lines at the given x positions.

Return type:: MarkerGroup

add_arrows(offsets, U, V, name=None, *, edgecolors='#ff0000', linewidths=1.5, hover_edgecolors=None, labels=None, label=None)[source]#

Return type:: MarkerGroup

add_ellipses(offsets, widths, heights, name=None, *, angles=0, facecolors=None, edgecolors='#ff0000', linewidths=1.5, alpha=0.3, hover_edgecolors=None, hover_facecolors=None, labels=None, label=None)[source]#

Return type:: MarkerGroup

add_lines(segments, name=None, *, edgecolors='#ff0000', linewidths=1.5, hover_edgecolors=None, labels=None, label=None)[source]#

Return type:: MarkerGroup

add_rectangles(offsets, widths, heights, name=None, *, angles=0, facecolors=None, edgecolors='#ff0000', linewidths=1.5, alpha=0.3, hover_edgecolors=None, hover_facecolors=None, labels=None, label=None)[source]#

Return type:: MarkerGroup

add_squares(offsets, widths, name=None, *, angles=0, facecolors=None, edgecolors='#ff0000', linewidths=1.5, alpha=0.3, hover_edgecolors=None, hover_facecolors=None, labels=None, label=None)[source]#

Return type:: MarkerGroup

add_polygons(vertices_list, name=None, *, facecolors=None, edgecolors='#ff0000', linewidths=1.5, alpha=0.3, hover_edgecolors=None, hover_facecolors=None, labels=None, label=None)[source]#

Return type:: MarkerGroup

add_texts(offsets, texts, name=None, *, color='#ff0000', fontsize=12, hover_edgecolors=None, labels=None, label=None)[source]#

Return type:: MarkerGroup

remove_marker(marker_type, name)[source]#

Parameters:

marker_type (str)
name (str)

Return type:

None

clear_markers()[source]#

Return type:: None

list_markers()[source]#

Return type:: list

class anyplotlib.figure_plots.Plot2D(data, x_axis=None, y_axis=None, units='px')[source]#

Bases: object

2-D image plot panel.

Not an anywidget. Holds state in _state dict; every mutation calls _push() which writes to the parent Figure’s panel trait.

The marker API follows matplotlib conventions:: plot.add_circles(offsets, name=”g1”, facecolors=”#f00”, radius=5) plot.markers[“circles”][“g1”].set(radius=8)

Parameters:

data (np.ndarray)
units (str)

to_state_dict()[source]#

Return a JSON-serialisable copy of the current state.

Return type:: dict

update(data, x_axis=None, y_axis=None, units=None)[source]#

Replace the image data.

Parameters:

data (ndarray)
units (str | None)

Return type:

None

set_colormap(name)[source]#

Parameters:: name (str)
Return type:: None

set_clim(vmin=None, vmax=None)[source]#

Return type:: None

set_scale_mode(mode)[source]#

Parameters:: mode (str)
Return type:: None

property colormap_name: str#

add_widget(kind, color='#00e5ff', **kwargs)[source]#

Parameters:

kind (str)
color (str)

Return type:

Widget

get_widget(wid)[source]#

Return the Widget object by ID string or Widget instance.

Return type:: Widget

remove_widget(wid)[source]#

Remove a widget by ID string or Widget instance.

Return type:: None

list_widgets()[source]#

Return type:: list

clear_widgets()[source]#

Return type:: None

on_changed(fn)[source]#

Decorator: fires on every pan/zoom/drag frame on this panel.

Parameters:: fn (Callable)
Return type:: Callable

on_release(fn)[source]#

Decorator: fires once when pan/zoom/drag settles on this panel.

Parameters:: fn (Callable)
Return type:: Callable

on_click(fn)[source]#

Decorator: fires on click on this panel.

Parameters:: fn (Callable)
Return type:: Callable

on_key(key_or_fn=None)[source]#

Two call forms are supported:

@plot.on_key('q')          # fires only when 'q' is pressed
def handler(event): ...

@plot.on_key               # fires for every registered key
def handler(event): ...

The event carries: key, mouse_x, mouse_y, phys_x, and last_widget_id.

Note

Registered keys take priority over the built-in r (reset view) shortcut.

Return type:: Callable

disconnect(cid)[source]#

Remove the callback registered under integer cid.

Parameters:: cid (int)
Return type:: None

set_view(x0=None, x1=None, y0=None, y1=None)[source]#

Set the viewport to a data-space rectangle.

Parameters:

x0 (float, optional) – Horizontal data-space range to show. If omitted the full x-extent is used for zoom calculation.
x1 (float, optional) – Horizontal data-space range to show. If omitted the full x-extent is used for zoom calculation.
y0 (float, optional) – Vertical data-space range to show. If omitted the full y-extent is used for zoom calculation.
y1 (float, optional) – Vertical data-space range to show. If omitted the full y-extent is used for zoom calculation.
center_x (Translates the requested rectangle into the zoom /)
renderer. (/ center_y state values used by the 2-D JS)

Return type:

None

reset_view()[source]#

Reset pan and zoom to show the full image.

Return type:: None

Add circle markers at (x, y) positions in data coordinates.

Return type:: MarkerGroup

Add point markers at (x, y) positions in data coordinates.

Return type:: MarkerGroup

add_hlines(y_values, name=None, *, color='#ff0000', linewidths=1.5, hover_edgecolors=None, labels=None, label=None)[source]#

Add static horizontal lines at the given y positions.

Return type:: MarkerGroup

add_vlines(x_values, name=None, *, color='#ff0000', linewidths=1.5, hover_edgecolors=None, labels=None, label=None)[source]#

Add static vertical lines at the given x positions.

Return type:: MarkerGroup

add_arrows(offsets, U, V, name=None, *, edgecolors='#ff0000', linewidths=1.5, hover_edgecolors=None, labels=None, label=None)[source]#

Return type:: MarkerGroup

Return type:: MarkerGroup

add_lines(segments, name=None, *, edgecolors='#ff0000', linewidths=1.5, hover_edgecolors=None, labels=None, label=None)[source]#

Return type:: MarkerGroup

Return type:: MarkerGroup

Return type:: MarkerGroup

Return type:: MarkerGroup

add_texts(offsets, texts, name=None, *, color='#ff0000', fontsize=12, hover_edgecolors=None, labels=None, label=None)[source]#

Return type:: MarkerGroup

remove_marker(marker_type, name)[source]#

Parameters:

marker_type (str)
name (str)

Return type:

None

clear_markers()[source]#

Return type:: None

list_markers()[source]#

Return type:: list

class anyplotlib.figure_plots.PlotMesh(data, x_edges=None, y_edges=None, units='')[source]#

Bases: Plot2D

2-D mesh plot panel created by Axes.pcolormesh().

Accepts cell edge arrays (length N+1 / M+1) rather than centre arrays, matches matplotlib’s pcolormesh convention. Only 'circles' and 'lines' markers are supported.

Parameters:

data (np.ndarray)
units (str)

update(data, x_edges=None, y_edges=None, units=None)[source]#

Replace the mesh data (and optionally the edge arrays).

Parameters:

data (ndarray)
units (str | None)

Return type:

None

class anyplotlib.figure_plots.Plot3D(geom_type, x, y, z, *, colormap='viridis', color='#4fc3f7', point_size=4.0, linewidth=1.5, x_label='x', y_label='y', z_label='z', azimuth=-60.0, elevation=30.0, zoom=1.0)[source]#

Bases: object

3-D plot panel.

Supports three geometry types matching matplotlib’s 3-D Axes API:

'surface' – triangulated surface, Z-coloured via colormap.
'scatter' – point cloud, single colour.
'line' – connected line through 3-D points.

Created by Axes.plot_surface(), Axes.scatter3d(), and Axes.plot3d().

Not an anywidget. Holds state in _state dict; every mutation calls _push() which writes to the parent Figure’s panel trait.

Parameters:

geom_type (str)
colormap (str)
color (str)
point_size (float)
linewidth (float)
x_label (str)
y_label (str)
z_label (str)
azimuth (float)
elevation (float)
zoom (float)

to_state_dict()[source]#

Return type:: dict

on_changed(fn)[source]#

Decorator: fires on every rotation/zoom frame.

Parameters:: fn (Callable)
Return type:: Callable

on_release(fn)[source]#

Decorator: fires once when rotation/zoom settles.

Parameters:: fn (Callable)
Return type:: Callable

on_click(fn)[source]#

Decorator: fires on click on this panel.

Parameters:: fn (Callable)
Return type:: Callable

on_key(key_or_fn=None)[source]#

Two call forms are supported:

@plot.on_key('q')          # fires only when 'q' is pressed
def handler(event): ...

@plot.on_key               # fires for every registered key
def handler(event): ...

The event carries: key, mouse_x, mouse_y, and last_widget_id.

Note

Registered keys take priority over the built-in r (reset view) shortcut.

Return type:: Callable

disconnect(cid)[source]#

Remove the callback registered under integer cid.

Parameters:: cid (int)
Return type:: None

set_colormap(name)[source]#

Set the surface colormap (ignored for scatter/line).

Parameters:: name (str)
Return type:: None

set_view(azimuth=None, elevation=None)[source]#

Set the camera azimuth (°) and/or elevation (°).

Parameters:

azimuth (float | None)
elevation (float | None)

Return type:

None

set_zoom(zoom)[source]#

Parameters:: zoom (float)
Return type:: None

update(x, y, z)[source]#

Replace the geometry data.

Return type:: None

class anyplotlib.figure_plots.PlotBar(values, x_labels=None, x_centers=None, color='#4fc3f7', colors=None, bar_width=0.7, orient='v', baseline=0.0, show_values=False, units='', y_units='')[source]#

Bases: object

Bar-chart plot panel.

Not an anywidget. Holds state in _state dict; every mutation calls _push() which writes to the parent Figure’s panel trait.

Supports draggable VLineWidget and HLineWidget overlays via add_vline_widget() / add_hline_widget().

Created by Axes.bar().

Parameters:

color (str)
bar_width (float)
orient (str)
baseline (float)
show_values (bool)
units (str)
y_units (str)

to_state_dict()[source]#

Return type:: dict

update(values, x_centers=None, x_labels=None)[source]#

Replace bar values; recalculates the value-axis range automatically.

Return type:: None

set_color(color)[source]#

Set a single colour for all bars.

Parameters:: color (str)
Return type:: None

set_colors(colors)[source]#

Set per-bar colours (list of CSS colour strings, length N).

Return type:: None

set_show_values(show)[source]#

Show or hide in-bar value annotations.

Parameters:: show (bool)
Return type:: None

add_vline_widget(x, color='#00e5ff')[source]#

Add a draggable vertical line at data position x.

Parameters:

x (float)
color (str)

Return type:

VLineWidget

add_hline_widget(y, color='#00e5ff')[source]#

Add a draggable horizontal line at value-axis position y.

Parameters:

y (float)
color (str)

Return type:

HLineWidget

get_widget(wid)[source]#

Return the Widget object by ID string or Widget instance.

Return type:: Widget

remove_widget(wid)[source]#

Remove a widget by ID string or Widget instance.

Return type:: None

list_widgets()[source]#

Return type:: list

clear_widgets()[source]#

Return type:: None

on_click(fn)[source]#

Decorator: fires when the user clicks a bar.

The Event has bar_index, value, x_center, and x_label.

Parameters:: fn (Callable)
Return type:: Callable

on_changed(fn)[source]#

Decorator: fires on every drag frame (widget drag or hover).

Parameters:: fn (Callable)
Return type:: Callable

on_release(fn)[source]#

Decorator: fires once when a widget drag settles.

Parameters:: fn (Callable)
Return type:: Callable

on_key(key_or_fn=None)[source]#

Two call forms are supported:

@plot.on_key('q')          # fires only when 'q' is pressed
def handler(event): ...

@plot.on_key               # fires for every registered key
def handler(event): ...

The event carries: key, mouse_x, mouse_y, and last_widget_id.

Return type:: Callable

disconnect(cid)[source]#

Parameters:: cid (int)
Return type:: None

Figure Plots#

figure_plots.py#

Public classes#

This Page