Proxy objects (cdl.proxy)#

The cdl.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 cdl.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 (bool) – Automatically connect to DataLab XML-RPC server.

Raises:

Examples

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

>>> from cdl.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
<cdl.core.model.signal.SignalObj at 0x7f7f1c0b4a90>
>>> proxy[1]  # from number
<cdl.core.model.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 (list) – annotation plot items

  • refresh_plot (bool | None) – refresh plot. Defaults to True.

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

add_image(title: str, data: ndarray, xunit: str | None = None, yunit: str | None = None, zunit: str | None = None, xlabel: str | None = None, ylabel: str | None = None, zlabel: str | None = None) bool#

Add image data to DataLab.

Parameters:
  • title (str) – Image title

  • data (numpy.ndarray) – Image data

  • xunit (str | None) – X unit. Defaults to None.

  • yunit (str | None) – Y unit. Defaults to None.

  • zunit (str | None) – Z unit. Defaults to None.

  • xlabel (str | None) – X label. Defaults to None.

  • ylabel (str | None) – Y label. Defaults to None.

  • zlabel (str | None) – Z label. Defaults to None.

Returns:

True if image was added successfully, False otherwise

Return type:

bool

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 (str | None) – Label title. Defaults to None. If None, the title is the object title.

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

add_object(obj: SignalObj | ImageObj) None#

Add object to DataLab.

Parameters:

obj (SignalObj | ImageObj) – Signal or image object

add_signal(title: str, xdata: ndarray, ydata: ndarray, xunit: str | None = None, yunit: str | None = None, xlabel: str | None = None, ylabel: str | None = None) bool#

Add signal data to DataLab.

Parameters:
  • title (str) – Signal title

  • xdata (numpy.ndarray) – X data

  • ydata (numpy.ndarray) – Y data

  • xunit (str | None) – X unit. Defaults to None.

  • yunit (str | None) – Y unit. Defaults to None.

  • xlabel (str | None) – X label. Defaults to None.

  • ylabel (str | None) – Y label. Defaults to None.

Returns:

True if signal was added successfully, False otherwise

Return type:

bool

Raises:
calc(name: str, param: DataSet | None = None) DataSet#

Call compute function name in current panel’s processor.

Parameters:
Returns:

Compute function result

Return type:

guidata.dataset.DataSet

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 (str | None) – XML-RPC port to connect to. If not specified, the port is automatically retrieved from DataLab configuration.

  • timeout (float | None) – Timeout in seconds. Defaults to 5.0.

  • retries (int | None) – Number of retries. Defaults to 10.

Raises:
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.compute_fft()
...     proxy.compute_wiener()
...     proxy.compute_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:

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

Return type:

str

get_group_titles_with_object_infos() 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) list[str]#

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

Parameters:

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

Returns:

list of object uuids

Return type:

list[str]

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

Return type:

list[str]

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

Return type:

str

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

Open DataLab HDF5 browser to Import HDF5 file.

Parameters:
  • filename (str) – HDF5 file name

  • reset_all (bool | None) – 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_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[str] | None) – List of HDF5 files to open. Defaults to None.

  • import_all (bool | None) – Import all objects from HDF5 files. Defaults to None.

  • reset_all (bool | None) – 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 (str) – 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 (str | None) – 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 (str) – 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 (bool) – Auto refresh state

toggle_show_titles(state: bool) None#

Toggle show titles state.

Parameters:

state (bool) – 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 cdl.proxy.LocalProxy(cdl: CDLMainWindow | 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:

cdl (CDLMainWindow) – CDLMainWindow instance.

add_signal(title: str, xdata: ndarray, ydata: ndarray, xunit: str | None = None, yunit: str | None = None, xlabel: str | None = None, ylabel: str | None = None) bool#

Add signal data to DataLab.

Parameters:
  • title (str) – Signal title

  • xdata (numpy.ndarray) – X data

  • ydata (numpy.ndarray) – Y data

  • xunit (str | None) – X unit. Defaults to None.

  • yunit (str | None) – Y unit. Defaults to None.

  • xlabel (str | None) – X label. Defaults to None.

  • ylabel (str | None) – Y label. Defaults to None.

Returns:

True if signal was added successfully, False otherwise

Return type:

bool

Raises:
add_image(title: str, data: ndarray, xunit: str | None = None, yunit: str | None = None, zunit: str | None = None, xlabel: str | None = None, ylabel: str | None = None, zlabel: str | None = None) bool#

Add image data to DataLab.

Parameters:
  • title (str) – Image title

  • data (numpy.ndarray) – Image data

  • xunit (str | None) – X unit. Defaults to None.

  • yunit (str | None) – Y unit. Defaults to None.

  • zunit (str | None) – Z unit. Defaults to None.

  • xlabel (str | None) – X label. Defaults to None.

  • ylabel (str | None) – Y label. Defaults to None.

  • zlabel (str | None) – Z label. Defaults to None.

Returns:

True if image was added successfully, False otherwise

Return type:

bool

Raises:

ValueError – Invalid data dtype

calc(name: str, param: DataSet | None = None) DataSet#

Call compute function name in current panel’s processor.

Parameters:
  • name (str) – Compute function name

  • param (guidata.dataset.DataSet | None) – Compute function

  • None. (parameter. Defaults to) –

Returns:

Compute function result

Return type:

guidata.dataset.DataSet

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:
  • items (list) – annotation plot items

  • refresh_plot (bool | None) – refresh plot. Defaults to True.

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

add_object(obj: SignalObj | ImageObj) None#

Add object to DataLab.

Parameters:

obj (SignalObj | ImageObj) – Signal or image object

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 (str | None) – Label title. Defaults to None. If None, the title is the object title.

  • panel (str | None) – 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.compute_fft()
...     proxy.compute_wiener()
...     proxy.compute_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:

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

Return type:

str

get_group_titles_with_object_infos() 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) list[str]#

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

Parameters:

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

Returns:

list of object uuids

Return type:

list[str]

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

Return type:

list[str]

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

Return type:

str

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

Open DataLab HDF5 browser to Import HDF5 file.

Parameters:
  • filename (str) – HDF5 file name

  • reset_all (bool | None) – Reset all application data. Defaults to None.

import_macro_from_file(filename: str) None#

Import macro from file

Parameters:

filename – Filename.

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[str] | None) – List of HDF5 files to open. Defaults to None.

  • import_all (bool | None) – Import all objects from HDF5 files. Defaults to None.

  • reset_all (bool | None) – 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 (str) – 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 (str | None) – 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 (str) – 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 (bool) – Auto refresh state

toggle_show_titles(state: bool) None#

Toggle show titles state.

Parameters:

state (bool) – 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.

cdl.proxy.proxy_context(what: str) Generator[LocalProxy | RemoteProxy, None, None]#

Context manager handling CDL proxy creation and destruction.

Parameters:

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

Yields:

Generator[LocalProxy | RemoteProxy, None, None]

proxy

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

Example

with proxy_context(“local”) as proxy:

proxy.add_signal(…)