phenotypic.sdk_.HDF#

class phenotypic.sdk_.HDF(filepath, name: str, mode: Literal['single', 'set'])[source]#

Bases: object

Represents an interface to manage HDF5 files with support for single or set image modes, and ensures safe and compatible file access with retry and error-handling mechanisms.

The class facilitates operations on HDF5 files commonly used for storing phenotypic data in both single image and image set modes. This class includes utilities to handle locking errors and ensure compatibility by initializing proper HDF5 modes while providing safe access methods for writing.

Parameters:

name (str)
mode (Literal['single', 'set'])

filepath#

Path to the HDF5 file on the filesystem.

Type:: Path

name#

Name associated with the HDF5 resource, often used as an identifier.

Type:: str

mode#

Specifies the mode for the HDF5 file, either single image or image set.

Type:: Literal[‘single’, ‘set’]

root_posix#

The root path for the HDF5 resource, determined by the mode.

Type:: str

home_posix#

The specific root directory of the HDF5 resource in the file, derived based on its mode.

Type:: str

set_data_posix#

The subgroup path for the data entity in image set mode, if applicable.

Type:: str, optional

SINGLE_IMAGE_ROOT_POSIX#

Base path for single image mode.

Type:: str

IMAGE_SET_ROOT_POSIX#

Base path for image set mode.

Type:: str

IMAGE_SET_DATA_POSIX#

Subgroup marker for image set data.

Type:: str

EXT#

Set of valid file extensions used to recognize HDF5 files.

Type:: set

IMAGE_MEASUREMENT_SUBGROUP_KEY#

Key for accessing measurements in an image’s group.

Type:: str

IMAGE_STATUS_SUBGROUP_KEY#

Key for accessing statuses in an image’s group.

Type:: str

Methods

`__init__`	Initializes a class instance to manage HDF5 file structures for single or set image data based on the given filepath, name of the resource, and operational mode.
`get_data_group`
`get_group`	Retrieves or creates a group in an HDF5 file.
`get_home`	Retrieves a specific group from an HDF file corresponding to single image data.
`get_image_group`
`get_image_measurement_subgroup`
`get_protected_metadata_subgroup`
`get_public_metadata_subgroup`
`get_root_group`
`get_status_subgroup`
`reader`
`safe_writer`	Returns a writer object that provides safe and controlled write access to an HDF5 file at the specified filepath or creates it if it doesn't exist.
`save_array2hdf5`	Saves a given numpy array to an HDF5 group.
`strict_writer`	Provides access to an HDF5 file in read/write mode using the h5py library.
`swmr_reader`
`swmr_writer`	Returns a writer object that provides safe SWMR-compatible write access to an HDF5 file.

Attributes

`EXT`
`IMAGE_MEASUREMENT_SUBGROUP_KEY`
`IMAGE_SET_DATA_POSIX`
`IMAGE_SET_ROOT_POSIX`
`IMAGE_STATUS_SUBGROUP_KEY`
`PROTECTED_METADATA_SUBGROUP_KEY`
`PUBLIC_METADATA_SUBGROUP_KEY`
`SINGLE_IMAGE_ROOT_POSIX`

SINGLE_IMAGE_ROOT_POSIX = '/phenotypic/images/'#

IMAGE_SET_ROOT_POSIX = '/phenotypic/image_sets/'#

IMAGE_SET_DATA_POSIX = 'data'#

IMAGE_MEASUREMENT_SUBGROUP_KEY = 'measurements'#

IMAGE_STATUS_SUBGROUP_KEY = 'status'#

PROTECTED_METADATA_SUBGROUP_KEY = 'protected_metadata'#

PUBLIC_METADATA_SUBGROUP_KEY = 'public_metadata'#

EXT = {'.h5', '.hdf', '.hdf5', '.he5'}#

__init__(filepath, name: str, mode: Literal['single', 'set'])[source]#

Initializes a class instance to manage HDF5 file structures for single or set image data based on the given filepath, name of the resource, and operational mode.

filepath#

Path to the HDF5 file.

Type:: Path

name#

Identifier for the resource within the HDF5 file.

Type:: str

mode#

Operational mode determining the structure and organization within the HDF5 file. Must be either ‘single’ or ‘set’.

Type:: Literal[‘single’, ‘set’]

root_posix#

Posix path representing the root directory within the HDF5 file based on the mode.

Type:: str

home_posix#

Posix path representing the home directory for the resource within the HDF5 file based on the mode.

Type:: str

set_data_posix#

Posix path for the data subdirectory within the resource home directory. Only initialized in ‘set’ mode.

Type:: Optional[str]

Parameters:

filepath – Path to the target HDF5 file. Must have an HDF5-compatible extension, or a ValueError is raised.
name (str) – Name of the resource to be managed in the file. Used to construct the home directory for the resource within the HDF5 file.
mode (Literal['single', 'set']) – Operational mode. Specifies whether the resource represents a ‘single’ or ‘set’ image data. If the mode is invalid, a ValueError is raised.

Raises:

ValueError – If the filepath does not have an HDF5-compatible extension.
ValueError – If the mode is neither ‘single’ nor ‘set’.

safe_writer() → File[source]#

Returns a writer object that provides safe and controlled write access to an HDF5 file at the specified filepath or creates it if it doesn’t exist. Ensures that the file uses the ‘latest’ version of the HDF5 library for compatibility and performance.

Handles HDF5 file locking conflicts by attempting to clear consistency flags and retrying file opening with exponential backoff.

Returns:: A file writer object with append mode and ‘latest’ library version enabled.
Return type:: h5py.File
Raises:: OSError – If file cannot be opened after all retry attempts.

swmr_writer() → File[source]#

Returns a writer object that provides safe SWMR-compatible write access to an HDF5 file. Creates the file if it doesn’t exist and enables SWMR mode properly.

This method ensures proper SWMR mode initialization by creating the file with the correct settings from the start, avoiding cache conflicts that occur when trying to enable SWMR mode after opening.

Returns:: A file writer object with SWMR mode enabled.
Return type:: h5py.File
Raises:: OSError – If file cannot be opened after all retry attempts.

strict_writer() → File[source]#

Provides access to an HDF5 file in read/write mode using the h5py library. This property is used to obtain an h5py.File object configured with the latest library version.

Note

If using SWMR mode, don’t forget to enable SWMR mode:

>>> hdf = HDF(filepath)
>>> with hdf.writer as writer:
...     writer.swmr_mode = True
...     # rest of your code

Returns:: An HDF5 file object opened in ‘r+’ mode, enabling reading and writing.
Return type:: h5py.File
Raises:: OSError – If the file cannot be opened or accessed.

swmr_reader() → File[source]#

Return type:: File

reader() → File[source]#

Return type:: File

static get_group(handle: File, posix) → Group[source]#

Retrieves or creates a group in an HDF5 file.

This method checks the validity of the provided HDF5 file handle and tries to retrieve the specified group based on the given posix path. If the group does not exist and the file is not opened in read-only mode, the group gets created. If the file is in read-only mode and the group does not exist, an error is raised.

Parameters:

handle (h5py.File) – The HDF5 file handle to operate on.
posix (str) – The posix path of the group to retrieve or create in the HDF5 file.

Returns:

The corresponding h5py group within the HDF5 file.

Return type:

h5py.Group

Raises:

ValueError – If the HDF5 file handle is invalid or no longer valid.
ValueError – If the file handle mode cannot be determined.
KeyError – If the specified group does not exist in read-only mode.

get_home(handle)[source]#

Retrieves a specific group from an HDF file corresponding to single image data.

This method is used to fetch a predefined group from an HDF container, where the group is identified by a constant key related to single image data. The function provides a static interface allowing invocation without requiring an instance of the class.

Parameters:

handle – The HDF file handle from which the group should be retrieved.

Returns:

The group corresponding to single image data, retrieved based on the defined SINGLE_IMAGE_ROOT_POSIX.

Raises:

Appropriate exceptions may be raised by the underlying HDF.get_group() method, –
based on the implementation and provided handle or key. –

get_root_group(handle) → Group[source]#

Return type:: Group

get_data_group(handle)[source]#

get_image_group(handle, image_name)[source]#

get_image_measurement_subgroup(handle, image_name)[source]#

get_status_subgroup(handle, image_name)[source]#

get_protected_metadata_subgroup(handle: File, image_name: str) → Group[source]#

Parameters:

handle (File)
image_name (str)

Return type:

Group

get_public_metadata_subgroup(handle: File, image_name: str) → Group[source]#

Parameters:

handle (File)
image_name (str)

Return type:

Group

static save_array2hdf5(group, array, name, **kwargs)[source]#

Saves a given numpy array to an HDF5 group. If a dataset with the specified name already exists in the group, it checks if the shapes match. If the shapes match, it updates the existing dataset; otherwise, it removes the existing dataset and creates a new one with the specified name. If a dataset with the given name doesn’t exist, it creates a new dataset.

Parameters:

group – h5py.Group The HDF5 group in which the dataset will be saved.
array – numpy.ndarray The data array to be stored in the dataset.
name – str The name of the dataset within the group.
**kwargs – dict Additional keyword arguments to pass when creating a new dataset.

phenotypic.sdk_.HDF#

This Page