anyplotlib.Plot1D#

class anyplotlib.Plot1D(data, x_axis=None, units='px', y_units='', color='#4fc3f7', linewidth=1.5, linestyle='solid', alpha=1.0, marker='none', markersize=4.0, label='')[source]#

Bases: object

1-D line plot panel returned by Axes.plot().

All display state is stored in a plain _state dict. Every mutation ends with _push(), which serialises the state to the parent Figure trait so the JS renderer picks up the change immediately.

Supported line properties#

Set at construction time via Axes.plot() or updated afterwards with the corresponding setter:

Parameter	Default	Description
`color`	`"#4fc3f7"`	CSS colour string for the primary line.
`linewidth`	`1.5`	Stroke width in pixels.
`linestyle` (`ls`)	`"solid"`	Dash pattern: `"solid"`, `"dashed"`, `"dotted"`, `"dashdot"`. Shorthands `"-"`, `"--"`, `":"`, `"-."` also accepted.
`alpha`	`1.0`	Line opacity (0 = transparent, 1 = fully opaque).
`marker`	`"none"`	Per-point symbol: `"o"` (circle), `"s"` (square), `"^"`/`"v"` (triangles), `"D"` (diamond), `"+"`/`"x"` (stroke-only), or `"none"`.
`markersize`	`4.0`	Marker radius / half-side in pixels.
`label`	`""`	Legend label (empty string = no legend entry).

Public API summary#

Data: update() — replace y-data (and optionally the x-axis / units) without recreating the panel.
Overlay lines: add_line() / remove_line() / clear_lines() — overlay additional curves on the same axes.
Shaded spans: add_span() / remove_span() / clear_spans() — highlight a region along the x- or y-axis.
View control: set_view() / reset_view() — programmatic pan/zoom (users can also pan/zoom interactively with the mouse; press R to reset).
Interactive widgets: add_vline_widget() / add_hline_widget() / add_range_widget() — draggable overlays that report their position back to Python via callbacks. Manage them with get_widget(), remove_widget(), list_widgets(), and clear_widgets().
Static marker collections: add_points() / add_circles() / add_vlines() / add_hlines() / add_arrows() / add_ellipses() / add_lines() / add_rectangles() / add_squares() / add_polygons() / add_texts() — fixed overlays positioned at explicit data coordinates. Access them via plot.markers[type][name] and manage with remove_marker(), clear_markers(), and list_markers().
Callbacks: on_changed() / on_release() / on_click() / on_key() — react to pan/zoom frames, mouse clicks, and key-presses. Remove a handler with disconnect().

to_state_dict()[source]#

Return type:: dict

property line: Line1D#

Handle for the primary line, enabling per-line callbacks.

Returns a Line1D with id=None so you can register hover / click handlers scoped to just the primary line:

@plot.line.on_click
def on_primary_click(event):
    print(f"primary line clicked at x={event.x:.3f}")

property data: ndarray#

The primary line’s y-data (read-only).

Returns a float64 copy with writeable=False. To replace the data call set_data().

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

Replace the primary line’s y-data and optionally its x-axis / units.

The y-axis range (data_min / data_max) is recomputed automatically. The viewport is not reset — call reset_view() explicitly if needed.

Parameters:

data (array-like, shape (N,)) – New y values. Must be 1-D.
x_axis (array-like, shape (N,), optional) – New x coordinates. If omitted and the length of data matches the current x-axis, the existing x-axis is reused; otherwise it is reset to 0, 1, …, N-1.
units (str, optional) – New x-axis label. Unchanged if not supplied.
y_units (str, optional) – New y-axis label. Unchanged if not supplied.

Return type:

None

add_line(data, x_axis=None, color='#ffffff', linewidth=1.5, linestyle='solid', ls=None, alpha=1.0, marker='none', markersize=4.0, label='')[source]#

Overlay an additional curve on this panel.

The y-axis range is automatically expanded to include the new data so all lines remain fully visible.

Parameters:

data (array-like, shape (N,)) – Y values for the new line. Must be 1-D.
x_axis (array-like, shape (N,), optional) – X coordinates. Defaults to the primary line’s x-axis.
color (str, optional) – CSS colour string. Default "#ffffff".
linewidth (float, optional) – Stroke width in pixels. Default 1.5.
linestyle (str, optional) – Dash pattern: "solid", "dashed", "dotted", "dashdot" (or shorthands). Default "solid".
ls (str, optional) – Short alias for linestyle.
alpha (float, optional) – Line opacity (0–1). Default 1.0.
marker (str, optional) – Per-point marker symbol (see Plot1D). Default "none".
markersize (float, optional) – Marker radius / half-side in pixels. Default 4.0.
label (str, optional) – Legend label. Default "" (no legend entry).

Returns:

A handle to the new overlay line. Use it to register per-line hover/click callbacks or to remove the line later:

line = v.add_line(fit, color="#ffcc00", label="fit")
line.remove()                     # remove it
@line.on_click                    # per-line click handler
def clicked(event): ...

Return type:

Line1D

remove_line(lid)[source]#

Remove an overlay line by its ID or Line1D handle.

The y-axis range is recomputed after removal.

Parameters:: lid (str or Line1D) – The value returned by add_line().
Raises:: KeyError – If lid does not match any overlay line.
Return type:: None

clear_lines()[source]#

Remove all overlay lines, leaving the primary line intact.

The y-axis range is recomputed after clearing.

Return type:: None

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

Add a shaded span along the x- or y-axis.

Parameters:

v0 (float) – Start and end of the span in data coordinates.
v1 (float) – Start and end of the span in data coordinates.
axis ("x" | "y", optional) – Which axis the span runs along. Default "x".
color (str, optional) – CSS colour string (supports alpha, e.g. "rgba(255,200,0,0.2)"). Defaults to a theme-appropriate yellow tint.

Returns:

Span ID for use with remove_span().

Return type:

str

remove_span(sid)[source]#

Remove a shaded span by its ID.

Parameters:: sid (str) – The ID returned by add_span().
Raises:: KeyError – If sid does not match any span.
Return type:: None

clear_spans()[source]#

Remove all shaded spans.

Return type:: None

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

Add a draggable vertical-line overlay.

Parameters:

x (float) – Initial x position in data coordinates.
color (str, optional) – CSS colour string. Default "#00e5ff".

Returns:

Widget object. Register position callbacks with on_changed() / on_release().

Return type:

VLineWidget

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

Add a draggable horizontal-line overlay.

Parameters:

y (float) – Initial y position in data coordinates.
color (str, optional) – CSS colour string. Default "#00e5ff".

Returns:

Widget object. Register position callbacks with on_changed() / on_release().

Return type:

HLineWidget

add_range_widget(x0, x1, color='#00e5ff', style='band', y=0.0, _push=True)[source]#

Add a draggable range overlay to this panel.

Parameters:

x0 (float) – Initial left and right edges in data coordinates.
x1 (float) – Initial left and right edges in data coordinates.
color (str, optional) – CSS colour string. Default "#00e5ff".
style ({'band', 'fwhm'}, optional) – Visual style. 'band' (default) draws two vertical lines with a translucent fill. 'fwhm' draws two draggable circles connected by a dashed horizontal line at y (the half-maximum level), giving an o-------o FWHM indicator.
y (float, optional) – Y-coordinate (data space) for the connecting line when style='fwhm'. Ignored when style='band'. Default 0.
_push (bool, optional) – Push state to JS immediately. Set to False when adding several widgets at once; call _push() manually afterward.

Returns:

Widget object. Register position callbacks with on_changed() / on_release().

Return type:

RangeWidget

add_point_widget(x, y, color='#00e5ff', show_crosshair=True, _push=True)[source]#

Add a freely-draggable control point to this panel.

Parameters:

x (float) – Initial x position in data coordinates.
y (float) – Initial y position in data coordinates (value axis).
color (str, optional) – CSS colour string. Default "#00e5ff".
show_crosshair (bool, optional) – Draw dashed guide lines through the handle. Default True. Pass False for a plain dot with no guide lines.
_push (bool, optional) – Push state to JS immediately. Set to False when adding several widgets at once; call _push() manually afterward.

Return type:

PointWidget

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 a list of all active widget objects on this panel.

Return type:: list

clear_widgets()[source]#

Remove all interactive overlay widgets from this panel.

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]#

Register a key-press handler for this panel.

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

on_line_hover(fn)[source]#

Decorator: fires when the cursor moves over any line on this panel.

The event carries event.line_id (None = primary line, str = overlay), event.x, and event.y in data coordinates. For per-line filtering use Line1D.on_hover() instead.

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

on_line_click(fn)[source]#

Decorator: fires when the user clicks any line on this panel.

The event carries the same fields as on_line_hover(). For per-line filtering use Line1D.on_click() instead.

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

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

Programmatically set the visible x range.

Parameters:

x0 (float, optional) – Left edge of the view in data coordinates. None keeps the current left edge.
x1 (float, optional) – Right edge of the view in data coordinates. None keeps the current right edge.

Return type:

None

reset_view()[source]#

Reset the view to show the full x range of the primary line.

Return type:: None

set_color(color)[source]#

Set the primary line colour.

Parameters:: color (str) – Any CSS colour string (hex, rgb(), named colour, etc.).
Return type:: None

set_linewidth(linewidth)[source]#

Set the primary line stroke width.

Parameters:: linewidth (float) – Stroke width in pixels.
Return type:: None

set_linestyle(linestyle)[source]#

Set the primary line dash pattern.

Parameters:: linestyle (str) – "solid" ("-"), "dashed" ("--"), "dotted" (":"), or "dashdot" ("-.")
Return type:: None

set_alpha(alpha)[source]#

Set the primary line opacity.

Parameters:: alpha (float) – Opacity in the range 0 (transparent) to 1 (fully opaque).
Return type:: None

set_marker(marker, markersize=None)[source]#

Set the primary line per-point marker symbol.

Parameters:

marker (str) – "o", "s", "^", "v", "D", "+", "x", or "none".
markersize (float, optional) – Marker radius / half-side in pixels. Unchanged if not supplied.

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]#

Add circle markers at explicit (x, y) positions.

On 1-D panels circles are rendered as filled/stroked discs; radius is in canvas pixels (not data units).

Parameters:

offsets (array-like, shape (N, 2)) – Marker positions as [[x0, y0], [x1, y1], …] in data coordinates.
name (str, optional) – Registry key. Auto-generated if omitted.
radius (float or array-like, optional) – Radius in pixels. Scalar or per-marker array. Default 5.
facecolors (str or None, optional) – Fill colour. None = no fill.
edgecolors (str, optional) – Stroke colour. Default "#ff0000".
linewidths (float, optional) – Stroke width in pixels. Default 1.5.
alpha (float, optional) – Fill opacity (0–1). Default 0.3.
hover_edgecolors (str, optional) – Colour overrides applied on mouse-hover.
hover_facecolors (str, optional) – Colour overrides applied on mouse-hover.
labels (list of str, optional) – Per-marker tooltip labels.
label (str, optional) – Collection-level tooltip label.

Returns:

Live group object. Call .set(**kwargs) to update in place.

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.

Parameters:

offsets (array-like, shape (N, 2)) – Marker positions as [[x0, y0], [x1, y1], …].
name (str, optional) – Registry key. Auto-generated if omitted.
sizes (float or array-like, optional) – Radius in pixels. Scalar or per-marker array. Default 5.
color (str, optional) – Stroke colour. Default "#ff0000".
facecolors (str or None, optional) – Fill colour. None = no fill.
linewidths (float, optional) – Stroke width in pixels. Default 1.5.
alpha (float, optional) – Fill opacity (0–1). Default 0.3.
hover_edgecolors (str, optional) – Colour overrides applied on mouse-hover.
hover_facecolors (str, optional) – Colour overrides applied on mouse-hover.
labels (list of str, optional) – Per-marker tooltip labels.
label (str, optional) – Collection-level tooltip label.

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 spanning the full x range.

Parameters:

y_values (array-like, shape (N,)) – Y positions of each line in data coordinates.
name (str, optional) – Registry key. Auto-generated if omitted.
color (str, optional) – Line colour. Default "#ff0000".
linewidths (float, optional) – Stroke width in pixels. Default 1.5.
hover_edgecolors (str, optional) – Colour override applied on mouse-hover.
labels (list of str, optional) – Per-line tooltip labels.
label (str, optional) – Collection-level tooltip label.

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 spanning the full y range.

Parameters:

x_values (array-like, shape (N,)) – X positions of each line in data coordinates.
name (str, optional) – Registry key. Auto-generated if omitted.
color (str, optional) – Line colour. Default "#ff0000".
linewidths (float, optional) – Stroke width in pixels. Default 1.5.
hover_edgecolors (str, optional) – Colour override applied on mouse-hover.
labels (list of str, optional) – Per-line tooltip labels.
label (str, optional) – Collection-level tooltip label.

Return type:

MarkerGroup

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

Add arrow markers at explicit (x, y) positions.

Parameters:

offsets (array-like, shape (N, 2)) – Arrow tail positions as [[x0, y0], …] in data coordinates.
U (array-like, shape (N,)) – X and Y components of each arrow vector (in data units).
V (array-like, shape (N,)) – X and Y components of each arrow vector (in data units).
name (str, optional) – Registry key. Auto-generated if omitted.
edgecolors (str, optional) – Arrow colour. Default "#ff0000".
linewidths (float, optional) – Stroke width in pixels. Default 1.5.
hover_edgecolors (str, optional) – Colour override applied on mouse-hover.
labels (list of str, optional) – Per-arrow tooltip labels.
label (str, optional) – Collection-level tooltip label.

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]#

Add ellipse markers at explicit (x, y) positions.

Parameters:

offsets (array-like, shape (N, 2)) – Centre positions in data coordinates.
widths (float or array-like) – Full width and height of each ellipse in canvas pixels.
heights (float or array-like) – Full width and height of each ellipse in canvas pixels.
name (str, optional) – Registry key. Auto-generated if omitted.
angles (float or array-like, optional) – Rotation angle(s) in degrees. Default 0.
facecolors (str or None, optional) – Fill colour. None = no fill.
edgecolors (str, optional) – Stroke colour. Default "#ff0000".
linewidths (float, optional) – Stroke width in pixels. Default 1.5.
alpha (float, optional) – Fill opacity (0–1). Default 0.3.
hover_edgecolors (str, optional) – Colour overrides applied on mouse-hover.
hover_facecolors (str, optional) – Colour overrides applied on mouse-hover.
labels (list of str, optional) – Per-marker tooltip labels.
label (str, optional) – Collection-level tooltip label.

Return type:

MarkerGroup

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

Add line-segment markers (static, not draggable).

Parameters:

segments (array-like, shape (N, 2, 2)) – Each segment is [[x0, y0], [x1, y1]] in data coordinates.
name (str, optional) – Registry key. Auto-generated if omitted.
edgecolors (str, optional) – Line colour. Default "#ff0000".
linewidths (float, optional) – Stroke width in pixels. Default 1.5.
hover_edgecolors (str, optional) – Colour override applied on mouse-hover.
labels (list of str, optional) – Per-segment tooltip labels.
label (str, optional) – Collection-level tooltip label.

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]#

Add rectangle markers at explicit (x, y) positions.

Parameters:

offsets (array-like, shape (N, 2)) – Centre positions in data coordinates.
widths (float or array-like) – Full width and height of each rectangle in canvas pixels.
heights (float or array-like) – Full width and height of each rectangle in canvas pixels.
name (str, optional) – Registry key. Auto-generated if omitted.
angles (float or array-like, optional) – Rotation angle(s) in degrees. Default 0.
facecolors (str or None, optional) – Fill colour. None = no fill.
edgecolors (str, optional) – Stroke colour. Default "#ff0000".
linewidths (float, optional) – Stroke width in pixels. Default 1.5.
alpha (float, optional) – Fill opacity (0–1). Default 0.3.
hover_edgecolors (str, optional) – Colour overrides applied on mouse-hover.
hover_facecolors (str, optional) – Colour overrides applied on mouse-hover.
labels (list of str, optional) – Per-marker tooltip labels.
label (str, optional) – Collection-level tooltip label.

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]#

Add square markers at explicit (x, y) positions.

Parameters:

offsets (array-like, shape (N, 2)) – Centre positions in data coordinates.
widths (float or array-like) – Side length of each square in canvas pixels.
name (str, optional) – Registry key. Auto-generated if omitted.
angles (float or array-like, optional) – Rotation angle(s) in degrees. Default 0.
facecolors (str or None, optional) – Fill colour. None = no fill.
edgecolors (str, optional) – Stroke colour. Default "#ff0000".
linewidths (float, optional) – Stroke width in pixels. Default 1.5.
alpha (float, optional) – Fill opacity (0–1). Default 0.3.
hover_edgecolors (str, optional) – Colour overrides applied on mouse-hover.
hover_facecolors (str, optional) – Colour overrides applied on mouse-hover.
labels (list of str, optional) – Per-marker tooltip labels.
label (str, optional) – Collection-level tooltip label.

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]#

Add polygon markers defined by explicit vertex lists.

Parameters:

vertices_list (list of array-like, each shape (K, 2)) – One polygon per element; each is a list of [x, y] vertices in data coordinates.
name (str, optional) – Registry key. Auto-generated if omitted.
facecolors (str or None, optional) – Fill colour. None = no fill.
edgecolors (str, optional) – Stroke colour. Default "#ff0000".
linewidths (float, optional) – Stroke width in pixels. Default 1.5.
alpha (float, optional) – Fill opacity (0–1). Default 0.3.
hover_edgecolors (str, optional) – Colour overrides applied on mouse-hover.
hover_facecolors (str, optional) – Colour overrides applied on mouse-hover.
labels (list of str, optional) – Per-polygon tooltip labels.
label (str, optional) – Collection-level tooltip label.

Return type:

MarkerGroup

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

Add text annotations at explicit (x, y) positions.

Parameters:

offsets (array-like, shape (N, 2)) – Anchor positions in data coordinates.
texts (list of str) – One string per position.
name (str, optional) – Registry key. Auto-generated if omitted.
color (str, optional) – Text colour. Default "#ff0000".
fontsize (int, optional) – Font size in pixels. Default 12.
hover_edgecolors (str, optional) – Colour override applied on mouse-hover.
labels (list of str, optional) – Per-annotation tooltip labels.
label (str, optional) – Collection-level tooltip label.

Return type:

MarkerGroup

remove_marker(marker_type, name)[source]#

Remove a named marker collection by type and name.

Parameters:

marker_type (str) – Collection type, e.g. "points", "vlines".
name (str) – The name used when the collection was created.

Return type:

None

clear_markers()[source]#

Remove all marker collections from this panel.

Return type:: None

list_markers()[source]#

Return a summary list of all marker collections on this panel.

Returns:: Each dict has keys "type", "name", and "n" (number of markers in the collection).
Return type:: list of dict

Parameters:

data (np.ndarray)
units (str)
y_units (str)
color (str)
linewidth (float)
linestyle (str)
alpha (float)
marker (str)
markersize (float)
label (str)