zea.data.file

zea data file (HDF5).

Functions

assert_key(file, key)	Asserts key is in a h5py.File.
load_dict_from_hdf5_group(group)	Recursively load the contents of an HDF5 group into a plain dict.
load_file(path[, data_type, indices, ...])	Loads a zea data files (h5py file).
load_file_all_data_types(path[, indices, ...])	Loads a zea data files (h5py file).
validate_file([path, file])	Validate the structure and data of a zea HDF5 file.

Classes

File(name[, mode])	h5py.File in zea format.
Track(index, group[, timestamps, label, probe])	A single acquisition track within a File.

class zea.data.file.Track(index, group, timestamps=None, label=None, probe=None)

Bases: object

A single acquisition track within a File.

Provides the same .data, .scan and .load_parameters() interface as File but scoped to one tracks/track_N group. Obtain instances through File.tracks rather than constructing this class directly.

Example:

with File("multi_track.hdf5") as f:
    for track in f.tracks:
        raw = track.data.raw_data[:]
        parameters = track.load_parameters()

property data: _GroupProxy

Lazy proxy for this track’s data group.

property label: str | None

Human-readable name for this track (e.g. 'focused' or 'planewave').

Returns None for single-track files or legacy files written without a label. Use File.track_labels to print all labels in acquisition order and File.get_track() to retrieve a track by name.

load_parameters(**overrides)

Load this track’s parameters (merged probe + scan) as Parameters.

Each track shares the same probe but has its own scan, so the returned object has the same shape as File.load_parameters() for a single-track file.

Parameters:

**overrides – Override any parameter.

Returns:

Initialised parameters object for this track.

Return type:

Parameters

property n_ax: int

Number of axial samples.

property n_el: int

Number of elements.

property n_frames: int

Number of frames.

property n_tx: int

Number of transmit events.

property scan: ScanSpec

Return the validated ScanSpec for this track.

This is the bare scan group as a spec object. For a full, derivable parameter object (merged probe + scan) use load_parameters().

property timestamps: ndarray | None

Global transmit timestamps for this track, shape (n_frames, n_tx).

Timestamps are pre-computed when the Track is created via File.tracks. Returns None if the file has no track_schedule or any track is missing time_to_next_transmit.

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

Asserts key is in a h5py.File.

zea.data.file.load_dict_from_hdf5_group(group)

Recursively load the contents of an HDF5 group into a plain dict.

Datasets are returned as numpy arrays or scalars; nested groups are converted recursively. String datasets are decoded to np.str_.

Parameters:

group (Group) – An open h5py.Group (or h5py.File).

Returns:

Nested dictionary mirroring the group structure.

Return type:

dict

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

Loads a zea data files (h5py file).

Returns the data together with a parameters object containing the parameters of the acquisition. Probe information is available via parameters.to_probe_dict() or File.probe.

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

The indices parameter can be used to load a subset of the data. This can be

• 'all' or None to load all data

• an int to load a single frame

• a List[int] to load specific frames

• a Tuple[Union[list, slice, int], ...] to index multiple axes (i.e. frames and transmits). Note that

  indexing with lists of indices for multiple axes is not supported. In that case, try to define one of the axes with a slice for optimal performance. Alternatively, slice the data after loading.

For more information on the indexing options, see indexing on ndarrays and fancy indexing in h5py.

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 (Union[Tuple[Union[list, slice, int], ...], List[int], int, None]) – The indices to load. Defaults to None in which case all frames are loaded.

• scan_kwargs (dict) – Additional keyword arguments to pass to File.load_parameters(). These will override the parameters from the file if they are present. Defaults to None.

Returns:

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

Return type:

Tuple[ndarray, Parameters]

zea.data.file.load_file_all_data_types(path, indices=None, scan_kwargs=None)

Loads a zea data files (h5py file).

Returns all data types together with a parameters object containing the parameters of the acquisition. Probe information is available via parameters.to_probe_dict() or File.probe.

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

The indices parameter can be used to load a subset of the data. This can be

• 'all' or None to load all data

• an int to load a single frame

• a List[int] to load specific frames

• a Tuple[Union[list, slice, int], ...] to index multiple axes (i.e. frames and transmits). Note that

  indexing with lists of indices for multiple axes is not supported. In that case, try to define one of the axes with a slice for optimal performance. Alternatively, slice the data after loading.

For more information on the indexing options, see indexing on ndarrays and fancy indexing in h5py.

Parameters:

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

• indices (Union[Tuple[Union[list, slice, int], ...], List[int], int, None]) – The indices to load. Defaults to None in which case all frames are loaded.

• scan_kwargs (dict) – Additional keyword arguments to pass to File.load_parameters(). These will override the parameters from the file if they are present. Defaults to None.

Returns:

A dictionary with all data types as keys and the corresponding data as values. (Parameters): A parameters object containing the parameters of the acquisition.

Return type:

(dict)

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

Validate the structure and data of a zea HDF5 file.

For files created with zea v0.1.0 and later this runs the full FileSpec schema validation (dtypes, shapes, and dimension consistency). Legacy files (before zea v0.1.0) are detected by the presence of scalar dataset scan/n_frames; for those only a lightweight structural data group check is performed.

Provide either path or file, but not both.

Parameters:

• path (str) – Path to the HDF5 file.

• file (File) – An already-open File instance.

Returns:

{"status": "success"} on success.

Return type:

dict

Raises:

• AssertionError – If the file is missing the data group.

• TypeError, ValueError – If spec validation fails on files created with zea v0.1.0 and later.