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.
`compiled_experiment`	`CompiledExperiment`	The compiled experiment that was executed. 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.
`user_func_results`		Alias for neartime_callback_results. Deprecated.
`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.

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.

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 = attrs.field(factory=AcquiredResults)` `class-attribute` `instance-attribute` ¶

`compiled_experiment = attrs.field(default=None)` `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.

`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.

`user_func_results` `property` ¶

Alias for neartime_callback_results.

Deprecated in version 2.19.0

The .user_func_results attribute was deprecated in version 2.19.0. Use .neartime_callback_results 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.

`load(filename)` `staticmethod` ¶

Load the result from a specified file.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The file to load the result from.	required

Deprecated in version 2.50.0

Use laboneq.simple.load instead.

`save(filename)` ¶

Save the result to a specified file.

Parameters:

Name	Type	Description	Default
`filename`	`str`	The name of the file to save the result to.	required

Deprecated in version 2.50.0

Use laboneq.simple.save instead.

`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

laboneq.dsl.result¶

Results ¶

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

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

data property ¶

device_calibration property ¶

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

errors property ¶

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

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

experiment_calibration property ¶

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

neartime_callbacks property ¶

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

signal_map property ¶

user_func_results property ¶

get_axis(handle) ¶

get_axis_name(handle) ¶

get_data(handle) ¶

get_last_nt_step(handle) ¶

get_result(handle) ¶

load(filename) staticmethod ¶

save(filename) ¶

AcquiredResults ¶

to_xarray(copy=False) ¶

AcquiredResult() dataclass ¶

to_xarray(copy=False) ¶

`Results` ¶

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

`compiled_experiment = attrs.field(default=None)` `class-attribute` `instance-attribute` ¶

`data` `property` ¶

`device_calibration` `property` ¶

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

`errors` `property` ¶

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

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

`experiment_calibration` `property` ¶

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

`neartime_callbacks` `property` ¶

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

`signal_map` `property` ¶

`user_func_results` `property` ¶

`get_axis(handle)` ¶

`get_axis_name(handle)` ¶

`get_data(handle)` ¶

`get_last_nt_step(handle)` ¶

`get_result(handle)` ¶

`load(filename)` `staticmethod` ¶

`save(filename)` ¶

`AcquiredResults` ¶

`to_xarray(copy=False)` ¶

`AcquiredResult()` `dataclass` ¶

`to_xarray(copy=False)` ¶