zea.data.file_operations¶

This module provides some utilities to edit zea data files, either individually or in bulk.

Each operation is available both as a Python function and as a command line subcommand. See the CLI documentation for the available operations and their command-line usage.

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, parameters[, 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, or a folder of files.
output_path (Path) – Path to the output file (or folder) 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.

Parameters:

input_path (Path) – Path to the input raw data file, or a folder of files.
output_path (Path) – Path to the output file (or folder) 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, or a folder of files.
output_path (Path) – Path to the output file (or folder) 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, enable_compression=True, chunk_frames=False)[source]¶

Resaves a zea data file to a new location.

Parameters:

input_path (Path) – Path to the input zea data file, or a folder of files.
output_path (Path) – Path to the output file (or folder) where the data will be saved.
overwrite (bool, optional) – Whether to overwrite the output file if it exists. Defaults to False.
enable_compression (bool, optional) – Whether to enable lzf compression for the datasets. Defaults to True.
chunk_frames (bool, optional) – Whether to store the data datasets with HDF5 chunked storage, using one frame per chunk. Defaults to False.

zea.data.file_operations.save_file(path, parameters, raw_data=None, aligned_data=None, beamformed_data=None, envelope_data=None, image=None, description=None, custom_maps=None, metadata=None, compression='lzf', chunk_frames=False, **kwargs)[source]¶

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

Parameters:

path (str, pathlike) – The path to the hdf5 file.
parameters (Parameters) – The parameters object containing acquisition and probe parameters.
raw_data (ndarray) – The data to save.
aligned_data (dict) – Aligned data as a dict with "values" and "extent" keys (validated as AlignedData).
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 (dict) – Reconstructed (log-compressed) image data as a dict with "values" and "extent" keys (validated as Image).
description (str, optional) – A description for the dataset.
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 "coordinates" (np.ndarray, float32, shape (n_frames, ..., 3)) fields, plus optional "description" and "unit" fields. Example:
```
custom_maps = {
    "my_overlay": {
        "values": values_array,      # (n_frames, z, x[, n_ch]), uint8
        "coordinates": coords_array, # (n_frames, z, x, 3), 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"])},
}
```
compression (str) – The HDF5 compression filter to use. Defaults to "lzf".
chunk_frames (bool, optional) – Whether to store the data datasets with HDF5 chunked storage, using one frame per chunk. Defaults to False.

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. Each path may be a single file or a folder; folders are expanded into all zea files they contain (using zea.Dataset).
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.