zea.data.convert.matlab¶

Functionality to convert Verasonics matlab raw files to the zea format.

Example (MATLAB):

>> setup_script;
>> VSX;
>> save_raw('C:/path/to/raw_data.mat');

Then in python:

from zea.data_format.zea_from_matlab_raw import zea_from_matlab_raw

zea_from_matlab_raw("C:/path/to/raw_data.mat", "C:/path/to/output.hdf5")

Or alternatively, use the script below to convert all .mat files in a directory:

python zea/data/convert/matlab.py "C:/path/to/directory"

or without the directory argument, the script will prompt you to select a directory using a file dialog.

Event structure¶

By default the zea dataformat saves all the data to an hdf5 file with the following structure:

regular_zea_dataset.hdf5
├── data
└── scan
      └── center_frequency: 1MHz

The data is stored in the data group and the scan parameters are stored in the scan. However, when we do an adaptive acquisition, some scanning parameters might change. These blocks of data with consistent scanning parameters we call events. In the case we have multiple events, we store the data in the following structure:

zea_dataset.hdf5
├── event_0
│   ├── data
│   └── scan
│       └── center_frequency: 1MHz
├── event_1
│   ├── data
│   └── scan
│       └── center_frequency: 2MHz
├── event_2
│   ├── data
│   └── scan
└── event_3
    ├── data
    └── scan

This structure is supported by the zea toolbox. The way we can save the data in this structure from the Verasonics, is by changing the setup script to keep track of the TX struct at each event.

The way this is done is still in development, an example of such an acquisition script that is compatible with saving event structures is found here: setup_agent.m

Adding additional elements¶

You can add additional elements to the dataset by defining a function that reads the data from the file and returns a DatasetElement. Then pass the function to the zea_from_matlab_raw function as a list.

def read_max_high_voltage(file):
    lens_correction = file["Trans"]["lensCorrection"][0, 0].item()
    return lens_correction


def read_high_voltage_func(file):
    return DatasetElement(
        group_name="scan",
        dataset_name="max_high_voltage",
        data=read_max_high_voltage(file),
        description="The maximum high voltage used by the Verasonics system.",
        unit="V",
    )


zea_from_matlab_raw(
    "C:/path/to/raw_data.mat",
    "C:/path/to/output.hdf5",
    [read_high_voltage_func],
)

Functions

`decode_string`(dataset)	Decode a string dataset.
`dereference_index`(file, dataset, index[, ...])	Get the element at the given index from the dataset, dereferencing it if necessary.
`get_answer`(prompt[, additional_options])	Get a yes or no answer from the user.
`get_frame_indices`(file, frames)	Creates a numpy array of frame indices from the file and the frames argument.
`get_reference_size`(dataset)	Get the size of a reference dataset.
`parse_args`()	Parse command line arguments.
`planewave_focal_distance_to_inf`(...)	Detects plane wave transmits and sets the focus distance to infinity.
`read_azimuth_angles`(file, tx_order[, event])	Read the azimuth angles from the file.
`read_bandwidth_percent`(file)	Reads the bandwidth percent from the file.
`read_focus_distances`(file, tx_order[, event])	Reads the focus distances from the file.
`read_image_data_p`(file[, event, frames])	Reads the image data from the file.
`read_initial_times`(file, rcv_order, sound_speed)	Reads the initial times from the file.
`read_lens_correction`(file)	Reads the lens correction from the file.
`read_polar_angles`(file, tx_order[, event])	Read the polar angles from the file.
`read_probe_center_frequency`(file)	Reads the center frequency of the probe from the file.
`read_probe_element_width`(file)	Reads the element width from the file.
`read_probe_geometry`(file)	Read the probe geometry from the file.
`read_probe_name`(file)	Reads the name of the probe from the file.
`read_raw_data`(file[, event, frames])	Read the raw data from the file.
`read_sampling_frequency`(file)	Read the sampling frequency from the file.
`read_sound_speed`(file)	Reads the speed of sound from the file.
`read_t0_delays_apod`(file, tx_order[, event])	Read the t0 delays and apodization from the file.
`read_tgc_gain_curve`(file)	Reads the TGC gain curve from the file.
`read_transmit_events`(file[, event, frames])	Read the events from the file and finds the order in which transmits and receives appear in the events.
`read_verasonics_file`(file[, event, ...])	Reads data from a .mat Verasonics output file.
`read_waveforms`(file, tx_order[, event])	Read the waveforms from the file.
`read_wavelength`(file)	Reads the wavelength from the file.
`zea_from_matlab_raw`(input_path, output_path)	Converts a Verasonics matlab raw file to the zea format.

zea.data.convert.matlab.decode_string(dataset)[source]¶: Decode a string dataset.

zea.data.convert.matlab.dereference_index(file, dataset, index, event=None, subindex=None)[source]¶

Get the element at the given index from the dataset, dereferencing it if necessary.

MATLAB stores items in struct array differently depending on the size. If the size is 1, the item is stored as a regular dataset. If the size is larger, the item is stored as a dataset of references to the actual data.

This function dereferences the dataset if it is a reference. Otherwise, it returns the dataset.

Parameters:

file (h5py.File) – The file to read the dataset from.
dataset (h5py.Dataset) – The dataset to read the element from.
index (int) – The index of the element to read.
event (int, optional) – The event index. Usually we store each event in the second dimension of the dataset. Defaults to None in this case we assume that there is only a single event.
subindex (slice, optional) – The subindex of the element to read after referencing the actual data. Defaults to None. In this case, all the data is returned.

zea.data.convert.matlab.get_answer(prompt, additional_options=None)[source]¶

Get a yes or no answer from the user. There is also the option to provide additional options. In case yes or no is selected, the function returns a boolean. In case an additional option is selected, the function returns the selected option as a string.

Parameters:

prompt (str) – The prompt to show the user.
additional_options (list, optional) – Additional options to show the user. Defaults to None.

Returns:

The user’s answer.

Return type:

str

zea.data.convert.matlab.get_frame_indices(file, frames)[source]¶

Creates a numpy array of frame indices from the file and the frames argument.

Parameters:

file (h5py.File) – The file to read the frame indices from.
frames (str) – The frames argument. This can be “all” or a list of frame indices.

Returns:

The frame indices.

Return type:

frame_indices (np.ndarray)

zea.data.convert.matlab.get_reference_size(dataset)[source]¶: Get the size of a reference dataset.

zea.data.convert.matlab.parse_args()[source]¶: Parse command line arguments.

zea.data.convert.matlab.planewave_focal_distance_to_inf(focus_distances, t0_delays, tx_apodizations, probe_geometry)[source]¶

Detects plane wave transmits and sets the focus distance to infinity.

Parameters:

focus_distances (np.ndarray) – The focus distances of shape (n_tx,).
t0_delays (np.ndarray) – The t0 delays of shape (n_tx, n_el).
tx_apodizations (np.ndarray) – The apodization of shape (n_tx, n_el).

Returns:

The focus distances of shape (n_tx,).

Return type:

focus_distances (np.ndarray)

Note

This function assumes that the probe_geometry is a 1d uniform linear array. If not it will warn and return.

zea.data.convert.matlab.read_azimuth_angles(file, tx_order, event=None)[source]¶

Read the azimuth angles from the file.

Parameters:: file (h5py.File) – The file to read the azimuth angles from. (The file should be opened in read mode.)
Returns:: The azimuth angles of shape (n_tx,).
Return type:: azimuth_angles (np.ndarray)

zea.data.convert.matlab.read_bandwidth_percent(file)[source]¶

Reads the bandwidth percent from the file.

Parameters:: file (h5py.File) – The file to read the bandwidth percent from. (The file should be opened in read mode.)
Returns:: The bandwidth percent.
Return type:: bandwidth_percent (int)

zea.data.convert.matlab.read_focus_distances(file, tx_order, event=None)[source]¶

Reads the focus distances from the file.

Parameters:

file (h5py.File) – The file to read the focus distances from. (The file should be opened in read mode.)
tx_order (list) – The order in which the transmits appear in the events.

Returns:

The focus distances.

Return type:

focus_distances (list)

zea.data.convert.matlab.read_image_data_p(file, event=None, frames='all')[source]¶

Reads the image data from the file.

Parameters:: file (h5py.File) – The file to read the image data from. (The file should be opened in read mode.)
Returns:: The image data.
Return type:: image_data (np.ndarray)

zea.data.convert.matlab.read_initial_times(file, rcv_order, sound_speed)[source]¶

Reads the initial times from the file.

Parameters:

file (h5py.File) – The file to read the initial times from. (The file should be opened in read mode.)
rcv_order (list) – The order in which the receives appear in the events.
wavelength (float) – The wavelength of the probe.
sound_speed (float) – The speed of sound.

Returns:

The initial times of shape (n_rcv,).

Return type:

initial_times (np.ndarray)

zea.data.convert.matlab.read_lens_correction(file)[source]¶

Reads the lens correction from the file.

Parameters:: file (h5py.File) – The file to read the lens correction from. (The file should be opened in read mode.)
Returns:: The lens correction.
Return type:: lens_correction (np.ndarray)

zea.data.convert.matlab.read_polar_angles(file, tx_order, event=None)[source]¶

Read the polar angles from the file.

Parameters:: file (h5py.File) – The file to read the polar angles from. (The file should be opened in read mode.)
Returns:: The polar angles of shape (n_tx,).
Return type:: polar_angles (np.ndarray)

zea.data.convert.matlab.read_probe_center_frequency(file)[source]¶

Reads the center frequency of the probe from the file.

Parameters:: file (h5py.File) – The file to read the center frequency from. (The file should be opened in read mode.)
Returns:: The center frequency of the probe.
Return type:: center_frequency (float)

zea.data.convert.matlab.read_probe_element_width(file)[source]¶

Reads the element width from the file.

Parameters:: file (h5py.File) – The file to read the element width from. The file should be opened in read mode.
Returns:: The element width.
Return type:: float

zea.data.convert.matlab.read_probe_geometry(file)[source]¶

Read the probe geometry from the file.

Parameters:: file (h5py.File) – The file to read the probe geometry from. (The file should be opened in read mode.)
Returns:: The probe geometry of shape (n_el, 3).
Return type:: probe_geometry (np.ndarray)

zea.data.convert.matlab.read_probe_name(file)[source]¶

Reads the name of the probe from the file.

Parameters:: file (h5py.File) – The file to read the name of the probe from. (The file should be opened in read mode.)
Returns:: The name of the probe.
Return type:: probe_name (str)

zea.data.convert.matlab.read_raw_data(file, event=None, frames='all')[source]¶

Read the raw data from the file.

Parameters:: file (h5py.File) – The file to read the raw data from. (The file should be opened in read mode.)
Returns:: The raw data of shape (n_rcv, n_samples).
Return type:: raw_data (np.ndarray)

zea.data.convert.matlab.read_sampling_frequency(file)[source]¶

Read the sampling frequency from the file.

Parameters:: file (h5py.File) – The file to read the sampling frequency from. (The file should be opened in read mode.)
Returns:: The sampling frequency.
Return type:: sampling_frequency (float)

zea.data.convert.matlab.read_sound_speed(file)[source]¶

Reads the speed of sound from the file.

Parameters:: file (h5py.File) – The file to read the speed of sound from. (The file should be opened in read mode.)
Returns:: The speed of sound.
Return type:: sound_speed (float)

zea.data.convert.matlab.read_t0_delays_apod(file, tx_order, event=None)[source]¶

Read the t0 delays and apodization from the file.

Parameters:: file (h5py.File) – The file to read the t0 delays from. (The file should be opened in read mode.)
Returns:: The t0 delays of shape (n_tx, n_el). apod (np.ndarray): The apodization of shape (n_el,).
Return type:: t0_delays (np.ndarray)

zea.data.convert.matlab.read_tgc_gain_curve(file)[source]¶

Reads the TGC gain curve from the file.

Parameters:: file (h5py.File) – The file to read the TGC gain curve from. (The file should be opened in read mode.)
Returns:: The TGC gain curve of shape (n_ax,).
Return type:: np.ndarray

zea.data.convert.matlab.read_transmit_events(file, event=None, frames='all')[source]¶

Read the events from the file and finds the order in which transmits and receives appear in the events.

Parameters:

file (h5py.File) – The file to read the events from. The file should be opened in read mode.
event (int, optional) – The event index. Defaults to None.
frames (str or list, optional) – The frames to read. Defaults to “all”.

Returns:

(tx_order, rcv_order, time_to_next_acq): tx_order (list): The order in which the transmits appear in the events. rcv_order (list): The order in which the receives appear in the events. time_to_next_acq (np.ndarray): The time to next acquisition of shape (n_acq, n_tx).

Return type:

tuple

zea.data.convert.matlab.read_verasonics_file(file, event=None, additional_functions=None, frames='all')[source]¶

Reads data from a .mat Verasonics output file.

Parameters:

file (h5py.File) – The file to read the data from. (The file should be opened in read mode.)
event (int, optional) – The event index. Defaults to None in this case we assume the data file is stored without event structure.
additional_functions (list, optional) – A list of functions that read additional data from the file. Each function should take the file as input and return a DatasetElement. Defaults to None.

zea.data.convert.matlab.read_waveforms(file, tx_order, event=None)[source]¶

Read the waveforms from the file.

Parameters:: file (h5py.File) – The file to read the waveforms from. (The file should be opened in read mode.)
Returns:: The waveforms of shape (n_tx, n_samples).
Return type:: waveforms (np.ndarray)

zea.data.convert.matlab.read_wavelength(file)[source]¶

Reads the wavelength from the file.

Parameters:: file (h5py.File) – The file to read the wavelength from. (The file should be opened in read mode.)
Returns:: The wavelength of the probe.
Return type:: wavelength (float)

zea.data.convert.matlab.zea_from_matlab_raw(input_path, output_path, additional_functions=None, frames='all')[source]¶

Converts a Verasonics matlab raw file to the zea format. The MATLAB file should be created using the save_raw function and be stored in “v7.3” format.

Parameters:

input_path (str) – The path to the input file (.mat file).
output_path (str) – The path to the output file (.hdf5 file).
additional_functions (list, optional) – A list of functions that read additional data from the file. Each function should take the file as input and return a DatasetElement. Defaults to None.
frames (str or list of int, optional) – The frames to add to the file. This can be a list of integers, a range of integers (e.g. 4-8), or ‘all’. Defaults to ‘all’.