Proxy objects (datalab.control.proxy)

The datalab.control.proxy module provides a way to access DataLab features from a proxy class.

Remote proxy

The remote proxy is used when DataLab is started from a different process than the proxy. In this case, the proxy connects to DataLab XML-RPC server.

class datalab.control.proxy.RemoteProxy(autoconnect: bool = True)

DataLab remote proxy class.

This class provides access to DataLab features from a proxy class. This is the remote version of proxy, which is used when DataLab is started from a different process than the proxy.

Parameters:

autoconnect – Automatically connect to DataLab XML-RPC server.

Raises:

• ConnectionRefusedError – Unable to connect to DataLab

• ValueError – Invalid timeout (must be >= 0.0)

• ValueError – Invalid number of retries (must be >= 1)

Examples

Here is a simple example of how to use RemoteProxy in a Python script or in a Jupyter notebook:

>>> from datalab.control.proxy import RemoteProxy
>>> proxy = RemoteProxy()
Connecting to DataLab XML-RPC server...OK (port: 28867)
>>> proxy.get_version()
'1.0.0'
>>> proxy.add_signal("toto", np.array([1., 2., 3.]), np.array([4., 5., -1.]))
True
>>> proxy.get_object_titles()
['toto']
>>> proxy["toto"]  # from title
<sigima.objects.signal.SignalObj at 0x7f7f1c0b4a90>
>>> proxy[1]  # from number
<sigima.objects.signal.SignalObj at 0x7f7f1c0b4a90>
>>> proxy[1].data
array([1., 2., 3.])
>>> proxy.set_current_panel("image")

add_annotations_from_items(items: list, refresh_plot: bool = True, panel: str | None = None) → None

Add object annotations (annotation plot items).

Parameters:

• items – annotation plot items

• refresh_plot – refresh plot. Defaults to True.

• panel – panel name (valid values: “signal”, “image”). If None, current panel is used.

add_group(title: str, panel: str | None = None, select: bool = False) → None

Add group to DataLab.

Parameters:

• title – Group title

• panel – Panel name (valid values: “signal”, “image”). Defaults to None.

• select – Select the group after creation. Defaults to False.

add_image(title: str, data: ndarray, xunit: str = '', yunit: str = '', zunit: str = '', xlabel: str = '', ylabel: str = '', zlabel: str = '', group_id: str = '', set_current: bool = True) → bool

Add image data to DataLab.

Parameters:

• title – Image title

• data – Image data

• xunit – X unit. Defaults to “”

• yunit – Y unit. Defaults to “”

• zunit – Z unit. Defaults to “”

• xlabel – X label. Defaults to “”

• ylabel – Y label. Defaults to “”

• zlabel – Z label. Defaults to “”

• group_id – group id in which to add the image. Defaults to “”

• set_current – if True, set the added image as current

Returns:

True if image was added successfully, False otherwise

Raises:

ValueError – Invalid data dtype

add_label_with_title(title: str | None = None, panel: str | None = None) → None

Add a label with object title on the associated plot

Parameters:

• title – Label title. Defaults to None. If None, the title is the object title.

• panel – panel name (valid values: “signal”, “image”). If None, current panel is used.

add_object(obj: SignalObj | ImageObj, group_id: str = '', set_current: bool = True) → None

Add object to DataLab.

Parameters:

• obj – Signal or image object

• group_id – group id in which to add the object. Defaults to “”

• set_current – if True, set the added object as current

add_signal(title: str, xdata: ndarray, ydata: ndarray, xunit: str = '', yunit: str = '', xlabel: str = '', ylabel: str = '', group_id: str = '', set_current: bool = True) → bool

Add signal data to DataLab.

Parameters:

• title – Signal title

• xdata – X data

• ydata – Y data

• xunit – X unit. Defaults to “”

• yunit – Y unit. Defaults to “”

• xlabel – X label. Defaults to “”

• ylabel – Y label. Defaults to “”

• group_id – group id in which to add the signal. Defaults to “”

• set_current – if True, set the added signal as current

Returns:

True if signal was added successfully, False otherwise

Raises:

• ValueError – Invalid xdata dtype

• ValueError – Invalid ydata dtype

calc(name: str, param: gds.DataSet | None = None) → None

Call computation feature name

Note

This calls either the processor’s compute_<name> method (if it exists), or the processor’s <name> computation feature (if it is registered, using the run_feature method). It looks for the function in all panels, starting with the current one.

Parameters:

• name – Compute function name

• param – Compute function parameter. Defaults to None.

Raises:

ValueError – unknown function

close_application() → None

Close DataLab application

connect(port: str | None = None, timeout: float | None = None, retries: int | None = None) → None

Try to connect to DataLab XML-RPC server.

Parameters:

• port – XML-RPC port to connect to. If not specified, the port is automatically retrieved from DataLab configuration.

• timeout – Maximum time to wait for connection in seconds. Defaults to 5.0. This is the total maximum wait time, not per retry.

• retries – Number of retries. Defaults to 10. This parameter is deprecated and will be removed in a future version (kept for backward compatibility).

Raises:

• ConnectionRefusedError – Unable to connect to DataLab

• ValueError – Invalid timeout (must be >= 0.0)

• ValueError – Invalid number of retries (must be >= 1)

context_no_refresh() → Generator[None, None, None]

Return a context manager to temporarily disable auto refresh.

Returns:

Context manager

Example

>>> with proxy.context_no_refresh():
...     proxy.add_image("image1", data1)
...     proxy.calc("fft")
...     proxy.calc("wiener")
...     proxy.calc("ifft")
...     # Auto refresh is disabled during the above operations

delete_metadata(refresh_plot: bool = True, keep_roi: bool = False) → None

Delete metadata of selected objects

Parameters:

• refresh_plot – Refresh plot. Defaults to True.

• keep_roi – Keep ROI. Defaults to False.

disconnect() → None

Disconnect from DataLab XML-RPC server.

get_current_panel() → str

Return current panel name.

Returns:

“signal”, “image”, “macro”))

Return type:

Panel name (valid values

get_group_titles_with_object_info() → tuple[list[str], list[list[str]], list[list[str]]]

Return groups titles and lists of inner objects uuids and titles.

Returns:

groups titles, lists of inner objects uuids and titles

Return type:

Tuple

get_method_list() → list[str]

Return list of available methods.

get_object(nb_id_title: int | str | None = None, panel: str | None = None) → SignalObj | ImageObj

Get object (signal/image) from index.

Parameters:

• nb_id_title – Object number, or object id, or object title. Defaults to None (current object).

• panel – Panel name. Defaults to None (current panel).

Returns:

Object

Raises:

KeyError – if object not found

get_object_shapes(nb_id_title: int | str | None = None, panel: str | None = None) → list

Get plot item shapes associated to object (signal/image).

Parameters:

• nb_id_title – Object number, or object id, or object title. Defaults to None (current object).

• panel – Panel name. Defaults to None (current panel).

Returns:

List of plot item shapes

get_object_titles(panel: str | None = None) → list[str]

Get object (signal/image) list for current panel. Objects are sorted by group number and object index in group.

Parameters:

panel – panel name (valid values: “signal”, “image”, “macro”). If None, current data panel is used (i.e. signal or image panel).

Returns:

List of object titles

Raises:

ValueError – if panel not found

get_object_uuids(panel: str | None = None, group: int | str | None = None) → list[str]

Get object (signal/image) uuid list for current panel. Objects are sorted by group number and object index in group.

Parameters:

• panel – panel name (valid values: “signal”, “image”). If None, current panel is used.

• group – Group number, or group id, or group title. Defaults to None (all groups).

Returns:

List of object uuids

Raises:

ValueError – if panel not found

classmethod get_public_methods() → list[str]

Return all public methods of the class, except itself.

Returns:

List of public methods

get_sel_object_uuids(include_groups: bool = False) → list[str]

Return selected objects uuids.

Parameters:

include_groups – If True, also return objects from selected groups.

Returns:

List of selected objects uuids.

get_version() → str

Return DataLab public version.

Returns:

DataLab version

import_h5_file(filename: str, reset_all: bool | None = None) → None

Open DataLab HDF5 browser to Import HDF5 file.

Parameters:

• filename – HDF5 file name

• reset_all – Reset all application data. Defaults to None.

import_macro_from_file(filename: str) → None

Import macro from file

Parameters:

filename – Filename.

is_connected() → bool

Return True if connected to DataLab XML-RPC server.

load_from_directory(path: str) → None

Open objects from directory in current panel (signals/images).

Parameters:

path – directory path

load_from_files(filenames: list[str]) → None

Open objects from files in current panel (signals/images).

Parameters:

filenames – list of file names

load_h5_workspace(h5files: list[str], reset_all: bool = False) → None

Load native DataLab HDF5 workspace files without any GUI elements.

This method can be safely called from scripts (e.g., internal console, macros) as it does not create any Qt widgets, dialogs, or progress bars.

Warning

This method only supports native DataLab HDF5 files. For importing arbitrary HDF5 files (non-native), use open_h5_files() or import_h5_file() instead.

Parameters:

• h5files – List of native DataLab HDF5 filenames

• reset_all – Reset all application data before importing. Defaults to False.

Raises:

ValueError – If a file is not a valid native DataLab HDF5 file

open_h5_files(h5files: list[str] | None = None, import_all: bool | None = None, reset_all: bool | None = None) → None

Open a DataLab HDF5 file or import from any other HDF5 file.

Parameters:

• h5files – List of HDF5 files to open. Defaults to None.

• import_all – Import all objects from HDF5 files. Defaults to None.

• reset_all – Reset all application data. Defaults to None.

raise_window() → None

Raise DataLab window

reset_all() → None

Reset all application data

run_macro(number_or_title: int | str | None = None) → None

Run macro.

Parameters:

number_or_title – Macro number, or macro title. Defaults to None (current macro).

Raises:

ValueError – if macro not found

save_h5_workspace(filename: str) → None

Save current workspace to a native DataLab HDF5 file without GUI elements.

This method can be safely called from scripts (e.g., internal console, macros) as it does not create any Qt widgets, dialogs, or progress bars.

Parameters:

filename – HDF5 filename to save to

Raises:

IOError – If file cannot be saved

save_to_h5_file(filename: str) → None

Save to a DataLab HDF5 file.

Parameters:

filename – HDF5 file name

select_groups(selection: list[int | str] | None = None, panel: str | None = None) → None

Select groups in current panel.

Parameters:

• selection – List of group numbers (1 to N), or list of group uuids, or None to select all groups. Defaults to None.

• panel – panel name (valid values: “signal”, “image”). If None, current panel is used. Defaults to None.

select_objects(selection: list[int | str], panel: str | None = None) → None

Select objects in current panel.

Parameters:

• selection – List of object numbers (1 to N) or uuids to select

• panel – panel name (valid values: “signal”, “image”). If None, current panel is used. Defaults to None.

set_current_panel(panel: str) → None

Switch to panel.

Parameters:

panel – Panel name (valid values: “signal”, “image”, “macro”))

set_port(port: str | None = None) → None

Set XML-RPC port to connect to.

Parameters:

port – XML-RPC port to connect to. If None, the port is automatically retrieved from DataLab configuration.

stop_macro(number_or_title: int | str | None = None) → None

Stop macro.

Parameters:

number_or_title – Macro number, or macro title. Defaults to None (current macro).

Raises:

ValueError – if macro not found

toggle_auto_refresh(state: bool) → None

Toggle auto refresh state.

Parameters:

state – Auto refresh state

toggle_show_titles(state: bool) → None

Toggle show titles state.

Parameters:

state – Show titles state

Local proxy

The local proxy is used when DataLab is started from the same process as the proxy. In this case, the proxy is directly connected to DataLab main window instance. The typical use case is high-level scripting.

class datalab.control.proxy.LocalProxy(datalab: DLMainWindow | ServerProxy | None = None)

DataLab local proxy class.

This class provides access to DataLab features from a proxy class. This is the local version of proxy, which is used when DataLab is started from the same process as the proxy.

Parameters:

datalab (DLMainWindow) – DLMainWindow instance.

add_signal(title: str, xdata: ndarray, ydata: ndarray, xunit: str = '', yunit: str = '', xlabel: str = '', ylabel: str = '', group_id: str = '', set_current: bool = True) → bool

Add signal data to DataLab.

Parameters:

• title – Signal title

• xdata – X data

• ydata – Y data

• xunit – X unit. Defaults to “”

• yunit – Y unit. Defaults to “”

• xlabel – X label. Defaults to “”

• ylabel – Y label. Defaults to “”

• group_id – group id in which to add the signal. Defaults to “”

• set_current – if True, set the added signal as current

Returns:

True if signal was added successfully, False otherwise

Raises:

• ValueError – Invalid xdata dtype

• ValueError – Invalid ydata dtype

add_image(title: str, data: ndarray, xunit: str = '', yunit: str = '', zunit: str = '', xlabel: str = '', ylabel: str = '', zlabel: str = '', group_id: str = '', set_current: bool = True) → bool

Add image data to DataLab.

Parameters:

• title – Image title

• data – Image data

• xunit – X unit. Defaults to “”

• yunit – Y unit. Defaults to “”

• zunit – Z unit. Defaults to “”

• xlabel – X label. Defaults to “”

• ylabel – Y label. Defaults to “”

• zlabel – Z label. Defaults to “”

• group_id – group id in which to add the image. Defaults to “”

• set_current – if True, set the added image as current

Returns:

True if image was added successfully, False otherwise

Raises:

ValueError – Invalid data dtype

add_object(obj: SignalObj | ImageObj, group_id: str = '', set_current: bool = True) → None

Add object to DataLab.

Parameters:

• obj – Signal or image object

• group_id – group id in which to add the object. Defaults to “”

• set_current – if True, set the added object as current

calc(name: str, param: gds.DataSet | None = None) → None

Call computation feature name

Note

This calls either the processor’s compute_<name> method (if it exists), or the processor’s <name> computation feature (if it is registered, using the run_feature method). It looks for the function in all panels, starting with the current one.

Parameters:

• name – Compute function name

• param – Compute function parameter. Defaults to None

Raises:

ValueError – unknown function

get_object(nb_id_title: int | str | None = None, panel: str | None = None) → SignalObj | ImageObj

Get object (signal/image) from index.

Parameters:

• nb_id_title – Object number, or object id, or object title. Defaults to None (current object)

• panel – Panel name. Defaults to None (current panel)

Returns:

Object

Raises:

KeyError – if object not found

get_object_shapes(nb_id_title: int | str | None = None, panel: str | None = None) → list

Get plot item shapes associated to object (signal/image).

Parameters:

• nb_id_title – Object number, or object id, or object title. Defaults to None (current object)

• panel – Panel name. Defaults to None (current panel)

Returns:

List of plot item shapes

add_annotations_from_items(items: list, refresh_plot: bool = True, panel: str | None = None) → None

Add object annotations (annotation plot items).

Parameters:

• itemsTrue – annotation plot items

• refresh_plotTrue – refresh plot. Defaults to True

• panel – panel name (valid values: “signal”, “image”). If None, current panel is used

load_h5_workspace(h5files: list[str] | str, reset_all: bool = False) → None

Load HDF5 workspace files without showing file dialog.

This method loads one or more DataLab native HDF5 files directly, bypassing the file dialog. It is safe to call from the internal console or any context where Qt dialogs would cause threading issues.

Parameters:

• h5files – Path(s) to HDF5 file(s). Can be a single path string or a list of paths

• reset_all – If True, reset workspace before loading. Defaults to False.

Raises:

ValueError – if file is not a DataLab native HDF5 file

save_h5_workspace(filename: str) → None

Save workspace to HDF5 file without showing file dialog.

This method saves the current workspace to a DataLab native HDF5 file directly, bypassing the file dialog. It is safe to call from the internal console or any context where Qt dialogs would cause threading issues.

Parameters:

filename – Path to the output HDF5 file

add_group(title: str, panel: str | None = None, select: bool = False) → None

Add group to DataLab.

Parameters:

• title – Group title

• panel – Panel name (valid values: “signal”, “image”). Defaults to None.

• select – Select the group after creation. Defaults to False.

add_label_with_title(title: str | None = None, panel: str | None = None) → None

Add a label with object title on the associated plot

Parameters:

• title – Label title. Defaults to None. If None, the title is the object title.

• panel – panel name (valid values: “signal”, “image”). If None, current panel is used.

close_application() → None

Close DataLab application

context_no_refresh() → Generator[None, None, None]

Return a context manager to temporarily disable auto refresh.

Returns:

Context manager

Example

>>> with proxy.context_no_refresh():
...     proxy.add_image("image1", data1)
...     proxy.calc("fft")
...     proxy.calc("wiener")
...     proxy.calc("ifft")
...     # Auto refresh is disabled during the above operations

delete_metadata(refresh_plot: bool = True, keep_roi: bool = False) → None

Delete metadata of selected objects

Parameters:

• refresh_plot – Refresh plot. Defaults to True.

• keep_roi – Keep ROI. Defaults to False.

get_current_panel() → str

Return current panel name.

Returns:

“signal”, “image”, “macro”))

Return type:

Panel name (valid values

get_group_titles_with_object_info() → tuple[list[str], list[list[str]], list[list[str]]]

Return groups titles and lists of inner objects uuids and titles.

Returns:

groups titles, lists of inner objects uuids and titles

Return type:

Tuple

get_object_titles(panel: str | None = None) → list[str]

Get object (signal/image) list for current panel. Objects are sorted by group number and object index in group.

Parameters:

panel – panel name (valid values: “signal”, “image”, “macro”). If None, current data panel is used (i.e. signal or image panel).

Returns:

List of object titles

Raises:

ValueError – if panel not found

get_object_uuids(panel: str | None = None, group: int | str | None = None) → list[str]

Get object (signal/image) uuid list for current panel. Objects are sorted by group number and object index in group.

Parameters:

• panel – panel name (valid values: “signal”, “image”). If None, current panel is used.

• group – Group number, or group id, or group title. Defaults to None (all groups).

Returns:

List of object uuids

Raises:

ValueError – if panel not found

classmethod get_public_methods() → list[str]

Return all public methods of the class, except itself.

Returns:

List of public methods

get_sel_object_uuids(include_groups: bool = False) → list[str]

Return selected objects uuids.

Parameters:

include_groups – If True, also return objects from selected groups.

Returns:

List of selected objects uuids.

get_version() → str

Return DataLab public version.

Returns:

DataLab version

import_h5_file(filename: str, reset_all: bool | None = None) → None

Open DataLab HDF5 browser to Import HDF5 file.

Parameters:

• filename – HDF5 file name

• reset_all – Reset all application data. Defaults to None.

import_macro_from_file(filename: str) → None

Import macro from file

Parameters:

filename – Filename.

load_from_directory(path: str) → None

Open objects from directory in current panel (signals/images).

Parameters:

path – directory path

load_from_files(filenames: list[str]) → None

Open objects from files in current panel (signals/images).

Parameters:

filenames – list of file names

open_h5_files(h5files: list[str] | None = None, import_all: bool | None = None, reset_all: bool | None = None) → None

Open a DataLab HDF5 file or import from any other HDF5 file.

Parameters:

• h5files – List of HDF5 files to open. Defaults to None.

• import_all – Import all objects from HDF5 files. Defaults to None.

• reset_all – Reset all application data. Defaults to None.

raise_window() → None

Raise DataLab window

reset_all() → None

Reset all application data

run_macro(number_or_title: int | str | None = None) → None

Run macro.

Parameters:

number_or_title – Macro number, or macro title. Defaults to None (current macro).

Raises:

ValueError – if macro not found

save_to_h5_file(filename: str) → None

Save to a DataLab HDF5 file.

Parameters:

filename – HDF5 file name

select_groups(selection: list[int | str] | None = None, panel: str | None = None) → None

Select groups in current panel.

Parameters:

• selection – List of group numbers (1 to N), or list of group uuids, or None to select all groups. Defaults to None.

• panel – panel name (valid values: “signal”, “image”). If None, current panel is used. Defaults to None.

select_objects(selection: list[int | str], panel: str | None = None) → None

Select objects in current panel.

Parameters:

• selection – List of object numbers (1 to N) or uuids to select

• panel – panel name (valid values: “signal”, “image”). If None, current panel is used. Defaults to None.

set_current_panel(panel: str) → None

Switch to panel.

Parameters:

panel – Panel name (valid values: “signal”, “image”, “macro”))

stop_macro(number_or_title: int | str | None = None) → None

Stop macro.

Parameters:

number_or_title – Macro number, or macro title. Defaults to None (current macro).

Raises:

ValueError – if macro not found

toggle_auto_refresh(state: bool) → None

Toggle auto refresh state.

Parameters:

state – Auto refresh state

toggle_show_titles(state: bool) → None

Toggle show titles state.

Parameters:

state – Show titles state

Proxy context manager

The proxy context manager is a convenient way to handle proxy creation and destruction. It is used as follows:

with proxy_context("local") as proxy:
    proxy.add_signal(...)

The proxy type can be “local” or “remote”. For remote proxy, the port can be specified as “remote:port”.

Note

The proxy context manager allows to use the proxy in various contexts (Python script, Jupyter notebook, etc.). It also allows to switch seamlessly between local and remote proxy, keeping the same code inside the context.

datalab.control.proxy.proxy_context(what: str) → Generator[LocalProxy | RemoteProxy, None, None]

Context manager handling DL proxy creation and destruction.

Parameters:

what – proxy type (“local” or “remote”) For remote proxy, the port can be specified as “remote:port”

Yields:

proxy

LocalProxy if what == “local” RemoteProxy if what == “remote” or “remote:port”

Example

with proxy_context(“local”) as proxy:

proxy.add_signal(…)

Calling processor methods using proxy objects

All the proxy objects provide access to the DataLab computing methods exposed by the processor classes:

• datalab.gui.processor.signal.SignalProcessor

• datalab.gui.processor.image.ImageProcessor

To run a computation feature associated to a processor, you can use the calc() method of the proxy object:

# Call a method without parameter
proxy.calc("average")

# Call a method with parameters
p = sigima.params.MovingAverageParam.create(n=30)
proxy.calc("moving_average", p)