laboneq.dsl.result

Results

Results of an LabOne Q experiment.

In addition to being accessible via the attributes and methods defined below, the acquired_results are also accessible directly on the result object itself using either attribute or dictionary-like item lookup.

For example::

```python
results = Results(
    acquired_results={
        "cal_trace/q0/g": AcquiredResult(
            data=numpy.array([1, 2, 3]),
            axis_name=["Amplitude"],
            axis=[numpy.array([0, 1, 2])],
        ),
    },
)

# These all return the same data:
results.cal_trace.q0.g
results["cal_trace"]["q0"]["g"]
results["cal_trace/q0/g"]
```

Attributes:

Name	Type	Description
experiment	Experiment	The source experiment. Deprecated.
device_setup	DeviceSetup	The device setup on which the experiment was run. Deprecated.
acquired_results	AcquiredResults	The acquired results, organized by handle.
neartime_callback_results	dict[str, list[Any]]	Dictionary of the results of near-time callbacks by their name.
execution_errors	list[tuple[list[int], str, str]]	A list of errors 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.

Removed in version 2.57.0

Removed the .user_func_results attribute and argument that were deprecated in version 2.19.0. Use .neartime_callback_results instead.

Removed in version 2.55.0

The deprecated .compiled_experiment attribute was removed. Track the compiled experiment separately instead.

Removed in version 2.54.0

The following deprecated methods for saving and loading were removed: - load - save Use the load and save functions from the laboneq.simple module instead.

Deprecated in version 2.52.0.

The experiment, device_setup and compiled_experiment attributes were deprecated in version 2.52.0 and are only populated when requested via Session or Session.run.

acquired_results = attrs.field(factory=AcquiredResults) class-attribute instance-attribute

data property

The results acquired during the real-time experiment.

Added in version 2.52.0

The .data attribute was added.

device_calibration property

Get the device setup's calibration.

See also DeviceSetup.get_calibration.

Deprecated in version 2.52.0

Use .device_setup.get_calibration() instead.

device_setup = attrs.field(default=None) class-attribute instance-attribute

errors property

The errors that occurred during running the experiment.

Added in version 2.52.0

The .errors attribute was added. The name was chosen to match that used on the (now removed) RunExperimentResults class.

execution_errors = attrs.field(factory=list) class-attribute instance-attribute

experiment = attrs.field(default=None) class-attribute instance-attribute

experiment_calibration property

Return the experiment calibration.

Deprecated in version 2.52.0

Use .experiment.get_calibration() instead.

neartime_callback_results = attrs.field(default=None) class-attribute instance-attribute

neartime_callbacks property

The results of the near-time user callbacks.

Added in version 2.52.0

The .neartime_callbacks attribute was added. The name was chosen to match that used on the (now removed) RunExperimentResults class.

pipeline_jobs_timestamps = attrs.field(factory=dict) class-attribute instance-attribute

signal_map property

Return the experiment signal map.

Deprecated in version 2.52.0

Use .experiment.get_signal_map() instead.

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] | complex128	A multidimensional numpy array, where each dimension corresponds to a sweep
NDArray[Any] | complex128	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.

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 or complex	A multidimensional numpy array, where each dimension corresponds to a sweep loop nesting level, the outermost sweep being the first dimension. Or, if there is only a single measurement, a complex scalar.
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