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).
validate_file([path, file])	Validate the structure and data of a zea HDF5 file.

Classes

ChunkedDataset(dset, fetcher)	An h5py.Dataset whose reads go through zea.data.chunk_reader.
CustomElement(name, data, description, unit)	Class to store custom dataset elements with a name, data, description and unit in the zea format.
CustomElements(elements)	A list of CustomElement with name/group based dict- and dot-access.
File(name[, mode])	File handler for zea formatted ultrasound files.
Track(index, group[, timestamps, label, ...])	A single acquisition track within a File.

class zea.data.file.ChunkedDataset(dset, fetcher)

Bases: object

An h5py.Dataset whose reads go through zea.data.chunk_reader.

Behaves exactly like the dataset it wraps, except that slicing fetches the chunk byte ranges itself and decodes them concurrently; reads the fast path does not understand fall back to h5py, so the result is always what h5py would have returned.

Handed out by _GroupProxy, so file.data.raw_data[0:8] is already on the fast path. file["data/raw_data"] still returns the bare h5py.Dataset.

class zea.data.file.CustomElement(name, data, description, unit, group_name='')

Bases: object

Class to store custom dataset elements with a name, data, description and unit in the zea format.

data: ndarray

description: str

group_name: str = ''

name: str

unit: str

class zea.data.file.CustomElements(elements)

Bases: object

A list of CustomElement with name/group based dict- and dot-access.

Behaves like list[CustomElement] — iteration, len(), positional indexing/slicing, and equality with a plain list all work as before. On top of that, elements can be looked up by name, and nested group_name groups can be walked into with dict- or dot-style access:

f.custom["lens_correction"]  # by name
f.custom.lens_correction  # same, as an attribute
f.custom["lens"]["profile"]  # into a nested group_name
f.custom.lens.profile  # same
f.custom["lens/profile"]  # slash-path shortcut for the above

Dot access only works for names that are valid Python identifiers (snake_case is recommended, and enforced when saving new files — see CustomElement); names with spaces or other characters are still reachable via [...] bracket access.

Note

This wraps rather than subclasses list, so a custom element named "keys" shadows that method for attribute access — use f.custom["keys"] in that case.

keys()

Top-level names: leaf element names plus immediate sub-group names.

class zea.data.file.Track(index, group, timestamps=None, label=None, probe=None, fetcher=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: _DataProxy

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, slice, None]) – The indices to load. Defaults to None in which case all frames are loaded.

• scan_kwargs (dict | None) – 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.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 | None) – Path to the HDF5 file.

• file (File | None) – 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.