Plotter#

The Plotter class provides visualization for workspace objects. It auto-selects the best available backend — Plotly (interactive) when installed, falling back to Matplotlib (static PNG) otherwise.

Plotter API#

The Plotter class provides visualization capabilities for the DataLab kernel. It supports inline notebook display and optional DataLab GUI synchronization.

This module serves as the public API facade and contains shared helpers used by both the matplotlib and Plotly backends:

  • datalab_kernel.matplotlib_backend — static PNG rendering

  • datalab_kernel.plotly_backend — interactive HTML rendering

The Plotter class auto-selects the best available backend: Plotly (interactive) if installed, otherwise matplotlib (static). Users can override the choice via Plotter.set_backend() or the DATALAB_PLOTTER_BACKEND environment variable.

Shared helper functions for metadata extraction, coordinate computation, and style resolution live in this module so both backends can reuse them.

class datalab_kernel.plotter.Plotter(workspace: Workspace, backend: str | None = None)[source]#

Bases: object

Visualization frontend for the DataLab kernel.

The Plotter provides methods to display signals and images inline in Jupyter notebooks, and optionally synchronize views with a running DataLab instance.

The backend is chosen automatically (Plotly if installed, otherwise matplotlib) but can be overridden via the backend parameter, the DATALAB_PLOTTER_BACKEND environment variable, or at runtime with set_backend().

Example:

# Single object
plotter.plot("i042")
plotter.plot(workspace.get("i042"))

# Multiple signals (overlay on shared axes)
plotter.plot([sig1, sig2, sig3])

# Multiple images (subplot grid)
plotter.plot([img1, img2])

# Display analysis results
plotter.display_table(result)
plotter.display_geometry(result)

# Switch backend at runtime
plotter.set_backend("matplotlib")
property backend: str#

Return the name of the active backend ("plotly" or "matplotlib").

set_backend(backend: str) → Plotter[source]#

Switch the plotting backend at runtime.

Parameters:

backend – "plotly" or "matplotlib" (case-insensitive).

Returns:

self, for call-chaining.

Raises:

  • ValueError – If backend is not recognised.

  • ImportError – If the requested backend is not installed and no fallback is available.

plot(obj_or_name, title=None, show_roi=True, show_results=True, *, xlabel=None, ylabel=None, xunit=None, yunit=None, zlabel=None, zunit=None, titles=None, results=None, **kwargs)[source]#

Plot one or more objects.

Accepts a single object (or workspace name) or a list of objects.

  • Single object — renders one signal or image.

  • List of signals — overlays all curves on shared axes.

  • List of images — displays in a subplot grid.

  • Mixed list — raises TypeError.

A single-item list is unwrapped and treated as a single object.

Parameters:

  • obj_or_name – Object to plot, workspace name, or a list of objects / names. Lists may contain SignalObj, ImageObj, numpy.ndarray (1-D → signal, 2-D → image), (x, y) tuples (signal), or workspace name strings.

  • title – Plot title (overall figure title for multi-plots).

  • show_roi – Whether to show ROIs defined in the objects.

  • show_results – Whether to show geometry/table results from metadata.

  • xlabel – X-axis label override (multi-plots).

  • ylabel – Y-axis label override (multi-plots).

  • xunit – X-axis unit override (multi-plots).

  • yunit – Y-axis unit override (multi-plots).

  • zlabel – Colorbar label override (images only).

  • zunit – Colorbar unit override (images only).

  • titles – Per-image title list (images only).

  • results – List of GeometryResult objects to overlay (images only).

Keyword Arguments:

  • height (int) – Figure height in pixels. For images defaults to an auto-computed value based on the aspect ratio.

  • colormap (str) – Colormap name override (images only).

Returns:

A backend-specific result object with Jupyter display capabilities.

Raises:

  • TypeError – If a list mixes signals and images.

  • KeyError – If a workspace name is not found.

display_table(result, title=None, visible_only=True, transpose_single_row=True)[source]#

Display a TableResult with rich HTML rendering.

See the active backend’s display_table method for full documentation.

display_geometry(result, title=None)[source]#

Display a GeometryResult with rich HTML rendering.

See the active backend’s display_geometry method for full documentation.

class datalab_kernel.plotter.TableResultDisplay(result, title: str | None = None, visible_only: bool = True, transpose_single_row: bool = True)[source]#

Bases: object

Display wrapper for TableResult with rich Jupyter notebook rendering.

Provides HTML table display with automatic formatting, optional DataFrame conversion, and support for ROI-indexed results.

Example:

# Display a TableResult from computation
result = proxy.compute_statistics()
display = TableResultDisplay(result)
display  # Shows styled HTML table in Jupyter

# Get as DataFrame for further analysis
df = display.to_dataframe()
to_dataframe()[source]#

Convert the TableResult to a pandas DataFrame.

Returns:

pandas DataFrame with result data

class datalab_kernel.plotter.GeometryResultDisplay(result, title: str | None = None)[source]#

Bases: object

Display wrapper for GeometryResult with rich Jupyter notebook rendering.

Provides HTML table display showing coordinates and metadata for geometric results like points, segments, circles, ellipses, rectangles, and polygons.

Example:

# Display a GeometryResult from computation
result = proxy.compute_peak_detection()
display = GeometryResultDisplay(result)
display  # Shows styled HTML table in Jupyter

# Get as DataFrame for further analysis
df = display.to_dataframe()
to_dataframe()[source]#

Convert the GeometryResult to a pandas DataFrame.

Returns:

pandas DataFrame with coordinate data

datalab_kernel.plotter.matplotlib_available() → bool[source]#

Check whether matplotlib is importable.

datalab_kernel.plotter.plotly_available() → bool[source]#

Check whether plotly is importable.

datalab_kernel.plotter.resolve_backend(requested: str | None = None) → str[source]#

Determine which plotting backend to use.

Resolution order:

  1. requested argument (from Plotter.set_backend() or constructor)

  2. DATALAB_PLOTTER_BACKEND environment variable

  3. Auto-detect: Plotly if available, else matplotlib

When the chosen backend is not installed the function falls back to the other one and emits a UserWarning. If neither is installed an ImportError is raised.

Parameters:

requested – "plotly" or "matplotlib", case-insensitive. None means auto-detect.

Returns:

Resolved backend name ("plotly" or "matplotlib").

Raises:

  • ValueError – If requested is not a recognised backend name.

  • ImportError – If neither matplotlib nor plotly is installed.

datalab_kernel.plotter.PlotResult#

alias of MplPlotResult

class datalab_kernel.plotter.MatplotlibPlotter(workspace: Workspace)[source]#

Bases: object

Matplotlib-based visualization frontend for the DataLab kernel.

This class provides the same public API as datalab_kernel.plotly_backend.PlotlyPlotter but produces static matplotlib PNGs instead of interactive Plotly figures.

Example:

from datalab_kernel.matplotlib_backend import MatplotlibPlotter

plotter = MatplotlibPlotter(workspace)
plotter.plot("s001")                    # Single signal
plotter.plot([sig1, sig2])               # Multiple signals
plotter.plot([img1, img2])               # Multiple images
plotter.display_table(table_result)      # HTML table
plotter.display_geometry(geom_result)    # HTML table
plot(obj_or_name: DataObject | str | list, title: str | None = None, show_roi: bool = True, show_results: bool = True, *, xlabel: str | None = None, ylabel: str | None = None, xunit: str | None = None, yunit: str | None = None, zlabel: str | None = None, zunit: str | None = None, titles: list[str] | None = None, results: list | None = None, **kwargs) → MplPlotResult | MplMultiSignalResult | MplMultiImageResult[source]#

Plot one or more objects.

Accepts a single object (or workspace name) or a list.

  • Single object — renders one signal or image.

  • List of signals — overlays all curves on shared axes.

  • List of images — displays in a subplot grid.

  • Mixed list — raises TypeError.

A single-item list is unwrapped and treated as a single object.

Parameters:

  • obj_or_name – Object to plot, workspace name, or a list of objects / names.

  • title – Plot title (overall figure title for multi-plots).

  • show_roi – Whether to show ROIs defined in the objects.

  • show_results – Whether to show geometry/table results from metadata.

  • xlabel – X-axis label override (multi-plots).

  • ylabel – Y-axis label override (multi-plots).

  • xunit – X-axis unit override (multi-plots).

  • yunit – Y-axis unit override (multi-plots).

  • zlabel – Colorbar label override (images only).

  • zunit – Colorbar unit override (images only).

  • titles – Per-image title list (images only).

  • results – List of GeometryResult objects to overlay (images only).

  • **kwargs – Additional plotting options (height, colormap).

Returns:

A result object with Jupyter display capabilities.

Raises:

  • TypeError – If a list mixes signals and images.

  • KeyError – If a workspace name is not found.

display_table(result, title: str | None = None, visible_only: bool = True, transpose_single_row: bool = True) → TableResultDisplay[source]#

Display a TableResult with rich HTML rendering.

Parameters:

  • result – TableResult object to display

  • title – Optional title override (uses result.title if None)

  • visible_only – If True, show only visible columns based on display prefs

  • transpose_single_row – If True, transpose single-row tables for readability

Returns:

TableResultDisplay with Jupyter display capabilities

display_geometry(result, title: str | None = None) → GeometryResultDisplay[source]#

Display a GeometryResult with rich HTML rendering.

Parameters:

  • result – GeometryResult object to display

  • title – Optional title override (uses result.title if None)

Returns:

GeometryResultDisplay with Jupyter display capabilities

datalab_kernel.plotter.DEFAULT_PLOT_WIDTH = 640#

Default plot width in pixels for figure output. Matches matplotlib’s default figure width (6.4 in × 100 DPI) and fits comfortably in standard Jupyter layouts (~960 px classic, ~700–900 px Lab).

Usage#

from datalab_kernel import Workspace, Plotter

workspace = Workspace()
plotter = Plotter(workspace)

# Add some objects
workspace.add("signal", signal_obj)
workspace.add("image", image_obj)

# Plot by name (uses the best available backend)
plotter.plot("signal")
plotter.plot("image")

Backend Selection#

DataLab-Kernel ships two plotting backends:

Backend

Output

Install

Plotly

Interactive HTML figures

pip install datalab-kernel[plotly]

Matplotlib

Static PNG images

Included by default

When both are installed Plotly is preferred automatically. You can override this at any time:

# Check the active backend
print(plotter.backend)  # "plotly" or "matplotlib"

# Switch at runtime
plotter.set_backend("matplotlib")
plotter.plot("my_signal")  # static PNG output

plotter.set_backend("plotly")
plotter.plot("my_signal")  # interactive figure

# Or pass the backend at construction time
plotter = Plotter(workspace, backend="matplotlib")

You can also set the default via an environment variable before starting the kernel:

$ export DATALAB_PLOTTER_BACKEND=matplotlib

If the requested backend is not installed, the plotter falls back to the other one with a warning. If neither is installed, an ImportError is raised.

Signal Plotting#

Signals are plotted as line plots:

plotter.plot("my_signal")

Image Plotting#

Images are displayed as 2D colormaps:

plotter.plot("my_image")

# With a specific colormap
plotter.plot("my_image", colormap="hot")

# Override the auto-computed figure height (pixels)
plotter.plot("my_image", height=600)

Multi-Object Plotting#

Pass a list to plot() to display multiple objects at once. The plotter auto-detects whether items are signals or images:

Multiple signals — overlaid on shared axes with automatic legend and color cycling:

plotter.plot([sig1, sig2, sig3])

# With explicit axis labels and units
plotter.plot(
    [sig1, sig2],
    title="Comparison",
    xlabel="Frequency", ylabel="Magnitude",
    xunit="Hz", yunit="dB",
)

# Raw numpy arrays and (x, y) tuples are also supported
import numpy as np
plotter.plot([np.sin(np.linspace(0, 10, 200)), (x_array, y_array)])

Multiple images — displayed in a subplot grid (up to 4 columns):

plotter.plot([img1, img2, img3])

# With per-image titles and a shared colormap
plotter.plot(
    [img1, img2],
    titles=["Before", "After"],
    colormap="hot",
)

Mixed lists of signals and images raise a TypeError. A single-item list behaves identically to passing the object directly.