laboneq.dsl.result

Results(experiment=None, device_setup=None, compiled_experiment=None, acquired_results=None, neartime_callback_results=None, execution_errors=None, user_func_results=None, pipeline_jobs_timestamps=None) dataclass

Results of an LabOne Q experiment.

Attributes:

Name	Type	Description
experiment	Experiment	The source experiment.
device_setup	DeviceSetup	The device setup on which the experiment was run.
compiled_experiment	CompiledExperiment	Compiled experiment.
acquired_results	AcquiredResults	The acquired results, organized by handle.
neartime_callback_results	dict[str, list[Any]]	List of the results of near-time callbacks by their name.
user_func_results	dict[str, list[Any]]	Deprecated. Alias for neartime_callback_results.
execution_errors	list[tuple[list[int], str, str]]	Any exceptions that occurred during the execution of the experiment. Entries are tuples of: * the indices of the loops where the error occurred * the experiment section uid * the error message
pipeline_jobs_timestamps	dict[str, list[float]]	The timestamps of all pipeline jobs, in seconds. Organized by signal, then pipeline job id.

Deprecated in version 2.19.0

The user_func_results attribute was deprecated in version 2.19.0. Use neartime_callback_results instead.

acquired_results = acquired_results if acquired_results is not None else AcquiredResults() instance-attribute

compiled_experiment = compiled_experiment instance-attribute

device_calibration: Calibration | None property

Get the device setup's calibration.

See also DeviceSetup.get_calibration.

device_setup = device_setup instance-attribute

execution_errors = execution_errors instance-attribute

experiment = experiment instance-attribute

experiment_calibration property

neartime_callback_results = neartime_callback_results instance-attribute

pipeline_jobs_timestamps = pipeline_jobs_timestamps instance-attribute

signal_map property

user_func_results property

Deprecated. Alias for neartime_callback_results.

get_axis(handle)

Returns the axes grids.

Returns the list, where each element represents an axis of the corresponding dimension of the result array returned by 'get'. Each element is either a 1D numpy array for a simple sweep, or a list of 1D numpy arrays for a parallel sweep. The length of each array matches the number of steps of the corresponding sweep, and the values are the sweep parameter values at each step.

Parameters:

Name	Type	Description	Default
handle	str	The handle assigned to an 'acquire' event in the experiment definition.	required

Returns:

Type	Description
list[NDArray[Any] | list[NDArray[Any]]]	A list of axis grids. Each element may be either a 1D numpy array or a list of such
list[NDArray[Any] | list[NDArray[Any]]]	arrays.

Raises:

Type	Description
LabOneQException	No result is available for the provided handle.

get_axis_name(handle)

Returns the names of axes.

Returns the list of axis names, that correspond to the dimensions of the result returned by 'get'. Elements in the list are in the same order as the dimensions of the array returned by 'get'. Each element is either a string for a simple sweep, or a list of strings for a parallel sweep. Values are given by the 'axis_name' argument of the corresponding sweep parameter, or the 'uid' of the same parameter, if 'axis_name' is not specified.

Parameters:

Name	Type	Description	Default
handle	str	The handle assigned to an 'acquire' event in the experiment definition.	required

Returns:

Type	Description
list[str | list[str]]	A list of axis names. Each element may be either a string or a list of strings.

Raises:

Type	Description
LabOneQException	No result is available for the provided handle.

get_data(handle)

Returns the acquired result data.

Returns the result acquired for an 'acquire' event with the specific handle that was assigned to it in the experiment definition.

Parameters:

Name	Type	Description	Default
handle	str	The handle assigned to an 'acquire' event in the experiment definition.	required

Returns:

Type	Description
NDArray[Any]	A multidimensional numpy array, where each dimension corresponds to a sweep
NDArray[Any]	loop nesting level, the outermost sweep being the first dimension.

Raises:

Type	Description
LabOneQException	No result is available for the provided handle.

get_last_nt_step(handle)

Returns the list of axis indices of the last measured near-time point.

Returns the list of axis indices that represent the last measured near-time point. Use this to retrieve the last recorded partial result from the 'data' array. 'None' means that no measurements were taken so far. The list only covers axes that correspond to the near-time sweeps / dimensions. All the elements of inner real-time sweeps that correspond to a single real-time execution step are read at once and filled entirely.

Parameters:

Name	Type	Description	Default
handle	str	The handle assigned to an 'acquire' event in the experiment definition.	required

Returns:

Type	Description
list[int]	A list of axis indices.

Raises:

Type	Description
LabOneQException	No result is available for the provided handle.

get_result(handle)

Returns the acquired result.

Returns the result acquired for an 'acquire' event with the specific handle that was assigned to it in the experiment definition.

Parameters:

Name	Type	Description	Default
handle	str	The handle assigned to an 'acquire' event in the experiment definition.	required

Returns:

Name	Type	Description
result	AcquiredResult	The acquire event result.

Raises:

Type	Description
LabOneQException	No result is available for the provided handle.

load(filename) staticmethod

save(filename)

AcquiredResults

Bases: UserDict[str, AcquiredResult]

A collection of acquired results.

Keys are handles for a single acquire event. Values are acquired results for that handle.

Added in version 2.16.0

to_xarray(copy=False)

Convert to xarray.Dataset.

Requires optional dependency xarray to be installed.

By default, the data in the returned object is a view of the data, and will get updated if it is created during experiment runtime.

By setting copy to True, the returned data will be detached from the AcquiredResults data.

Note

In the case of axis data mismatch in the underlying AcquiredResults, the conversion might not work. The mismatch can happen when multiple sweep parameters have the same axis name, but the values are different.

Use results["result_handle"].to_array() to convert individual results to xarray.Dataset.

Parameters:

Name	Type	Description	Default
copy	bool	If True, returns a copy of the data instead of a view.	False

Returns:

Type	Description
Dataset	An xarray.Dataset of all acquired results.

Raises:

Type	Description
ModuleNotFoundError	If xarray is not installed.
LabOneQException	Individual results cannot be merged

Changed in version 2.26.0

Name of the coordinates is now the values of the axis names instead of sweep_n.

AcquiredResult() dataclass

This class represents the results acquired for a single result handle.

The acquired result is a triple consisting of actual data, axis name(s) and one or more axes.

Attributes:

Name	Type	Description
data	ndarray	A multidimensional numpy array, where each dimension corresponds to a sweep loop nesting level, the outermost sweep being the first dimension.
axis_name	list[str | list[str]]	A list of axis names. Each element may be either a string or a list of strings.
axis	list[ndarray | list[ndarray]]	A list of axis grids. Each element may be either a 1D numpy array or a list of such arrays.
last_nt_step	list[int]	A list of axis indices that represent the last measured near-time point. Only covers outer near-time dimensions.
handle	str | None	Acquire handle used for capturing the results. Added in version 2.16.0

to_xarray(copy=False)

Convert to xarray.DataArray.

Requires optional dependency xarray to be installed.

By default, the data in the returned object is a view of the data, and will get updated if it is created during experiment runtime.

By setting copy to True, the returned data will be detached from the AcquiredResult data.

Parameters:

Name	Type	Description	Default
copy	bool	If True, returns a copy of the data instead of a view.	False

Returns:

Type	Description
DataArray	An xarray.DataArray representation of the object. The name is that of the result handle. The coordinates correspond to the axis_name of the individual sweep parameters. The dimensions have fixed names axis_0, axis_1 etc..

Raises:

Type	Description
ModuleNotFoundError	If xarray is not installed.

Changed in version 2.26.0

Names of the coordinates are now the values of the axis_name instead of generic sweep_n.

Names of the dimensions are in the format of axis_0, axis_1etc.

Added in version 2.16.0