zea.data.data_format

Functions to write and validate datasets in the zea format.

Functions

generate_example_dataset(path[, ...])

Generates an example dataset that contains all the necessary fields.

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

Generates a dataset in the zea format.

validate_input_data(raw_data, aligned_data, ...)

Validates input data for generate_zea_dataset

Classes

DatasetElement(group_name, dataset_name, ...)

Class to store a dataset element with a name, data, description and unit.
class zea.data.data_format.DatasetElement(group_name, dataset_name, data, description, unit)[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_example_dataset(path, add_optional_fields=False, add_optional_dtypes=False, n_frames=2, n_ax=2048, n_el=128, n_tx=11, n_ch=1, sound_speed=1540, center_frequency=7000000.0, sampling_frequency=40000000.0, grid_size_z=512, grid_size_x=512)[source]

Generates an example dataset that contains all the necessary fields. Note: This dataset does not contain actual data, but is filled with random values.

Parameters:

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

  • add_optional_fields (bool, optional) – Whether to add optional fields to the dataset. Defaults to False.

  • add_optional_dtypes (bool, optional) – Whether to add optional dtypes to the dataset. Defaults to False.

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, initial_times=None, t0_delays=None, sound_speed=None, probe_name=None, description='No description was supplied', focus_distances=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, event_structure=False, cast_to_float=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 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, n_el).

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

  • 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 tranducer 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 tranducer 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.

  • event_structure (bool) – Whether to write the dataset with an event structure. In that case all data should be lists with the same length (number of events). The data will be stored under event_i/data and event_i/scan for each event i. Instead of just a single data and scan group.

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

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).

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

  • 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).