geoh5py.workspace

geoh5py.workspace.workspace

class geoh5py.workspace.workspace.Workspace(h5file: str | Path | io.BytesIO = 'Analyst.geoh5', mode='a', **kwargs)

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

geoh5 – File name of the target geoh5 file. A new project is created if the target file cannot by found on disk.

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.

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, propery_groups: list[PropertyGroup], data_map: dict)

copy_to_parent(entity, parent, copy_children: bool = True, omit_list: tuple = ())

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.

• copy_children – Copy all children of the entity.

• omit_list – List of property names to omit on copy

Returns

The Entity registered to the workspace.

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, **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

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

• file – h5py.File or name of the target geoh5 file

• key – Field array name

Returns

Structured array.

fetch_children(entity: Entity | 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.

• file – h5py.File or name of the target geoh5 file.

Return list

List of children entities.

fetch_concatenated_attributes(entity: Group | ObjectBase) → dict | None

Fetch attributes of ConcatenatedData entities.

Parameters

entity – Concatenator group.

Returns

Dictionary of attributes.

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

Fetch list of data or indices of ConcatenatedData entities.

Parameters

• entity – Concatenator group.

• label – Label name of the h5py.Group

Returns

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.UUID, file_name: str) → bytes | None

Fetch an image from file name.

Parameters

uid – Unique identifier of target data object.

Returns

Array of values.

fetch_metadata(uid: uuid.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) → np.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

Parameters

file – h5py.File or name of the target geoh5 file

find_data(data_uid: uuid.UUID) → Entity | None

Find an existing and active Data entity.

find_entity(entity_uid: uuid.UUID) → Entity | None

Get all active entities registered in the workspace.

find_group(group_uid: uuid.UUID) → group.Group | None

Find an existing and active Group object.

find_object(object_uid: uuid.UUID) → object_base.ObjectBase | None

Find an existing and active Object.

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

Find an existing and active EntityType

Parameters

type_uid – Unique identifier of target type

property ga_version: str

str Version of Geoscience Analyst software.

property geoh5: File

Instance of h5py.File.

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

Retrieve an entity from one of its identifier, either by name or uuid.UUID.

Parameters

name – Object identifier, either name or uuid.

Returns

List of entities with the same given name.

property groups: list[groups.Group]

Get all active Group entities registered in the workspace.

property h5file: str | Path | io.BytesIO

Str

Target geoh5 file name with path.

property list_data_name: dict[uuid.UUID, str]

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

property list_entities_name: dict[uuid.UUID, str]

Returns

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

property list_groups_name: dict[uuid.UUID, str]

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

property list_objects_name: dict[uuid.UUID, str]

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

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

Recover an entity from geoh5.

Parameters

• uid – Unique identifier of entity

• entity_type – One of entity type ‘group’, ‘object’, ‘data’ or ‘root’

Return entity

Entity loaded from geoh5

property name: str

str Name of the project.

property objects: list[objects.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

remove_children(parent, children: list)

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

remove_entity(entity: Entity)

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

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

Search and remove deleted entities

remove_recursively(entity: Entity)

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 | None

RootGroup entity.

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

Save or update an entity to geoh5.

Parameters

• entity – Entity to be written to geoh5.

• add_children – Add children entities to geoh5.

• file – h5py.File or name of the target geoh5

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, **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)