Plot2D

Plot2D#

See the interactive tutorial.

Use quantem.widget.Plot2D for a calibrated scalar map, such as G3 versus distance and angle. Use Show2D for spatial images. Plot2D owns axes, colorbar, zoom/pan and hover; it does not calculate correlations or train a model.

import numpy as np
import quantem.widget as qw

qw.profile(check_updates=False)
radius = (np.arange(100) + 0.5) * 0.1
angle = (np.arange(36) + 0.5) * 5
values = np.cos(np.deg2rad(angle[:, None])) ** 2 * radius[None, :]
plot = qw.Plot2D(
    values, x=radius, y=angle,
    x_label="Second-neighbor distance (Å)", y_label="Shared-root angle (°)",
    colorbar_label="Illustrative value", width=500, max_width=600,
)
plot

x contains column bin centers; y contains row bin centers. Both must be increasing uniform grids. Row zero is at the bottom, matching Cartesian plots. Source values and browser hover transport retain float64. The shared QuantEM WebGPU colormap renderer uses float32 display buffers. Canvas fallback is explicitly labeled when WebGPU is unavailable; it is not GPU acceleration.

Wheel over the map to zoom, then drag to pan. Zoom buttons and Reset View are also available. The Color menu changes map and colorbar together; each plot is independent. A browser-local animation-frame scheduler handles gestures without Python round trips. Stable view bounds are saved after interaction.

Map pixels, hover values and color-scale metadata update together after rendering completes, including during rapid replacements.

plot.set_data(next_values) preserves the original grid, color limits and viewport. plot.horizontal_line = 92.5 adds an angle-reading line without resending the map. plot.figure() returns a closed Matplotlib figure with the current axes, values, colormap and viewport, for example plot.figure().savefig("g3.svg"). By default, saved snapshots omit the map array and retain a static PNG preview. Use save_state=True to embed the complete float64 map for interactive restoration in supporting frontends. Static previews record the view when Python renders the preview or creates a full snapshot; they do not track browser-only gestures continuously. Notebook-manager save/restore behavior varies by frontend. Keep scientific data files separately.

Current scope#

This API targets small, finite scalar maps, not large spatial images. It does not support nonuniform coordinates, logarithmic axes, or standalone export_html. Full interactive embedding is opt-in with save_state=True; keep large data outside notebooks. Static previews use stride sampling above 512 bins per axis, preserve calibrated bounds, and are for viewing only. Controls, axes and the canvas follow the notebook or documentation light/dark theme.

Reference#

class quantem.widget.Plot2D(*args: t.Any, **kwargs: t.Any)#

Inspect a scalar map with physical axes and a labeled color scale.

Rows correspond to y and columns to x. Both coordinates are bin centers on increasing uniform grids. The first row is shown at the bottom, as in Matplotlib’s Cartesian plots. Source values and hover transport are float64; QuantEM’s shared WebGPU colormap renderer uses float32 display data. Pan and zoom change only the viewport, never the scientific array.

Parameters:

  • data (numpy.ndarray) – Finite two-dimensional scalar values.

  • x (numpy.ndarray) – Physical column and row bin centers, respectively.

  • y (numpy.ndarray) – Physical column and row bin centers, respectively.

  • x_label (str) – Scientific quantities including units where applicable.

  • y_label (str) – Scientific quantities including units where applicable.

  • colorbar_label (str) – Scientific quantities including units where applicable.

  • title (str) – Plot title.

  • cmap (str) – QuantEM colormap name, also used for Matplotlib export.

  • vmin (float or None) – Fixed color limits. When omitted, use the initial data range.

  • vmax (float or None) – Fixed color limits. When omitted, use the initial data range.

  • width (int) – Initial plot dimensions in CSS pixels.

  • height (int) – Initial plot dimensions in CSS pixels.

  • max_width (int) – Maximum width in CSS pixels, also bounded by the notebook container.

  • save_state (bool, default False) – Embed the full float64 map in saved widget state when True. By default, save a static PNG preview and omit the array from full state snapshots. Targeted live updates always retain the original values.

Examples

>>> plot = Plot2D(g3, x=radii, y=angles, x_label="r02 (Å)",
...               y_label="Angle (°)", colorbar_label="Normalized G3")
>>> plot.set_data(next_g3)
>>> plot.figure().savefig("g3.png", dpi=180)
set_data(data: ndarray) → None#

Replace values on the existing grid, preserving limits and viewport.

Parameters:

data (numpy.ndarray) – Finite values with the original row/column shape.

Examples

>>> plot.set_data(predicted_g3[1])
figure() → Figure#

Return a closed Matplotlib figure of the current values and viewport.

Returns:

Editable figure with physical axes and a labeled colorbar.

Return type:

matplotlib.figure.Figure

Examples

>>> plot.figure().savefig("correlation.svg")

Interactive controls#

Control

Behavior

Color

Recolor the map and scale without modifying values.

Zoom In / Zoom Out

Zoom about the viewport center.

Wheel / drag

Zoom about the pointer; pan within the full grid.

Reset View / double-click

Restore full physical bounds.

Save PNG

Save the current canvas, including labels and color scale.

Hover

Inspect original (row, col), calibrated coordinates and value.

The storyboard defines browser signoff.