lyse.Run

class lyse.Run(h5_path, no_write=False)[source]

Bases: object

A class for saving/retrieving data to/from a shot’s hdf5 file.

This class implements methods that allow the user to retrieve data from a shot’s hdf5 file such as images, traces, and the values of globals. It also provides methods for saving and retrieving results from analysis.

Parameters:

h5_path (str) – The path, including file name and extension, to the hdf5 file for a shot.
no_write (bool, optional) – Set to True to prevent editing the shot’s hdf5 file. Note that doing so prohibits the ability to save results to the file. Defaults to False.

__init__(h5_path, no_write=False)[source]

Methods

`__init__`(h5_path[, no_write])
`get_all_image_labels`()	Return all existing images labels in the h5 file.
`get_attrs`(group)	Returns all attributes of the specified group as a dictionary.
`get_globals`([group])	Get globals from the shot.
`get_globals_expansion`()	Get the expansion type of each global.
`get_globals_raw`([group])	Get the raw global values from the shot.
`get_image`(orientation, label, image)	Get previously saved image from the h5 file.
`get_image_attributes`(orientation)	Return the attributes of a saved orientation image group.
`get_images`(orientation, label, *images)	Get multiple saved images from orientation and label.
`get_images_dict`(orientation, label, *images)	Get multiple saved images from orientation and label.
`get_result`(group, name)	Retrieve result from prior calculation.
`get_result_array`(group, name)	Returns saved results data.
`get_result_arrays`(group, *names)	Retrieve multiple result arrays from the same group.
`get_results`(group, *names)	Return multiple results from the same group.
`get_trace`(name[, raw_data])	Return the saved data trace `name`.
`get_traces`(*names)	Retrieve multiple data traces.
`get_units`([group])	Get the units of globals.
`get_wait`(name)	Returns the wait parameters: label, timeout, duration, and time out status.
`get_waits`()	Returns the parameters of all waits in the experiment.
`globals_diff`(other_run[, group])	Take a diff between this run and another run.
`globals_groups`()	Get names of all the globals groups.
`open`(mode)	Context manager to open the Run's h5 file for successive reads/writes.
`save_result`(name, value[, group, overwrite])	Save a result to the hdf5 file.
`save_result_array`(name, data[, group, ...])	Save an array of data to the hdf5 h5 file.
`save_result_arrays`(args, *kwargs)	Save multiple result arrays.
`save_results`(args, *kwargs)	Save multiple results to the hdf5 file.
`save_results_dict`(results_dict[, uncertainties])	Save results dictionary.
`set_group`(groupname)	Set the default hdf5 file group for saving results.
`trace_names`()	Return a list of all saved data traces in Run.

Attributes

`group`	The group in the hdf5 file in which results are saved by default.
`h5_file`	opened h5py file handle for the shot
`h5_path`	The value provided for `h5_path` during instantiation.
`no_write`	The value provided for `no_write` during instantiation.

get_all_image_labels()[source]

Return all existing images labels in the h5 file.

Returns:: Dictionary of the form {orientation:[label1,label2]}
Return type:: dict

get_attrs(group)[source]

Returns all attributes of the specified group as a dictionary.

Parameters:: group (str) – Group for which attributes are desired.
Raises:: Exception – If the group does not exist.
Returns:: Dictionary of attributes.
Return type:: dict

get_globals(group=None)[source]

Get globals from the shot.

Parameters:: group (str, optional) – If None, return all global variables. If defined, only return globals from group.
Returns:: Dictionary of globals and their values.
Return type:: dict

get_globals_expansion()[source]

Get the expansion type of each global.

This will skip global variables that do not have an expansion.

Parameters:: h5_file (h5py.File, optional) – Allows passing in a handle to an already opened h5 file. If None, will open in read only mode and close after operation.
Returns:: Dcitionary of globals with their expansion type.
Return type:: dict

get_globals_raw(group=None)[source]

Get the raw global values from the shot.

Parameters:: group (str, optional) – If None, return all global variables. If defined, only return globals from group.
Returns:: Dictionary of raw globals and their values
Return type:: dict

get_image(orientation, label, image)[source]

Get previously saved image from the h5 file.

h5 path to saved image is /images/orientation/label/image

Parameters:

orientation (str) – Orientation label for saved image.
label (str) – Label of saved image.
image (str) – Identifier of saved image.

Raises:

Exception – If the image or paths do not exist.

Returns:

2-D image array.

Return type:

numpy.ndarray

get_image_attributes(orientation)[source]

Return the attributes of a saved orientation image group.

Parameters:: orientation (str) – Orientation label to get attributes of.
Raises:: Exception – If images or orientation group do not exist.
Returns:: Dictionary of attributes and their values.
Return type:: dict

get_images(orientation, label, *images)[source]

Get multiple saved images from orientation and label.

Iteratively calls self.get_image(orientation,label,image) for each image argument.

Parameters:

orientation (str) – Orientation label of saved images.
label (str) – Label of saved images.
*images (str) – Collection of images to return

Returns:

List of 2-D images.

Return type:

list of numpy.ndarray

get_images_dict(orientation, label, *images)[source]

Get multiple saved images from orientation and label.

Iteratively calls self.get_image(orientation,label,image) for each image argument.

Parameters:

orientation (str) – Orientation label of saved images.
label (str) – Label of saved images.
*images (str) – Collection of images to return

Returns:

Dictionary of 2-D images.

Return type:

dict of numpy.ndarray

get_result(group, name)[source]

Retrieve result from prior calculation.

Parameters:

group (str) – Group to look in for the result. Typically the name of the analysis script that created it.
name (str) – Name of the result.

Raises:

Exception – If group or name do not already exist.

Returns:

Result with appropriate type, as determined by labscript_utils.properties.get_attribute.

get_result_array(group, name)[source]

Returns saved results data.

Parameters:

group (str) – Group to look in for the array. Typically the name of the analysis script that created it.
name (str) – Name of the results array to return.

Raises:

Exception – If group or name do not already exist.

Returns:

Numpy array of the saved data.

Return type:

numpy.ndarray

get_result_arrays(group, *names)[source]

Retrieve multiple result arrays from the same group.

Iteratively calls self.get_result_array(group,name) with default arguments.

Parameters:

group (str) – Group to obtain the results from.
*names (str) – Result names to retrieve.

Returns:

List of results.

Return type:

list

get_results(group, *names)[source]

Return multiple results from the same group.

Iteratively calls get_result(group,name) for each name provided.

Parameters:

group (str) – Group to look in for the results. Typically the name of the analysis script that created it.
*names (str) – Names of results to retrieve.

Returns:

List of the results, in the same order as specified by names. If names does not preserve order, return order is not guaranteed.

Return type:

list

get_trace(name, raw_data=False)[source]

Return the saved data trace name.

Parameters:

name (str) – Name of saved data trace to get.
raw_data (bool, optional) – option to return the h5_data directly without interpreting it as a 2-D time trace.

Raises:

Exception – If name trace does not exist.

Returns:

Returns 2-D timetrace of times 't' and values 'values'.

Return type:

numpy.ndarray

get_traces(*names)[source]

Retrieve multiple data traces.

Iteratively calls get_trace.

Parameters:: *names (str) – Names of traces to retrieve
Returns:: List of numpy arrays.
Return type:: list

get_units(group=None)[source]

Get the units of globals.

This method retrieves the values in the “Units” column of runmanager for this shot. The values are returned in a dictionary where the keys are the names of globals and the values are the corresponding units.

Parameters:: group (str, optional) – The name of the globals group for which the units will be retrieved. Globals and units from other globals groups will not be included in the returned dictionary. If set to None then all globals from all globals groups will be returned. If group is set to a value that isn’t the name of a globals group, then an empty dictionary will be returned, but no error will be raised. Defaults to None.
Returns:: A dictionary in which each key is a string giving the name of a global, and each value is a string specifying the corresponding value in the “Units” column of runmanager. An empty dictionary will be returned if group is set to a value that isn’t the name of a globals group.
Return type:: dict

get_wait(name)[source]

Returns the wait parameters: label, timeout, duration, and time out status.

Parameters:: name (str) – Name of the wait to get.
Raises:: KeyError if name wait does not exist. –
Returns:: Tuple of the wait parameters.
Return type:: tuple

get_waits()[source]

Returns the parameters of all waits in the experiment.

Raises:: Exception – If the experiment has no waits.
Returns:: Returns 2D structured numpy array of the waits and their parameters.
Return type:: numpy.ndarray

globals_diff(other_run, group=None)[source]

Take a diff between this run and another run.

This calls globals_diff(self, other_run, group).

Parameters:

other_run (Run) – Run to compare to.
group (str, optional) – When None (default), compare all globals. Otherwise only compare globals in group.

Returns:

Dictionary of different globals.

Return type:

dict

globals_groups()[source]

Get names of all the globals groups.

Returns:: List of global group names.
Return type:: list

property group

The group in the hdf5 file in which results are saved by default.

When a Run instance is created from within a lyse singleshot or multishot routine, group will be set to the name of the running routine. If created from outside a lyse script it will be set to None. To change the default group for saving results, use the set_group() method. Note that if self.group is None and no value is provided for the optional group argument used by the save...() methods, a ValueError will be raised.

Attempting to directly set self.group’s value will automatically call self.set_group().

Type:: str

property h5_file

opened h5py file handle for the shot

Type:: h5py.File

property h5_path

The value provided for h5_path during instantiation.

Type:: str

property no_write

The value provided for no_write during instantiation.

Type:: bool

open(mode)[source]

Context manager to open the Run’s h5 file for successive reads/writes.

Supports all h5 modes, though only 'r' and 'r+'/'a' are typically used within lyse itself.

Parameters:: mode (str) – which h5py.File mode to open the h5 file with. Must be ‘r’, ‘a’, ‘r+’, ‘w’, ‘w-’, or ‘x’. Lyse typically only uses ‘r’ and ‘r+’.
Yields:: Run – Handle to opened Run object.
Raises:: PermissionError – If the Run is set as read-only but a write mode is requested

Examples

Trivial example that selectively opens the file during analysis. For better performance, it would be better to combine these two openings into one.

>>> from lyse import *
>>> shot = Run(path)
>>> with shot.open('r'):
>>>     # shot processing that requires reads/writes
>>>     _, vals = shot.get_trace('my_trace')
>>> with shot.open('r+'):
>>>     results = vals**2
>>>     shot.save_result_array('my_result', results)
>>>     _, vals2 = shot.get_trace('my_other_trace')
>>>     shot.save_result('my_result2', vals2.mean())
>>> # Shot processing that doesn't require h5 reads/writes
>>> print(f'Max of results is {results.max():.3f}')
Max of results is 5.003

Open and create the shot handle for the whole analysis in a single line.

>>> from lyse import *
>>> with Run(path).open('r+') as shot:
>>>     # shot processing that requires reads/writes
>>>     t, vals = shot.get_trace('my_trace')
>>>     results = vals**2
>>>     shot.save_result_array('my_result', results)
>>>     # Shot processing that doesn't require h5 reads/writes
>>>     # could be outside the context
>>>     print(f'Max of results is {results.max():.3f}')
Max of results is 5.003

save_result(name, value, group=None, overwrite=True)[source]

Save a result to the hdf5 file.

With the default argument values this method saves to self.group in the '/results' group and overwrites any existing value. Note that the result is saved as an attribute and overwriting attributes causes hdf5 file size bloat.

Parameters:

name (str) – The name of the result. This will be the name of the attribute added to the hdf5 file’s group.
value (any) – The value of the result, which will be saved as the value of the hdf5 group’s attribute set by name. However note that when saving large arrays, it is better to use the self.save_result_array() method which will store the results as a dataset in the hdf5 file.
group (str, optional) – The group in the hdf5 file to which the result will be saved as an attribute. If set to None, then the result will be saved to self.group in '/results'. Note that if a value is passed for group here then it will NOT have '/result' prepended to it which allows the caller to save results anywhere in the hdf5 file. This is in contrast to using the default group set with self.set_group(); when the default group is set with that method it WILL have '/results' prepended to it when saving results. Defaults to None.
overwrite (bool, optional) – Sets whether or not to overwrite the previous value if the attribute already exists. If set to False and the attribute already exists, a PermissionError is raised. Defaults to True.

Raises:

PermissionError – A PermissionError is raised if self.no_write is True because saving the result would edit the file.
ValueError – A ValueError is raised if self.group is None and no value is provided for group because the method then doesn’t know where to save the result.
PermissionError – A PermissionError is raised if an attribute with name name already exists but overwrite is set to False.

save_result_array(name, data, group=None, overwrite=True, keep_attrs=False, **kwargs)[source]

Save an array of data to the hdf5 h5 file.

With the default argument values this method saves to self.group in the '/results' group and overwrites any existing value without keeping the dataset’s previous attributes. Additional keyword arguments are passed directly to h5py.Group.create_dataset.

Parameters:

name (str) – The name of the result. This will be the name of the dataset added to the hdf5 file.
data (numpy.array) – The data to save to the hdf5 file.
group (str, optional) – The group in the hdf5 file in which the result will be saved as a dataset. If set to None, then the result will be saved in self.group in '/results'. Note that if a value is passed for group here then it will NOT have '/result' prepended to it which allows the caller to save results anywhere in the hdf5 file. This is in contrast to using the default group set with self.set_group(); when the default group is set with that method it WILL have '/results' prepended to it when saving results. Defaults to None..
overwrite (bool, optional) – Sets whether or not to overwrite the previous value if the dataset already exists. If set to False and the dataset already exists, a PermissionError is raised. Defaults to True.
keep_attrs (bool, optional) – Whether or not to keep the dataset’s attributes when overwriting it, i.e. if the dataset already existed. Defaults to False.
**kwargs – Optional kwargs passed directly to h5_file.create_dataset()

Raises:

PermissionError – A PermissionError is raised if self.no_write is True because saving the result would edit the file.
ValueError – A ValueError is raised if self.group is None and no value is provided for group because the method then doesn’t know where to save the result.
PermissionError – A PermissionError is raised if a dataset with name name already exists but overwrite is set to False.

save_result_arrays(*args, **kwargs)[source]

Save multiple result arrays.

Iteratively calls save_result_array() on multiple data sets. Assumes arguments are ordered such that each dataset to be saved is preceded by the name to save it as. All keyword arguments are passed to each call of save_result_array().

Parameters:

*args – Ordered arguments such that each dataset to be saved is preceded by the name to save it as.
**kwargs – Passed through to save_result_array as kwargs.

save_results(*args, **kwargs)[source]

Save multiple results to the hdf5 file.

This method iteratively calls self.save_result() on multiple results. It assumes arguments are ordered such that each result to be saved is preceded by the name of the attribute to save it under. Keywords arguments are passed to each call of self.save_result().

Parameters:

*args – The names and values of results to be saved. The first entry should be a string giving the name of the first result, and the second entry should be the value for that result. After that, an arbitrary number of additional pairs of result name strings and values can be included, e.g. 'name0', value0, 'name1', value1,....
**kwargs – Keyword arguments are passed to self.save_result(). Note that the names and values of keyword arguments are NOT saved as results to the hdf5 file; they are only used to provide values for the optional arguments of self.save_result().

Examples

>>> run = Run('path/to/an/hdf5/file.h5')  
>>> a = 5
>>> b = 2.48
>>> run.save_results('result', a, 'other_result', b, overwrite=False)  

save_results_dict(results_dict, uncertainties=False, **kwargs)[source]

Save results dictionary.

Iteratively calls self.save_result(key,value) on the provided dictionary. If uncertainties is True, value is a two-element list where the second element is the uncertainty in the result and saved with to the same key with u_ prepended.

Parameters:

results_dict (dict) – Dictionary of results to save. If uncertainties is False, form is {name:value}. If True, for is {name,[value,uncertainty]}.
uncertainties (bool, optional) – Marks if uncertainties are provided.
**kwargs – Extra arguments provided to save_result.

set_group(groupname)[source]

Set the default hdf5 file group for saving results.

The save...() methods will save their results to self.group if an explicit value for their optional group argument is not given. This method updates self.group, making sure to create the group in the hdf5 file if it does not already exist.

Parameters:: groupname (str) – The name of the hdf5 file group in which to save results by default. The group will be created in the '/results' group of the hdf5 file.

trace_names()[source]

Return a list of all saved data traces in Run.

Raises:: KeyError – If the group '/data/traces/' does not yet exist.
Returns:: List of keys in the h5 file’s '/data/traces/' group.
Return type:: list