geoh5py.workspace

geoh5py.workspace.workspace

class geoh5py.workspace.workspace.Workspace(h5file: str | Path | BytesIO | None = None, contributors: tuple[str] = ('docs',), distance_unit: str = 'meter', ga_version: str = '1', mode='r+', name: str = 'GEOSCIENCE', repack: bool = False, version: float = 2.1)

Bases: AbstractContextManager

The Workspace class manages all Entities created or imported from the geoh5 structure.

The basic requirements needed to create a Workspace are:

Parameters:

• h5file – Path to the geoh5 file or oi.BytesIO representation of a geoh5 structure.

• contributors – List of contributors to the project.

• distance_unit – Distance unit used in the project.

• ga_version – Version of the geoh5 file format.

• mode – Mode in which the geoh5 file is opened.

• name – Name of the project.

• repack – Repack the geoh5 file after closing.

• version – Version of the project.

activate()

Makes this workspace the active one.

In case the workspace gets deleted, Workspace.active() safely returns None.

static active() → Workspace

Get the active workspace.

add_or_update_property_group(property_group: PropertyGroup, remove: bool = False)

Add or update a property group to the workspace.

property attribute_map: dict

Mapping between names used in the geoh5 database.

close()

Close the file and clear properties for future open.

property contributors: ndarray

numpy.array of str List of contributors name.

classmethod copy_property_groups(entity: ObjectBase, property_groups: list[PropertyGroup], data_map: dict)

Copy property groups to a new entity. Keep the same uid if it’s not present on the new workspace.

Parameters:

• entity – The entity associated to the property groups.

• property_groups – The property groups to copy.

• data_map – the data map to use for the property groups.

copy_to_parent(entity, parent, omit_list: tuple = (), clear_cache: bool = False, **kwargs)

Copy an entity to a different parent with copies of children.

Parameters:

• entity – Entity to be copied.

• parent – Target parent to copy the entity under.

• omit_list – List of property names to omit on copy

• clear_cache – Clear array attributes after copy.

• kwargs – Additional keyword arguments passed to the copy constructor.

Returns:

The Entity registered to the workspace.

classmethod create(path: str | Path, **kwargs) → Workspace

Create a named blank workspace and save to disk.

create_data(entity_class, entity_kwargs: dict, entity_type_kwargs: dict | DataType) → Data | None

Create a new Data entity with attributes.

Parameters:

• entity_class – Data class.

• entity_kwargs – Properties of the entity.

• entity_type_kwargs – Properties of the entity_type.

Returns:

The newly created entity.

create_entity(entity_class, save_on_creation: bool = True, compression: int = 5, **kwargs) → Entity | None

Function to create and register a new entity and its entity_type.

Parameters:

• entity_class – Type of entity to be created

• save_on_creation – Save the entity to geoh5 immediately

• compression – Compression level for data.

Return entity:

Newly created entity registered to the workspace

create_from_concatenation(attributes)

create_object_or_group(entity_class, entity_kwargs: dict, entity_type_kwargs: dict) → Group | ObjectBase | None

Create an object or a group with attributes.

Parameters:

• entity_class – ObjectBase or Group class.

• entity_kwargs – Attributes of the entity.

• entity_type_kwargs – Attributes of the entity_type.

Returns:

A new Object or Group.

property data: list[Data]

Get all active Data entities registered in the workspace.

deactivate()

Deactivate this workspace if it was the active one, else does nothing.

property distance_unit: str

str Distance unit used in the project.

fetch_array_attribute(entity: Entity, key: str = 'cells') → ndarray

Fetch attribute stored as structured array from the source geoh5.

Parameters:

• entity – Unique identifier of target entity.

• key – Field array name

Returns:

Structured array.

fetch_children(entity: Entity | PropertyGroup | None, recursively: bool = False) → list

Recover and register children entities from the geoh5.

Parameters:

• entity – Parental entity.

• recursively – Recover all children down the project tree.

Return list:

List of children entities.

fetch_concatenated_attributes(entity: Concatenator | ConcatenatedObject) → dict | None

Fetch attributes of Concatenated entity. :param entity: Concatenator group or ConcatenateObject. :return: Dictionary of attributes.

fetch_concatenated_list(entity: Group | ObjectBase, label: str) → list | None

Fetch list of data or indices of ConcatenatedData entities. :param entity: Concatenator group. :param label: Label name of the h5py.Group. :return: List of concatenated Data names.

fetch_concatenated_values(entity: Group | ObjectBase, label: str) → tuple | None

Fetch data under the ConcatenatedData Data group of an entity.

Parameters:

• entity – Concatenator group.

• label – Name of the target data.

Returns:

Index array and data values for the target label.

fetch_file_object(uid: UUID, file_name: str) → bytes | None

Fetch an image from file name. :param uid: Unique identifier of target data object. :param file_name: Name of the file to fetch. :return: Array of values.

fetch_metadata(uid: UUID, argument='Metadata') → dict | None

Fetch the metadata of an entity from the source geoh5.

Parameters:

• uid – Entity uid containing the metadata.

• argument – Optional argument for other json-like attributes.

Returns:

Dictionary of values.

fetch_or_create_root()

fetch_property_groups(entity: Entity) → list[PropertyGroup]

Fetch all property_groups on an object from the source geoh5

Parameters:

entity – Target object

Returns:

List of PropertyGroups

fetch_type(uid: UUID, entity_type: str) → dict

Fetch attributes of a specific entity type. :param uid: Unique identifier of the entity type. :param entity_type: One of ‘Data’, ‘Object’ or ‘Group’

fetch_values(entity: Entity) → ndarray | str | float | None

Fetch the data values from the source geoh5.

Parameters:

entity – Entity with ‘values’.

Returns:

Array of values.

finalize() → None

Deprecate method finalize.

find_data(data_uid: UUID) → Entity | None

Find an existing and active Data entity.

find_entity(entity_uid: UUID) → Entity | PropertyGroup | None

Get all active entities registered in the workspace.

find_group(group_uid: UUID) → Group | None

Find an existing and active Group object.

find_object(object_uid: UUID) → ObjectBase | None

Find an existing and active Object.

find_property_group(property_group_uid: UUID) → PropertyGroup | None

Find an existing and active PropertyGroup object.

find_type(type_uid: UUID, type_class: type[EntityType]) → EntityType | None

Find an existing and active EntityType. :param type_uid: Unique identifier of target type. :param type_class: The type of entity to find.

property ga_version: str

str Version of Geoscience Analyst software.

property geoh5: File

Instance of h5py.File.

get_entity(name: str | UUID) → list[Entity | PropertyGroup | None]

Retrieve an entity from one of its identifier, either by name or uuid.UUID. :param name: Object identifier, either name or uuid. :return: List of entities with the same given name.

property groups: list[Group]

Get all active Group entities registered in the workspace.

property h5file: str | Path | BytesIO | None

Target geoh5 file name with path or BytesIO object representation.

On geoh5py.workspace.Workspace.save(), the BytesIO representation gets replaced by a Path to a file on disk.

property list_data_name: dict[UUID, str]

dict of uuid.UUID keys and name values for all registered Data.

property list_entities_name: dict[UUID, str]

Returns:

dict of uuid.UUID keys and name values for all registered Entities.

property list_groups_name: dict[UUID, str]

dict of uuid.UUID keys and name values for all registered Groups.

property list_objects_name: dict[UUID, str]

dict of uuid.UUID keys and name values for all registered Objects.

property list_property_groups_name: dict[UUID, str]

dict of uuid.UUID keys and name values for all registered Groups.

load_entity(uid: UUID, entity_type: str, parent: Entity | None = None) → Entity | PropertyGroup | None

Recover an entity from geoh5. :param uid: Unique identifier of entity :param entity_type: One of entity type ‘group’, ‘object’, ‘data’ or ‘root’ :param parent: Parent entity. :return entity: Entity loaded from geoh5

property name: str

str Name of the project.

property objects: list[ObjectBase]

Get all active Object entities registered in the workspace.

open(mode: str | None = None) → Workspace

Open a geoh5 file and load the tree structure.

Parameters:

mode – Optional mode of h5py.File. Defaults to ‘r+’.

Returns:

self

property property_groups: list[PropertyGroup]

Get all active PropertyGroup entities registered in the workspace.

register(entity: Entity | EntityType | PropertyGroup)

Register an entity to the workspace based on its type.

Parameters:

entity – The entity to be registered.

remove_children(parent, children: list)

Remove a list of entities from a parent. The target entities remain present on file.

remove_entity(entity: Entity | PropertyGroup)

Function to remove an entity and its children from the workspace.

remove_none_referents(referents: dict[UUID, ReferenceType], rtype: str)

Search and remove deleted entities

remove_recursively(entity: Entity | PropertyGroup)

Delete an entity and its children from the workspace and geoh5 recursively

property repack: bool

Flag to repack the file after data deletion.

property root: Entity | PropertyGroup | None

RootGroup entity.

save(filepath: str | Path) → Workspace

save_as(filepath: str | Path) → Workspace

Save the workspace to disk.

save_entity(entity: Entity, add_children: bool = True, compression: int = 5) → None

Save or update an entity to geoh5. :param entity: Entity to be written to geoh5. :param add_children: Add children entities to geoh5. :param compression: Compression level for data.

save_entity_type(entity_type: EntityType) → None

Save or update an entity_type to geoh5.

Parameters:

entity_type – Entity to be written to geoh5.

static str_from_type(entity) → str | None

property types: list[EntityType]

Get all active entity types registered in the workspace.

update_attribute(entity: Entity | EntityType, attribute: str, channel: str | None = None, **kwargs) → None

Save or update an entity to geoh5.

Parameters:

• entity – Entity to be written to geoh5.

• attribute – Name of the attribute to get updated to geoh5.

• channel – Optional channel argument for concatenated data and index.

property version: float

float Version of the geoh5 file format.

property workspace: Workspace

This workspace instance itself.

geoh5py.workspace.workspace.active_workspace(workspace: Workspace)