Workspace#

The Workspace class is the central API for managing data objects.

WorkspaceMode#

class datalab_kernel.workspace.WorkspaceMode(value)[source]#

Workspace execution mode.

STANDALONE = 'standalone'#
LIVE = 'live'#

Workspace Class#

class datalab_kernel.workspace.Workspace(backend: WorkspaceBackend | None = None)[source]#

Bases: object

Workspace API for data access and persistence.

The Workspace provides a unified interface to access, modify, and persist scientific data objects (signals and images). It automatically selects the appropriate backend:

  • Standalone mode: Local memory storage with HDF5 persistence

  • Live mode: Synchronized with a running DataLab instance

Example:

# List objects
workspace.list()

# Get an object
img = workspace.get("i042")

# Add a new object
workspace.add("filtered", processed_img)

# Save to file
workspace.save("analysis.h5")
resync() → bool[source]#

Attempt to resync with DataLab via Web API.

If currently in standalone mode and DataLab Web API becomes available, switch to live mode. Objects in the standalone workspace are transferred to DataLab.

Returns:

True if switched to live mode, False if already live or

DataLab Web API is not available.

connect(url: str | None = None, token: str | None = None) → bool[source]#

Connect to DataLab Web API.

Attempts to establish a connection to DataLab using the Web API. If no URL/token are provided, auto-discovery is attempted using:

  1. Environment variables (DATALAB_WORKSPACE_URL, DATALAB_WORKSPACE_TOKEN)

  2. Connection file written by DataLab

  3. URL query parameters (for JupyterLite)

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

If currently in standalone mode with objects, they will be transferred to the DataLab workspace.

Parameters:

  • url – DataLab Web API URL (e.g., “http://127.0.0.1:18080”). If None, attempts auto-discovery.

  • token – Authentication token. If None, attempts auto-discovery. May be omitted if server allows localhost connections without token.

Returns:

True if connected successfully, False otherwise.

Example:

# Auto-discover DataLab (recommended)
workspace.connect()

# Connect with explicit credentials
workspace.connect("http://127.0.0.1:18080", "my-token")
status() → dict[source]#

Get current workspace status.

Returns:

Dictionary with mode, backend type, and connection info.

Example:

>>> workspace.status()
{'mode': 'live', 'backend': 'WebApiBackend', 'url': 'http://127.0.0.1:8080'}
property mode: WorkspaceMode#

Get current execution mode.

list() → list[str][source]#

List all object names in the workspace.

Returns:

List of object names

get(name: str) → DataObject[source]#

Retrieve an object by name.

Parameters:

name – Object name

Returns:

The requested object (SignalObj or ImageObj)

Raises:

KeyError – If object not found

add(name: str, obj: DataObject, overwrite: bool = False) → DataObject[source]#

Add an object to the workspace.

Parameters:

  • name – Object name

  • obj – Object to add (SignalObj or ImageObj)

  • overwrite – If True, replace existing object with same name

Returns:

The added object

Raises:

ValueError – If object exists and overwrite=False

remove(name: str) → None[source]#

Remove an object from the workspace.

Parameters:

name – Object name

Raises:

KeyError – If object not found

rename(old_name: str, new_name: str) → None[source]#

Rename an object.

Parameters:

  • old_name – Current object name

  • new_name – New object name

Raises:
exists(name: str) → bool[source]#

Check if an object exists.

Parameters:

name – Object name

Returns:

True if object exists

clear() → None[source]#

Remove all objects from the workspace.

save(filepath: str) → None[source]#

Save workspace to HDF5 file.

Parameters:

filepath – Path to save file (should end with .h5)

load(filepath: str) → None[source]#

Load workspace from HDF5 file.

Parameters:

filepath – Path to HDF5 file

select_objects(names: list[str], panel: str | None = None) → tuple[list[str], str][source]#

Select objects by name in DataLab.

This method is only available in live mode. It selects the specified objects, making them the active selection for subsequent operations.

Parameters:

  • names – List of object names/titles to select.

  • panel – Panel name (“signal” or “image”). None = auto-detect.

Returns:

Tuple of (list of selected names, panel name).

Raises:

Example:

# Select objects before calling calc
workspace.select_objects(["signal1", "signal2"])
workspace.calc("average")
calc(name: str, param: object | None = None) → object | None[source]#

Call a DataLab computation function.

This method is only available in live mode. It calls DataLab’s computation feature by name on the currently selected objects.

Parameters:

  • name – Computation function name (e.g., “normalize”, “fft”, “denoise”)

  • param – Optional parameter DataSet or dict for the computation

Returns:

Tuple of (success, list of new object names), or None if backend doesn’t support returning results.

Raises:

Example:

# Simple computation (select objects first)
workspace.select_objects(["my_signal"])
workspace.calc("normalize")

# Computation with parameters
workspace.calc("moving_average", {"n": 5})

# Or with DataSet
from sigima.params import MovingAverageParam
workspace.calc("moving_average", MovingAverageParam.create(n=5))

Backend Classes#