Skip to content

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) 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

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

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[ArrayLike | list[ArrayLike]]

A list of axis grids. Each element may be either a 1D numpy array or a list of such

list[ArrayLike | list[ArrayLike]]

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
ArrayLike

A multidimensional numpy array, where each dimension corresponds to a sweep

ArrayLike

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 ArrayLike

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[ArrayLike | list[ArrayLike]]

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