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.

slice_spec_dims(spec, **dim_indices)

Index a spec along named SCHEMA dimensions, wherever they occur.

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 (str | Path) – Path to the input raw data file, or a folder of files. Also accepts an hf:// path (file or folder).

  • output_path (str | 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 (str | Path) – Path to the input raw data file, or a folder of files. Also accepts an hf:// path (file or folder).

  • output_path (str | 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 (str | Path) – Source path. Can be a single file, a list of files, a folder, or an hf:// path.

  • dst (str | 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, **kwargs)[source]

extracts frames and transmits in a raw data file.

Every field carrying an n_frames or n_tx dimension is sliced, as determined by the spec schema (see slice_spec_dims()), so scan parameters, annotations and metrics stay in sync with the extracted data.

Parameters:

  • input_path (str | Path) – Path to the input raw data file, or a folder of files. Also accepts an hf:// path (file or folder).

  • output_path (str | 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.

  • **kwargs – Passed to zea.data.spec.FileSpec.save() (e.g. compression, chunk_axes).

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, **kwargs)[source]

Resaves a zea data file to a new location.

Parameters:

  • input_path (str | Path) – Path to the input zea data file, or a folder of files. Also accepts an hf:// path (file or folder).

  • output_path (str | 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.

  • chunk_axes (tuple, optional) – Dimension names to chunk with size 1. Defaults to ("n_frames",) — one full frame per chunk — so partial and streamed reads fetch only the requested frames; other axes stay at full extent. Use None/() for contiguous storage. See zea.data.spec.Spec._resolve_chunks().

zea.data.file_operations.slice_spec_dims(spec, **dim_indices)[source]

Index a spec along named SCHEMA dimensions, wherever they occur.

Every field whose SCHEMA shape mentions one of the given dimension names is indexed along that dimension, throughout the whole spec tree. So slicing n_frames also selects the matching entries of timestamps, annotations and metrics, and slicing n_tx also selects the matching t0_delays, tx_apodizations and time_to_next_transmit — without this function needing to know those fields exist.

Fields that do not carry the dimension are passed through untouched, and arrays are shared with spec rather than copied where possible.

Note

custom elements are opaque to the schema and are never sliced.

Parameters:

  • spec (TypeVar(SpecT, bound= Spec)) – The spec to slice. Not modified.

  • **dim_indices – Index per named dimension, e.g. n_frames=[0, 2], n_tx=slice(0, 4). Values may be ints, lists, arrays, boolean masks or slices, and unlike a single fancy-index expression, several dimensions may be given as lists at the same time.

Returns:

A validated copy of spec with the requested dimensions indexed.

Return type:

TypeVar(SpecT, bound= Spec)

Example

sliced = slice_spec_dims(file_spec, n_frames=[0, 2], n_tx=slice(0, 4))
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 (Sequence[str | Path]) – List of paths to the input raw data files. Each path may be a single file, a folder, or an hf:// path; folders (local or hf://) are expanded into all zea files they contain (using zea.Dataset).

  • output_path (str | 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 (str | Path) – Path to the zea data file. Also accepts an hf:// path.