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 zea data 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.

copy(src, dst, key[, mode])

Copies zea files to a new location using zea.Dataset.copy().

extract_frames_transmits(input_path, output_path)

extracts frames and transmits in a raw data file.

main()

Parse command line arguments and run the requested data operation.

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.

summary(input_path)

Prints a summary of a zea data file to the console.
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.copy(src, dst, key, mode=None)[source]

Copies zea files to a new location using zea.Dataset.copy().

Parameters:

  • src (Path) – Source path. Can be a single file, a list of files, or a folder.

  • dst (Path) – Destination folder path.

  • key (str) – Key to access in the HDF5 files. Use "all" or "*" to copy everything.

  • mode (str | None) – HDF5 file mode for the destination files. Defaults to None, which lets zea.Dataset.copy() auto-select the mode ("a" for a single key, "w" when key is "all"/"*").

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.main()[source]

Parse command line arguments and run the requested data operation.

Entry point for python -m zea.data. This is equivalent to zea data.

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, custom_elements=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 | None) – The data to save.

  • aligned_data (dict | None) – Aligned data as a dict with "values" and "extent" keys (validated as AlignedData).

  • beamformed_data (dict | None) – Beamformed data as a dict with "values" and "extent" keys (validated as BeamformedData).

  • envelope_data (dict | None) – Envelope-detected data as a dict with "values" and "extent" keys (validated as EnvelopeData).

  • image (dict | None) – 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
    }
}

  • custom_elements (list | None) – List of CustomElement objects holding data that does not fit the zea format. Stored in a custom group and read back via zea.File.custom.

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

zea.data.file_operations.summary(input_path)[source]

Prints a summary of a zea data file to the console.

Parameters:

input_path (Path) – Path to the zea data file.