zea.data.data_format

Functions to write and validate datasets in the zea format.

Functions

generate_zea_dataset(path[, raw_data, ...])

Generates a dataset in the zea format.

load_additional_elements(path)

Loads additional dataset elements from a zea dataset.

load_description(path)

Loads the description of a zea dataset.

validate_input_data(raw_data, aligned_data, ...)

Validates input data for generate_zea_dataset

Classes

DatasetElement(dataset_name, data, ...[, ...])

Class to store a dataset element with a name, data, description and unit.
class zea.data.data_format.DatasetElement(dataset_name, data, description, unit, group_name='')[source]

Bases: object

Class to store a dataset element with a name, data, description and unit. Used to supply additional dataset elements to the generate_zea_dataset function.

data: ndarray
dataset_name: str
description: str
group_name: str = ''
unit: str
zea.data.data_format.generate_zea_dataset(path, raw_data=None, aligned_data=None, envelope_data=None, beamformed_data=None, image=None, image_sc=None, probe_geometry=None, sampling_frequency=None, center_frequency=None, demodulation_frequency=None, initial_times=None, t0_delays=None, sound_speed=None, probe_name=None, description='No description was supplied', focus_distances=None, transmit_origins=None, polar_angles=None, azimuth_angles=None, tx_apodizations=None, bandwidth_percent=None, time_to_next_transmit=None, tgc_gain_curve=None, element_width=None, tx_waveform_indices=None, waveforms_one_way=None, waveforms_two_way=None, additional_elements=None, cast_to_float=True, overwrite=False, enable_compression=True)[source]

Generates a dataset in the zea format.

Parameters:

  • path (str) – The path to write the dataset to.

  • raw_data (np.ndarray) – The raw data of the ultrasound measurement of shape (n_frames, n_tx, n_ax, n_el, n_ch).

  • aligned_data (np.ndarray) – The aligned data of the ultrasound measurement of shape (n_frames, n_tx, n_ax, n_el, n_ch).

  • envelope_data (np.ndarray) – The envelope data of the ultrasound measurement of shape (n_frames, grid_size_z, grid_size_x).

  • beamformed_data (np.ndarray) – The beamformed data of the ultrasound measurement of shape (n_frames, grid_size_z, grid_size_x, n_ch).

  • image (np.ndarray) – The ultrasound images to be saved of shape (n_frames, grid_size_z, grid_size_x).

  • image_sc (np.ndarray) – The scan converted ultrasound images to be saved of shape (n_frames, output_size_z, output_size_x).

  • probe_geometry (np.ndarray) – The probe geometry of shape (n_el, 3).

  • sampling_frequency (float) – The sampling frequency in Hz.

  • center_frequency (float) – The center frequency of the transmit pulse in Hz.

  • demodulation_frequency (float) – The demodulation frequency in Hz.

  • initial_times (list) – The times when the A/D converter starts sampling in seconds of shape (n_tx,). This is the time between the first element firing and the first recorded sample.

  • t0_delays (np.ndarray) – The t0_delays of shape (n_tx, n_el).

  • sound_speed (float) – The speed of sound in m/s.

  • probe_name (str) – The name of the probe.

  • description (str) – The description of the dataset.

  • focus_distances (np.ndarray) – The focus distances of shape (n_tx,).

  • transmit_origins (np.ndarray) – The transmit origins of shape (n_tx, 3).

  • polar_angles (np.ndarray) – The polar angles (radians) of shape (n_tx,).

  • azimuth_angles (np.ndarray) – The azimuth angles (radians) of shape (n_tx,).

  • tx_apodizations (np.ndarray) – The transmit delays for each element defining the wavefront in seconds of shape (n_tx, n_elem). This is the time between the first element firing and the last element firing.

  • bandwidth_percent (float) – The bandwidth of the transducer as a percentage of the center frequency.

  • time_to_next_transmit (np.ndarray) – The time between subsequent transmit events in s of shape (n_frames, n_tx).

  • tgc_gain_curve (np.ndarray) – The TGC gain that was applied to every sample in the raw_data of shape (n_ax).

  • element_width (float) – The width of the elements in the probe in meters of shape (n_tx,).

  • tx_waveform_indices (np.ndarray) – Transmit indices for waveforms, indexing waveforms_one_way and waveforms_two_way. This indicates which transmit waveform was used for each transmit event.

  • waveforms_one_way (list) – List of one-way waveforms as simulated by the Verasonics system, sampled at 250MHz. This is the waveform after being filtered by the transducer bandwidth once. Every element in the list is a 1D numpy array.

  • waveforms_two_way (list) – List of two-way waveforms as simulated by the Verasonics system, sampled at 250MHz. This is the waveform after being filtered by the transducer bandwidth twice. Every element in the list is a 1D numpy array.

  • additional_elements (List[DatasetElement]) – A list of additional dataset elements to be added to the dataset. Each element should be a DatasetElement object. The additional elements are added under the scan group.

  • cast_to_float (bool) – Whether to store data as float32. You may want to set this to False if storing images.

  • overwrite (bool) – Whether to overwrite the file if it already exists. Defaults to False.

  • enable_compression (bool) – Whether to enable gzip compression for datasets. Defaults to True. Compression reduces disk space at the cost of increased write time.

zea.data.data_format.load_additional_elements(path)[source]

Loads additional dataset elements from a zea dataset.

Parameters:

path (str) – The path to the zea dataset.

Returns:

A list of DatasetElement objects.

Return type:

list

zea.data.data_format.load_description(path)[source]

Loads the description of a zea dataset.

Parameters:

path (str) – The path to the zea dataset.

Returns:

The description of the dataset, or an empty string if not found.

Return type:

str

zea.data.data_format.validate_input_data(raw_data, aligned_data, envelope_data, beamformed_data, image, image_sc)[source]

Validates input data for generate_zea_dataset

Parameters:

  • raw_data (np.ndarray) – The raw data of the ultrasound measurement of shape (n_frames, n_tx, n_ax, n_el, n_ch).

  • aligned_data (np.ndarray) – The aligned data of the ultrasound measurement of shape (n_frames, n_tx, n_ax, n_el, n_ch).

  • envelope_data (np.ndarray) – The envelope data of the ultrasound measurement of shape (n_frames, grid_size_z, grid_size_x). Must be an ndarray.

  • beamformed_data (np.ndarray) – The beamformed data of the ultrasound measurement of shape (n_frames, grid_size_z, grid_size_x). Must be an ndarray.

  • image (np.ndarray) – The image data of shape (n_frames, grid_size_z, grid_size_x). Must be an ndarray.

  • image_sc (np.ndarray) – The scan converted images of shape (n_frames, output_size_z, output_size_x). Must be an ndarray.