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

Bases: AbstractContextManager

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

The basic requirements needed to create a Workspace are:

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


Makes this workspace the active one.

In case the workspace gets deleted, safely returns None.

static active() Workspace[source]

Get the active workspace.

add_or_update_property_group(property_group: PropertyGroup, remove: bool = False)[source]

Add or update a property group to the workspace.

property attribute_map: dict

Mapping between names used in the geoh5 database.


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

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

  • 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)[source]

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

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


The Entity registered to the workspace.

classmethod create(path: str | Path, **kwargs) Workspace[source]

Create a named blank workspace and save to disk.

create_data(entity_class, entity_kwargs: dict, entity_type_kwargs: dict | DataType) Data | None[source]

Create a new Data entity with attributes.

  • entity_classData class.

  • entity_kwargs – Properties of the entity.

  • entity_type_kwargs – Properties of the entity_type.


The newly created entity.

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

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

  • 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_object_or_group(entity_class, entity_kwargs: dict, entity_type_kwargs: dict) Group | ObjectBase | None[source]

Create an object or a group with attributes.

  • entity_classObjectBase or Group class.

  • entity_kwargs – Attributes of the entity.

  • entity_type_kwargs – Attributes of the entity_type.


A new Object or Group.

property data: list[Data]

Get all active Data entities registered in the workspace.


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[source]

Fetch attribute stored as structured array from the source geoh5.

  • entity – Unique identifier of target entity.

  • key – Field array name


Structured array.

fetch_children(entity: Entity | PropertyGroup | None, recursively: bool = False) list[source]

Recover and register children entities from the geoh5.

  • 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[source]

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[source]

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[source]

Fetch data under the ConcatenatedData Data group of an entity.

  • entity – Concatenator group.

  • label – Name of the target data.


Index array and data values for the target label.

fetch_file_object(uid: UUID, file_name: str) bytes | None[source]

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[source]

Fetch the metadata of an entity from the source geoh5.

  • uid – Entity uid containing the metadata.

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


Dictionary of values.

fetch_property_groups(entity: Entity) list[PropertyGroup][source]

Fetch all property_groups on an object from the source geoh5


entity – Target object


List of PropertyGroups

fetch_type(uid: UUID, entity_type: str) dict[source]

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[source]

Fetch the data values from the source geoh5.


entity – Entity with ‘values’.


Array of values.

finalize() None[source]

Deprecate method finalize.

find_data(data_uid: UUID) Entity | None[source]

Find an existing and active Data entity.

find_entity(entity_uid: UUID) Entity | PropertyGroup | None[source]

Get all active entities registered in the workspace.

find_group(group_uid: UUID) Group | None[source]

Find an existing and active Group object.

find_object(object_uid: UUID) ObjectBase | None[source]

Find an existing and active Object.

find_property_group(property_group_uid: UUID) PropertyGroup | None[source]

Find an existing and active PropertyGroup object.

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

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][source]

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

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[source]

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[source]

Open a geoh5 file and load the tree structure.


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



property property_groups: list[PropertyGroup]

Get all active PropertyGroup entities registered in the workspace.

register(entity: Entity | EntityType | PropertyGroup)[source]

Register an entity to the workspace based on its type.


entity – The entity to be registered.

remove_children(parent, children: list)[source]

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

remove_entity(entity: Entity | PropertyGroup)[source]

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

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

Search and remove deleted entities

remove_recursively(entity: Entity | PropertyGroup)[source]

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[source]
save_as(filepath: str | Path) Workspace[source]

Save the workspace to disk.

save_entity(entity: Entity, add_children: bool = True, compression: int = 5) None[source]

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[source]

Save or update an entity_type to geoh5.


entity_type – Entity to be written to geoh5.

static str_from_type(entity) str | None[source]
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[source]

Save or update an entity to geoh5.

  • 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)[source]