zea.data.file

zea H5 file functionality.

Functions

assert_key(file, key)	Asserts key is in a h5py.File.
load_file(path[, data_type, indices, ...])	Loads a zea data files (h5py file).
recursively_load_dict_contents_from_group(...)	Load dict from contents of group
validate_file([path, file])	Reads the hdf5 file at the given path and validates its structure.

Classes

File(name, *args, **kwargs)

h5py.File in zea format.

class zea.data.file.File(name, *args, **kwargs)

Bases: File

h5py.File in zea format.

static check_data(data, key)

Check the data for a given key. For example, will check if the shape matches the data type (such as raw_data, …)

copy_key(key, dst)

Copy a specific key to another file.

Will always copy the attributes and the scan data if it exists. Will warn if the key is not in this file or if the key already exists in the destination file.

Parameters:

• key (str) – The key to copy.

• dst (File) – The destination file to copy the key to.

property description

Reads the description from the data file and returns it.

property event_keys

Return all events in the file.

events_have_same_shape(key)

Check if all events have the same shape for a given key.

format_key(key)

Format the key to match the data type.

get_event_shapes(key)

Get the shapes of a key for all events.

get_parameters(event=None)

Returns a dictionary of parameters to initialize a scan object that comes with the file (stored inside datafile).

If there are no scan parameters in the hdf5 file, returns an empty dictionary.

Parameters:

event (int, optional) –

Event number. When specified, an event structure is expected as follows:

event_0 / scan
event_1 / scan
...

Defaults to None. In that case no event structure is expected.

Returns:

The scan parameters.

Return type:

dict

get_probe_parameters(event=None)

Returns a dictionary of probe parameters to initialize a probe object that comes with the file (stored inside datafile).

Returns:

The probe parameters.

Return type:

dict

get_scan_parameters(event=None)

Returns a dictionary of default parameters to initialize a scan object that works with the file.

Returns:

The default parameters (the keys are identical to the

__init__ parameters of the Scan class).

Return type:

dict

classmethod get_shape(path, key)

Get the shape of a key in a file.

Parameters:

• path (str) – The path to the file.

• key (str) – The key to get the shape of.

Returns:

The shape of the key.

Return type:

tuple

property has_events

Check if the file has events.

static key_to_data_type(key)

Convert the key to a data type.

load_data(data_type, indices='all')

Load data from the file.

Parameters:

• data_type (str) – The type of data to load. Options are ‘raw_data’, ‘aligned_data’, ‘beamformed_data’, ‘envelope_data’, ‘image’ and ‘image_sc’.

• indices (str, int, list, optional) – The indices to load. Defaults to “all” in which case all frames are loaded. If an int is provided, it will be used as a single index. If a list is provided, it will be used as a list of indices.

load_scan(event=None)

Alias for get_scan_parameters.

load_transmits(key, selected_transmits)

Load raw_data or aligned_data for a given list of transmits. :param data_type: The type of data to load. Options are ‘raw_data’ and ‘aligned_data’. :type data_type: str :type selected_transmits: :param selected_transmits: The transmits to load. :type selected_transmits: list, np.ndarray

property n_frames

Return number of frames in a file.

property name

Return the name of the file.

property path

Return the path of the file.

probe(event=None)

Returns a Probe object initialized with the parameters from the file.

Parameters:

event (int, optional) –

Event number. When specified, an event structure is expected as follows:

event_0 / scan
event_1 / scan
...

Defaults to None. In that case, no event structure is expected.

Returns:

The probe object.

Return type:

Probe

property probe_name

Reads the probe name from the data file and returns it.

recursively_load_dict_contents_from_group(path, squeeze=False)

Load dict from contents of group

Values inside the group are converted to numpy arrays or primitive types (int, float, str). Single element arrays are converted to the corresponding primitive type (if squeeze=True)

Parameters:

• path (str) – path to group

• squeeze (bool, optional) – squeeze arrays with single element. Defaults to False.

Returns:

dictionary with contents of group

Return type:

dict

scan(event=None, **kwargs)

Returns a Scan object initialized with the parameters from the file.

Parameters:

• event (int, optional) –

  Event number. When specified, an event structure is expected as follows:

  event_0 / scan
  event_1 / scan
  ...
  

  Defaults to None. In that case no event structure is expected.

• **kwargs – Additional keyword arguments to pass to the Scan object. These will override the parameters from the file if they are present in the file.

Returns:

The scan object.

Return type:

Scan

shape(key)

Return shape of some key, or all events.

Return type:

tuple

property stem

Return the stem of the file.

summary()

Print the contents of the file.

to_iterator(key)

Convert the data to an iterator over all frames.

validate()

Validate the file structure.

Returns:

A dictionary with the validation results.

Return type:

dict

zea.data.file.assert_key(file, key)

Asserts key is in a h5py.File.

zea.data.file.load_file(path, data_type='raw_data', indices='all', scan_kwargs=None)

Loads a zea data files (h5py file).

Returns the data together with a scan object containing the parameters of the acquisition and a probe object containing the parameters of the probe.

Additionally, it can load a specific subset of frames / transmits.

# TODO: add support for event

Parameters:

• path (str, pathlike) – The path to the hdf5 file.

• data_type (str, optional) – The type of data to load. Defaults to ‘raw_data’. Other options are ‘aligned_data’, ‘beamformed_data’, ‘envelope_data’, ‘image’ and ‘image_sc’.

• indices (str, int, list, optional) – The indices to load. Defaults to “all” in which case all frames are loaded. If an int is provided, it will be used as a single index. If a list is provided, it will be used as a list of indices.

• scan_kwargs (Config, dict, optional) – Additional keyword arguments to pass to the Scan object. These will override the parameters from the file if they are present in the file. Defaults to None.

Returns:

The raw data of shape (n_frames, n_tx, n_ax, n_el, n_ch). (Scan): A scan object containing the parameters of the acquisition. (Probe): A probe object containing the parameters of the probe.

Return type:

(np.ndarray)

zea.data.file.recursively_load_dict_contents_from_group(h5file, path, squeeze=False)

Load dict from contents of group

Values inside the group are converted to numpy arrays or primitive types (int, float, str). Single element arrays are converted to the corresponding primitive type (if squeeze=True)

Parameters:

• h5file (h5py._hl.files.File) – h5py file object

• path (str) – path to group

• squeeze (bool, optional) – squeeze arrays with single element. Defaults to False.

Returns:

dictionary with contents of group

Return type:

dict

zea.data.file.validate_file(path=None, file=None)

Reads the hdf5 file at the given path and validates its structure.

Provide either the path or the file, but not both.

Parameters:

• path (str, pathlike) – The path to the hdf5 file.

• file (File) – The hdf5 file.