geoh5py.shared

geoh5py.shared.concatenation

class geoh5py.shared.concatenation.Concatenated(entity_type, **kwargs)

Bases: Entity

Base class modifier for concatenated objects and data.

property concat_attr_str: str

String identifier for the concatenated attributes.

property concatenator: Concatenator

Parental Concatenator entity.

class geoh5py.shared.concatenation.ConcatenatedData(entity_type, **kwargs)

Bases: Concatenated

property n_values: ndarray

Number of values in the data.

property parent: ConcatenatedObject

property property_group

Get the property group containing the data interval.

class geoh5py.shared.concatenation.ConcatenatedDrillhole(entity_type, **kwargs)

Bases: ConcatenatedObject

property depth_: list[Data]

property from_: list[Data]

Depth data corresponding to the tops of the interval values.

sort_depths()

Bypass sort_depths from previous version.

property to_: list[Data]

Depth data corresponding to the bottoms of the interval values.

validate_data(attributes: dict, property_group=None, collocation_distance=None) → tuple

Validate input drillhole data attributes.

Parameters:

• attributes – Dictionary of data attributes.

• property_group – Input property group to validate against.

validate_depth_data(name: str | None, depth: list | ndarray | None, values: ndarray, property_group: str | ConcatenatedPropertyGroup | None = None, collocation_distance: float | None = None) → ConcatenatedPropertyGroup

Parameters:

• name – Data name.

• depth – Sampling depths.

• values – Data samples to depths.

• property_group – Group for possibly collocated data.

• collocation_distance – Tolerance to determine collocated data for property group assignment

Returns:

Augmented property group with name/values added for collocated data otherwise newly created property group with name/depth/values added.

validate_interval_data(name: str | None, from_to: list | ndarray | None, values: ndarray, property_group: str | ConcatenatedPropertyGroup | None = None, collocation_distance=0.0001) → ConcatenatedPropertyGroup

Compare new and current depth values and re-use the property group if possible. Otherwise a new property group is added.

Parameters:

• from_to – Array of from-to values.

• values – Data values to be added on the from-to intervals.

• property_group – Property group name

Collocation_distance:

Threshold on the comparison between existing depth values.

class geoh5py.shared.concatenation.ConcatenatedObject(entity_type, **kwargs)

Bases: Concatenated, ObjectBase

create_property_group(name=None, on_file=False, **kwargs) → ConcatenatedPropertyGroup

Create a new PropertyGroup.

Parameters:

kwargs – Any arguments taken by the PropertyGroup class.

Returns:

A new PropertyGroup

get_data(name: str | UUID) → list[Data]

Generic function to get data values from object.

get_data_list(attribute='name')

Get list of data names.

property parent: Concatenator

property property_groups: list | None

List of PropertyGroup.

class geoh5py.shared.concatenation.ConcatenatedPropertyGroup(parent: ConcatenatedObject, **kwargs)

Bases: PropertyGroup

property depth_

property from_

Return the data entities defined the ‘from’ depth intervals.

property parent

The parent ObjectBase

property to_

Return the data entities defined the ‘to’ depth intervals.

class geoh5py.shared.concatenation.Concatenator(group_type: GroupType, **kwargs)

Bases: Group

Class modifier for concatenation of objects and data.

add_children(children: list[ConcatenatedObject] | list[Entity]) → None

Parameters:

children – Add a list of entities as children

add_save_concatenated(child) → None

Add or save a concatenated entity.

Parameters:

child – Concatenated entity

property attributes_keys: list | None

List of uuids present in the concatenated attributes.

property concat_attr_str: str

String identifier for the concatenated attributes.

property concatenated_attributes: dict | None

Dictionary of concatenated objects and data attributes.

property concatenated_object_ids: list[bytes] | None

Dictionary of concatenated objects and data concatenated_object_ids.

copy(parent=None, copy_children: bool = True, clear_cache: bool = False, mask: ndarray | None = None, **kwargs)

Function to copy an entity to a different parent entity.

Parameters:

• parent – Target parent to copy the entity under. Copied to current parent if None.

• copy_children – Create copies of all children entities along with it.

• mask – Array of indices to sub-sample the input entity.

• clear_cache – Clear array attributes after copy.

Return entity:

Registered Entity to the workspace.

property data: dict

Concatenated data values stored as a dictionary.

delete_index_data(label: str, index: int) → None

fetch_concatenated_data_index()

Extract concatenation arrays.

fetch_concatenated_objects() → dict

Load all concatenated children.

fetch_index(entity: Concatenated, field: str) → int | None

Fetch the array index for specific concatenated object and data field.

Parameters:

• entity – Parent entity with data

• field – Name of the target data.

fetch_start_index(entity: Concatenated, label: str) → int

Fetch starting index for a given entity and label. Existing date is removed such that new entries can be appended.

Parameters:

• entity – Concatenated entity to be added.

• label – Name of the attribute requiring an update.

fetch_values(entity: Concatenated, field: str) → ndarray | None

Get an array of values from concatenated data.

Parameters:

• entity – Parent entity with data

• field – Name of the target data.

get_concatenated_attributes(uid: bytes | str | UUID) → dict

Fast reference index to concatenated attribute keys.

property index: dict

Concatenated index stored as a dictionary.

property property_group_ids: list | None

Dictionary of concatenated objects and data property_group_ids.

remove_entity(entity: Concatenated)

Remove a concatenated entity.

save_attribute(field: str)

Save a concatenated attribute.

Parameters:

field – Name of the attribute

update_array_attribute(entity: Concatenated, field: str, remove=False) → None

Update values stored as data. Row data and indices are first remove then appended.

Parameters:

• entity – Concatenated entity with array values.

• field – Name of the valued field.

update_attributes(entity: Concatenated, label: str) → None

Update a concatenated entity.

update_concatenated_attributes(entity: Concatenated) → None

Update the concatenated attributes. :param entity: Concatenated entity with attributes.

geoh5py.shared.entity

class geoh5py.shared.entity.Entity(uid: UUID | None = None, name='Entity', **kwargs)

Bases: ABC

Base Entity class

add_children(children: list[shared.Entity])

Parameters:

children – Add a list of entities as children

add_file(file: str)

Add a file to the object or group stored as bytes on a FilenameData

Parameters:

file – File name with path to import.

property allow_delete: bool

bool Entity can be deleted from the workspace.

property allow_move: bool

bool Entity can change parent

property allow_rename: bool

bool Entity can change name

property attribute_map: dict

dict Correspondence map between property names used in geoh5py and geoh5.

property children

list Children entities in the workspace tree

property clipping_ids: list[UUID] | None

List of clipping uuids

property coordinate_reference_system: dict

Coordinate reference system attached to the entity.

abstract copy(parent=None, copy_children: bool = True, clear_cache: bool = False, mask: ndarray | None = None, **kwargs)

Function to copy an entity to a different parent entity.

Parameters:

• parent – Target parent to copy the entity under. Copied to current parent if None.

• copy_children – (Optional) Create copies of all children entities along with it.

• clear_cache – Clear array attributes after copy to minimize the memory footprint of the workspace.

• mask – Array of indices to sub-sample the input entity.

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

Return entity:

Registered Entity to the workspace.

copy_from_extent(extent: ndarray, parent=None, copy_children: bool = True, clear_cache: bool = False, inverse: bool = False, **kwargs) → Entity | None

Function to copy an entity to a different parent entity.

Parameters:

• extent – Bounding box extent requested for the input entity, as supplied for mask_by_extent().

• parent – Target parent to copy the entity under. Copied to current parent if None.

• copy_children – (Optional) Create copies of all children entities along with it.

• clear_cache – Clear array attributes after copy.

• inverse – Keep the inverse (clip) of the extent selection.

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

Return entity:

Registered Entity to the workspace.

classmethod create(workspace, **kwargs)

Function to create an entity.

Parameters:

• workspace – Workspace to be added to.

• kwargs – List of keyword arguments defining the properties of a class.

Return entity:

Registered Entity to the workspace.

abstract property entity_type: shared.EntityType

classmethod fix_up_name(name: str) → str

If the given name is not a valid one, transforms it to make it valid :return: a valid name built from the given name. It simply returns the given name if it was already valid.

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

Get a child Data by name.

Parameters:

• name – Name of the target child data

• entity_type – Sub-select entities based on type.

Returns:

A list of children Data objects

get_entity_list(entity_type=<class 'abc.ABC'>) → list[str]

Get a list of names of all children Data.

Parameters:

entity_type – Option to sub-select based on type.

Returns:

List of names of data associated with the object.

abstract mask_by_extent(extent: ndarray, inverse: bool = False) → ndarray | None

Get a mask array from coordinate extent.

Parameters:

• extent – Bounding box extent coordinates defined by either: - obj:numpy.ndarray of shape (2, 3) 3D coordinate: [[west, south, bottom], [east, north, top]] - obj:numpy.ndarray of shape (2, 2) Horizontal coordinates: [[west, south], [east, north]].

• inverse – Return the complement of the mask extent. Default to False

Returns:

Array of bool defining the vertices or cell centers within the mask extent, or None if no intersection.

property metadata: dict | None

Metadata attached to the entity.

property name: str

str Name of the entity

property on_file: bool

Whether this Entity is already stored on h5file.

property parent

property partially_hidden: bool

Whether this Entity is partially hidden.

property public: bool

Whether this Entity is accessible in the workspace tree and other parts

of the the user interface in ANALYST.

reference_to_uid(value: Entity | PropertyGroup | str | uuid.UUID) → list[uuid.UUID]

General entity reference translation.

Parameters:

value – Either an Entity, string or uuid

Returns:

List of unique identifier associated with the input reference.

remove_children(children: list[shared.Entity] | list[PropertyGroup])

Remove children from the list of children entities.

Parameters:

children – List of entities

Warning

Removing a child entity without re-assigning it to a different parent may cause it to become inactive. Inactive entities are removed from the workspace by remove_none_referents().

save(add_children: bool = True)

Alias method of save_entity(). WILL BE DEPRECATED AS ENTITIES ARE ALWAYS AUTOMATICALLY UPDATED. :param add_children: Option to also save the children.

property uid: UUID

property visible: bool

Whether the Entity is visible in camera (checked in ANALYST object tree).

property workspace: Workspace

Workspace to which the Entity belongs to.

geoh5py.shared.entity_type

class geoh5py.shared.entity_type.EntityType(workspace: ws.Workspace, uid: uuid.UUID | None = None, **kwargs)

Bases: ABC

property attribute_map

dict Correspondence map between property names used in geoh5py and geoh5.

property description: str | None

classmethod find(workspace: ws.Workspace, type_uid: uuid.UUID) → EntityTypeT | None

Finds in the given Workspace the EntityType with the given UUID for this specific EntityType implementation class.

Returns:

EntityType of None

property name: str | None

property on_file: bool

bool Entity already present in h5file.

property uid: UUID

uuid.UUID The unique identifier of an entity, either as stored in geoh5 or generated in uuid4() format.

property workspace: ws.Workspace

Workspace registering this type.

geoh5py.shared.exceptions

exception geoh5py.shared.exceptions.AssociationValidationError(name: str, value: Entity | PropertyGroup | UUID, validation: Entity | Workspace)

Bases: BaseValidationError

Error on association between child and parent entity validation.

static message(name, value, validation)

Builds custom error message.

exception geoh5py.shared.exceptions.AtLeastOneValidationError(name: str, value: list[str])

Bases: BaseValidationError

static message(name, value, validation=None)

Builds custom error message.

exception geoh5py.shared.exceptions.BaseValidationError

Bases: ABC, Exception

Base class for custom exceptions.

abstract static message(name, value, validation)

Builds custom error message.

exception geoh5py.shared.exceptions.Geoh5FileClosedError

Bases: ABC, Exception

Error for closed geoh5 file.

exception geoh5py.shared.exceptions.JSONParameterValidationError(name: str, err: str)

Bases: Exception

Error on uuid validation.

static message(name, err)

exception geoh5py.shared.exceptions.OptionalValidationError(name: str, value: Any | None, validation: bool)

Bases: BaseValidationError

Error if None value provided to non-optional parameter.

static message(name, value, validation)

Builds custom error message.

exception geoh5py.shared.exceptions.PropertyGroupValidationError(name: str, value: PropertyGroup, validation: str)

Bases: BaseValidationError

Error on property group validation.

static message(name, value, validation)

Builds custom error message.

exception geoh5py.shared.exceptions.RequiredValidationError(name: str)

Bases: BaseValidationError

static message(name, value=None, validation=None)

Builds custom error message.

exception geoh5py.shared.exceptions.ShapeValidationError(name: str, value: tuple[int], validation: tuple[int] | str)

Bases: BaseValidationError

Error on shape validation.

static message(name, value, validation)

Builds custom error message.

exception geoh5py.shared.exceptions.TypeValidationError(name: str, value: str, validation: str | list[str])

Bases: BaseValidationError

Error on type validation.

static message(name, value, validation)

Builds custom error message.

exception geoh5py.shared.exceptions.UUIDValidationError(name: str, value: str)

Bases: BaseValidationError

Error on uuid string validation.

static message(name, value, validation=None)

Builds custom error message.

exception geoh5py.shared.exceptions.ValueValidationError(name: str, value: Any, validation: list[Any])

Bases: BaseValidationError

Error on value validation.

static message(name, value, validation)

Builds custom error message.

geoh5py.shared.utils

geoh5py.shared.utils.as_str_if_utf8_bytes(value) → str

Convert bytes to string

geoh5py.shared.utils.as_str_if_uuid(value: UUID | Any) → str | Any

Convert UUID to string used in geoh5.

geoh5py.shared.utils.bool_value(value: int8) → bool

Convert logical int8 to bool.

geoh5py.shared.utils.box_intersect(extent_a: ndarray, extent_b: ndarray) → bool

Compute the intersection of two axis-aligned bounding extents defined by their arrays of minimum and maximum bounds in N-D space.

Parameters:

• extent_a – First extent or shape (2, N)

• extent_b – Second extent or shape (2, N)

Returns:

Logic if the box extents intersect along all dimensions.

geoh5py.shared.utils.clear_array_attributes(entity: Entity, recursive: bool = False)

Clear all stashed values of attributes from an entity to free up memory.

Parameters:

• entity – Entity to clear attributes from.

• recursive – Clear attributes from children entities.

geoh5py.shared.utils.compare_entities(object_a, object_b, ignore: list | None = None, decimal: int = 6) → None

geoh5py.shared.utils.dict_mapper(val, string_funcs: list[Callable], *args, omit: dict | None = None)

Recursion through nested dictionaries and applies mapping functions to values.

Parameters:

• val – Value (could be another dictionary) to apply transform functions.

• string_funcs – Functions to apply on values within the input dictionary.

• omit – Dictionary of functions to omit.

Return val:

Transformed values

geoh5py.shared.utils.dip_points(points: ndarray, dip: float, rotation: float = 0) → ndarray

Rotate points about the x-axis by the dip angle and then about the z-axis by the rotation angle. :param points: an array of points to rotate :param dip: the dip angle in radians :param rotation: the rotation angle in radians :return: the rotated points

geoh5py.shared.utils.entity2uuid(value: Any) → UUID | Any

Convert an entity to its UUID.

geoh5py.shared.utils.fetch_active_workspace(workspace: Workspace | None, mode: str = 'r')

Open a workspace in the requested ‘mode’.

If receiving an opened Workspace instead, merely return the given workspace.

Parameters:

• workspace – A Workspace class

• mode – Set the h5 read/write mode

Return h5py.File:

Handle to an opened Workspace.

geoh5py.shared.utils.fetch_h5_handle(file: str | File | Path, mode: str = 'r') → File

Open in read+ mode a geoh5 file from string. If receiving a file instead of a string, merely return the given file.

Parameters:

• file – Name or handle to a geoh5 file.

• mode – Set the h5 read/write mode

Return h5py.File:

Handle to an opened h5py file.

geoh5py.shared.utils.get_attributes(entity, omit_list=(), attributes=None)

Extract the attributes of an object with omissions.

geoh5py.shared.utils.is_uuid(value: str) → bool

Check if a string is UUID compliant.

geoh5py.shared.utils.iterable(value: Any, checklen: bool = False) → bool

Checks if object is iterable.

Parameters:

valueObject to check for iterableness.

checklenRestrict objects with __iter__ method to len > 1.

Returns:

True if object has __iter__ attribute but is not string or dict type.

geoh5py.shared.utils.iterable_message(valid: list[Any] | None) → str

Append possibly iterable valid: “Must be (one of): {valid}.”.

geoh5py.shared.utils.mask_by_extent(locations: ndarray, extent: ndarray, inverse: bool = False) → ndarray

Find indices of locations within a rectangular extent.

Parameters:

• locations – shape(, 3) or shape(, 2) Coordinates to be evaluated.

• extent – shape(2, 2) Limits defined by the South-West and North-East corners. Extents can also be provided as 3D coordinates with shape(2, 3) defining the top and bottom limits.

• inverse – Return the complement of the mask extent.

Returns:

Array of bool for the locations inside or outside the box extent.

geoh5py.shared.utils.match_values(vec_a, vec_b, collocation_distance=0.0001) → ndarray

Find indices of matching values between two arrays, within collocation_distance.

Param:

vec_a, list or numpy.ndarray Input sorted values

Param:

vec_b, list or numpy.ndarray Query values

Returns:

indices, numpy.ndarray Pairs of indices for matching values between the two arrays such that vec_a[ind[:, 0]] == vec_b[ind[:, 1]].

geoh5py.shared.utils.merge_arrays(head, tail, replace='A->B', mapping=None, collocation_distance=0.0001, return_mapping=False) → ndarray

Given two numpy.arrays of different length, find the matching values and append both arrays.

Param:

head, numpy.array of float First vector of shape(M,) to be appended.

Param:

tail, numpy.array of float Second vector of shape(N,) to be appended

Param:

mapping=None, numpy.ndarray of int Optional array where values from the head are replaced by the tail.

Param:

collocation_distance=1e-4, float Tolerance between matching values.

Returns:

numpy.array shape(O,) Unique values from head to tail without repeats, within collocation_distance.

geoh5py.shared.utils.str2uuid(value: Any) → UUID | Any

Convert string to UUID

geoh5py.shared.utils.uuid2entity(value: UUID, workspace: Workspace) → Entity | Any

Convert UUID to a known entity.

geoh5py.shared.utils.xy_rotation_matrix(angle: float) → ndarray

Rotation matrix about the z-axis.

Parameters:

angle – Rotation angle in radians.

Return rot:

Rotation matrix.

geoh5py.shared.utils.yz_rotation_matrix(angle: float) → ndarray

Rotation matrix about the x-axis. :param angle: Rotation angle in radians. :return: rot: Rotation matrix.

geoh5py.shared.validators

class geoh5py.shared.validators.AssociationValidator(**kwargs)

Bases: BaseValidator

Validate the association between data and parent object.

classmethod validate(name: str, value: Entity | PropertyGroup | UUID | None, valid: Entity | Workspace) → None

Parameters:

• name – Parameter identifier.

• value – Input parameter value.

• valid – Expected value shape

validator_type = 'association'

class geoh5py.shared.validators.AtLeastOneValidator(**kwargs)

Bases: BaseValidator

classmethod validate(name, value, valid)

Custom validation function.

validator_type = 'one_of'

class geoh5py.shared.validators.BaseValidator(**kwargs)

Bases: ABC

Concrete base class for validators.

abstract classmethod validate(name: str, value: Any, valid: Any)

Custom validation function.

abstract property validator_type: str

Validation type identifier.

class geoh5py.shared.validators.OptionalValidator(**kwargs)

Bases: BaseValidator

Validate that forms contain optional parameter if None value is given.

classmethod validate(name: str, value: Any | None, valid: bool) → None

Parameters:

• name – Parameter identifier.

• value – Input parameter value.

• valid – True if optional keyword in form for parameter.

validator_type = 'optional'

class geoh5py.shared.validators.PropertyGroupValidator(**kwargs)

Bases: BaseValidator

Validate property_group from parent entity.

classmethod validate(name: str, value: PropertyGroup, valid: str) → None

Custom validation function.

validator_type = 'property_group_type'

class geoh5py.shared.validators.RequiredValidator(**kwargs)

Bases: BaseValidator

Validate that required keys are present in parameter.

classmethod validate(name: str, value: Any, valid: bool) → None

Parameters:

• name – Parameter identifier.

• value – Input parameter value.

• valid – Assert to be required

validator_type = 'required'

class geoh5py.shared.validators.ShapeValidator(**kwargs)

Bases: BaseValidator

Validate the shape of provided value.

classmethod validate(name: str, value: Any, valid: tuple[int]) → None

Parameters:

• name – Parameter identifier.

• value – Input parameter value.

• valid – Expected value shape

validator_type = 'shape'

class geoh5py.shared.validators.TypeValidator(**kwargs)

Bases: BaseValidator

Validate the value type from a list of valid types.

classmethod validate(name: str, value: Any, valid: type | list[type]) → None

Parameters:

• name – Parameter identifier.

• value – Input parameter value.

• valid – List of accepted value types

validator_type = 'types'

class geoh5py.shared.validators.UUIDValidator(**kwargs)

Bases: BaseValidator

Validate a uuui.UUID value or uuid string.

classmethod validate(name: str, value: Any, valid: None = None) → None

Parameters:

• name – Parameter identifier.

• value – Input parameter uuid.

• valid – [Optional] Validate uuid from parental entity or known uuids

validator_type = 'uuid'

class geoh5py.shared.validators.ValueValidator(**kwargs)

Bases: BaseValidator

Validator that ensures that values are valid entries.

classmethod validate(name: str, value: Any, valid: list[float | str]) → None

Parameters:

• name – Parameter identifier.

• value – Input parameter value.

• valid – List of accepted values

validator_type = 'values'

geoh5py.shared.weakref_utils

geoh5py.shared.weakref_utils.get_clean_ref(some_dict: dict[K, ReferenceType[T]], key: K) → T | None

Gets the referent value for the given key in a some_dict of weakref values. In case key points to a reference to a deleted value, remove that key from some_dict on the fly, and returns None.

Parameters:

• some_dict – The dictionary of weakref values.

• key – The key

Returns:

the referent value for key if found in the the dictionary, else None.

geoh5py.shared.weakref_utils.insert_once(some_dict: dict[K, ReferenceType], key: K, value)

Check if the reference to an Entity with uuid is already in use.

Parameters:

• some_dict – Dictionary of UUID keys and weakref values.

• key – UUID key to be checked.

• value – Entity to be checked

Returns:

Dictionary with clean weakref

geoh5py.shared.weakref_utils.remove_none_referents(some_dict: dict[K, ReferenceType])

Removes any key from the given some_dict where the value is a reference to a deleted value (that is where referent of the weakref value is None).

Parameters:

some_dict – The dictionary to be cleaned up.