load_hdf5

Contents

load_hdf5#

ptyrad.load.load_hdf5(file_path, key=None, delimiter='.')[source]#

Load dataset(s) from an HDF5 file, recursively if groups are encountered.

Parameters:

  • file_path (str) – Path to the HDF5 file.

  • key (str | list[str] | None) – Name(s) of the dataset(s) to load. - If None, ‘’, or []: Load all datasets recursively, preserving the original nested structure. - If str: Load a single dataset or group. Supports hierarchical keys (e.g., ‘group1.dataset1’). - If list[str]: Load multiple datasets. The returned dictionary will have a flattened structure with the hierarchical key strings as keys.

  • delimiter (str) – Delimiter for hierarchical keys (default: “.”).

Returns:

The loaded dataset(s).

  • If key is a string, returns a single np.ndarray or a nested dictionary if the key points to a group.

  • If key is a list of strings, returns a dictionary with the hierarchical key strings as keys and the corresponding datasets as values.

  • If key is None, returns a nested dictionary preserving the original structure of the HDF5 file.

Return type:

data (np.ndarray or dict)

Raises:

  • FileNotFoundError – If the specified file does not exist.

  • KeyError – If provided key(s) are not found in the file.

  • TypeError – If the key is not None, a string, or a list of strings.

Notes

  • Hierarchical Keys:

    • The function supports hierarchical keys (e.g., ‘group1.dataset1’) to directly access nested datasets or groups.

    • When a list of hierarchical keys is provided, the returned dictionary will have a flattened structure with the hierarchical key strings as keys.

  • Preserving Original Structure:

    • If key=None, the function recursively loads all datasets and groups, preserving the original nested structure of the HDF5 file.

  • Performance Considerations:

    • Providing an exact key (e.g., key=”group1/dataset1”) is significantly faster than recursively loading the entire file or traversing the hierarchy.

Contents