zea.data.file_operations¶

This module provides some utilities to edit zea data files.

Available operations¶

sum: Sum multiple raw data files into one.
compound_frames: Compound frames in a raw data file to increase SNR.
compound_transmits: Compound transmits in a raw data file to increase SNR.
resave: Resave a zea data file. This can be used to change the file format version.
extract: extract frames and transmits in a raw data file.

Functions

`compound_frames`(input_path, output_path[, ...])	Compounds frames in a raw data file by averaging them.
`compound_transmits`(input_path, output_path)	Compounds transmits in a raw data file by averaging them.
`extract_frames_transmits`(input_path, output_path)	extracts frames and transmits in a raw data file.
`get_parser`()	Command line argument parser with subcommands
`resave`(input_path, output_path[, overwrite])	Resaves a zea data file to a new location.
`save_file`(path, scan, probe[, raw_data, ...])	Saves data to a zea data file (h5py file).
`sum_data`(input_paths, output_path[, overwrite])	Sums multiple raw data files and saves the result to a new file.

zea.data.file_operations.compound_frames(input_path, output_path, overwrite=False)[source]¶

Compounds frames in a raw data file by averaging them.

Parameters:

input_path (Path) – Path to the input raw data file.
output_path (Path) – Path to the output file where the compounded data will be saved.
overwrite (bool, optional) – Whether to overwrite the output file if it exists. Defaults to False.

zea.data.file_operations.compound_transmits(input_path, output_path, overwrite=False)[source]¶

Compounds transmits in a raw data file by averaging them.

Note

This function assumes that all transmits are identical. If this is not the case the function will result in incorrect scan parameters.

Args:: input_path (Path): Path to the input raw data file. output_path (Path): Path to the output file where the compounded data will be saved. overwrite (bool, optional): Whether to overwrite the output file if it exists. Defaults to False.

zea.data.file_operations.extract_frames_transmits(input_path, output_path, frame_indices=slice(None, None, None), transmit_indices=slice(None, None, None), overwrite=False)[source]¶

extracts frames and transmits in a raw data file.

Note that the frame indices cannot both be lists. At least one of them must be a slice. Please refer to the documentation of zea.data.file.load_file_all_data_types() for more information on the supported index types.

Parameters:

input_path (Path) – Path to the input raw data file.
output_path (Path) – Path to the output file where the extracted data will be saved.
frame_indices (list, array-like, or slice) – Indices of the frames to keep.
transmit_indices (list, array-like, or slice) – Indices of the transmits to keep.
overwrite (bool, optional) – Whether to overwrite the output file if it exists. Defaults to False.

zea.data.file_operations.get_parser()[source]¶: Command line argument parser with subcommands

zea.data.file_operations.resave(input_path, output_path, overwrite=False)[source]¶

Resaves a zea data file to a new location.

Parameters:

input_path (Path) – Path to the input zea data file.
output_path (Path) – Path to the output file where the data will be saved.
overwrite (bool, optional) – Whether to overwrite the output file if it exists. Defaults to False.

zea.data.file_operations.save_file(path, scan, probe, raw_data=None, aligned_data=None, beamformed_data=None, envelope_data=None, image=None, image_sc=None, description='', custom_maps=None, metadata=None, **kwargs)[source]¶

Saves data to a zea data file (h5py file).

Parameters:

path (str, pathlike) – The path to the hdf5 file.
raw_data (ndarray) – The data to save.
scan (Scan) – The scan object containing the parameters of the acquisition.
probe (Probe) – The probe object containing the parameters of the probe.
description (str) – A description for the dataset.
beamformed_data (dict) – Beamformed data as a dict with "values" and "extent" keys (validated as BeamformedData).
envelope_data (dict) – Envelope-detected data as a dict with "values" and "extent" keys (validated as EnvelopeData).
image_sc (dict) – Scan-converted image data as a dict with "values" and "extent" keys (validated as ImageSc).
image (dict) – Reconstructed (log-compressed) image data as a dict with "values" and "extent" keys (validated as Image).
custom_maps (dict | None) –
Custom spatial map entries to include in the data group. Each key maps to a dict with "values" (np.ndarray, uint8) and "extent" (np.ndarray, float32, shape (6,)) fields, plus optional "labels", "description", and "unit" fields. Example:
```
custom_maps = {
    "my_overlay": {
        "values": values_array,  # (n_frames, x, z, y[, n_ch]), uint8
        "extent": extent_array,  # (6,) float32
    }
}
```
metadata (dict | None) –
Metadata to store in the metadata group, validated against MetadataSpec. Standard keys include "subject", "credit", "annotations", "text_report", "ecg", "probe_pose", and "voice_narration". Custom signal keys are also accepted and stored as SignalND entries. Example:
```
metadata = {
    "credit": "My Lab, 2024",
    "annotations": {"label": np.array(["healthy", "healthy"])},
}
```

zea.data.file_operations.sum_data(input_paths, output_path, overwrite=False)[source]¶

Sums multiple raw data files and saves the result to a new file.

For images, this will actually average the images. If the images are uint8, it will average directly. If the images are float32, we assume they are in the log-domain and we will do the averaging in the linear domain.

Parameters:

input_paths (list[Path]) – List of paths to the input raw data files.
output_path (Path) – Path to the output file where the summed data will be saved.
overwrite (bool, optional) – Whether to overwrite the output file if it exists. Defaults to False.