Features#

This page describes the key features of DataLab-Kernel.

Dual Operating Modes#

Standalone Mode

  • Works without DataLab installed

  • Local object storage in memory

  • HDF5 persistence for reproducibility

  • Full Sigima processing capabilities

Live Mode

  • Automatic connection to running DataLab

  • Real-time object synchronization

  • Access to DataLab’s processing pipeline

  • GUI feedback for all operations

Connection Methods#

Auto-Discovery (recommended)

DataLab-Kernel automatically discovers and connects to running DataLab instances. No configuration needed in most cases:

%load_ext datalab_kernel

# Connected automatically!
workspace.list()

Auto-discovery tries these methods in order:

  1. Environment variables (DATALAB_WORKSPACE_URL, DATALAB_WORKSPACE_TOKEN)

  2. Connection file written by DataLab (native Python only)

  3. URL query parameters (JupyterLite: ?datalab_url=...&datalab_token=...)

  4. Well-known port probing (http://127.0.0.1:18080)

Web API

Connect via HTTP/JSON using the REST API. This is what auto-discovery uses.

Features:

  • WASM/Pyodide compatible

  • Efficient NPZ binary format for data transfer

  • Bearer token authentication

  • Modern REST API

For manual connection (e.g., remote DataLab):

workspace.connect(url="http://192.168.1.100:18080", token="your-token")

Environment Variables

Variable

Description

Default

DATALAB_WORKSPACE_URL

Web API server URL

Auto-discovered

DATALAB_WORKSPACE_TOKEN

Web API authentication token

Auto-discovered

DATALAB_KERNEL_MODE

Force mode: auto, live, standalone

auto

DATALAB_PLOTTER_BACKEND

Plotting backend: plotly, matplotlib

Auto (Plotly preferred)

Unified Workspace API#

A single, consistent API regardless of mode:

workspace.add(name, obj)      # Add object
workspace.get(name)           # Retrieve object
workspace.remove(name)        # Remove object
workspace.rename(old, new)    # Rename object
workspace.list()              # List all objects
workspace.exists(name)        # Check existence
workspace.clear()             # Remove all objects
len(workspace)                # Object count
name in workspace             # Containment check
for name in workspace: ...    # Iteration

HDF5 Persistence#

Save and restore complete workspace state:

# Save everything
workspace.save("analysis.h5")

# Later, restore
workspace.load("analysis.h5")

HDF5 format ensures:

  • Platform-independent storage

  • Efficient compression

  • Complete metadata preservation

  • Compatibility with other HDF5 tools

Mode Switching with Resync#

Start standalone, switch to live when DataLab becomes available:

# Start without DataLab
workspace = Workspace()
workspace.add("signal", my_signal)

# ... work offline ...

# Later, DataLab is started
if workspace.resync():
    # Objects transferred to DataLab
    # Now in live mode
    workspace.calc("normalize")

DataLab Processing (Live Mode)#

Access DataLab’s extensive processing library:

import sigima.params

# Select and process
workspace.proxy.select_objects(["my_signal"], panel="signal")
workspace.calc("normalize", sigima.params.NormalizeParam())

# Results appear as new objects

Interactive Visualization#

DataLab-Kernel supports two plotting backends, chosen automatically:

  • Plotly — interactive HTML figures (preferred when installed)

  • Matplotlib — static PNG images (always available)

Install Plotly support with:

$ pip install datalab-kernel[plotly]

Usage:

plotter = Plotter(workspace)

# Signal plotting (uses the best available backend)
plotter.plot("signal_name")

# Image plotting with a specific colormap
plotter.plot("image_name", colormap="hot")

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

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

# Multiple images (subplot grid)
plotter.plot([img1, img2], titles=["Before", "After"])

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

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

You can also set the backend via the DATALAB_PLOTTER_BACKEND environment variable (plotly or matplotlib).

Sigima Integration#

Full access to Sigima’s data objects:

  • SignalObj: 1D signals with error bars, units, metadata

  • ImageObj: 2D images with coordinate systems

  • ROI support: Regions of interest for focused analysis

  • Processing functions: Via Sigima’s proc module

from sigima import SignalObj, ImageObj, create_signal, create_image

# Create rich data objects
signal = create_signal(
    "Temperature",
    time_array, temp_array,
    units=("s", "°C"),
    labels=("Time", "Temperature"),
)

Jupyter Integration#

Works seamlessly with:

Native Jupyter environments:

  • Jupyter Notebook: Classic notebook interface

  • JupyterLab: Modern lab environment

  • VS Code: With Jupyter extension

Browser-based:

  • JupyterLite: No server required, runs entirely in the browser via WebAssembly

For native environments, register the kernel once:

$ datalab-kernel-install

Then select “DataLab” kernel in any Jupyter frontend.

For JupyterLite, load the extension in your notebook:

%load_ext datalab_kernel

Error Handling#

User-friendly error messages:

>>> workspace.get("nonexistent")
KeyError: "Object 'nonexistent' not found. Available: ['signal1', 'image1']"

Errors avoid exposing internal implementation details.

Data Integrity#

Objects are copied on add to prevent accidental modification:

workspace.add("test", signal)
signal.y[0] = 999  # Modify original

retrieved = workspace.get("test")
assert retrieved.y[0] != 999  # Workspace copy unaffected