mapteksdk.geologycore.tables module

Module containing classes and enums for representing tables.

A table is a group of fields in a database which store related information. Common tables have their own subclass which provides additional information on the fields which are stored in tables of that type.

Note that each hole in a drillhole database has its own copy of each table defined in the database. Which tables and the fields contained within those tables are the same for all drillholes within the same database.

class DrillholeTableType(value)

Bases: Enum

Enumeration of supported table types.

COLLAR = 'Collar'

GEOLOGY = 'Geology'

ASSAY = 'Assay'

QUALITY = 'Quality'

DOWNHOLE = 'Downhole'

SURVEY = 'Survey'

OTHER = 'Other'

UNKNOWN = ''

must_be_unique()

True if a database can contain multiple tables of this type.

Return type: bool

class BaseTable(table_information)

Bases: object

Base class for tables containing shared functionality.

This is an abstract base class which should not be instantiated directly.

Parameters

name – The name of the table this object represents.
table_information (dict) –

property name: str

The table’s name.

This is a user-provided string. It may differ for equivalent tables in different databases.

property table_type: DrillholeTableType: The table’s type in the TableType enum.

property fields: list[BaseField]: A list of the fields in this table.

property field_count: int: The count of fields in the table.

property custom_fields: list[BaseField]

Returns a list of custom fields in this table.

Custom fields are all fields which do not correspond to a field type defined in the FieldType enum.

fields_by_type(field_type)

Returns a list of fields with the specified field type.

Parameters: field_type (DrillholeFieldType) – The type of field to return fields for.
Returns: List of fields with the specified field type.
Return type: list
Raises: KeyError – If field_type is not part of the DrillholeFieldType enum.

field_by_name(name)

Returns the field with the specified name.

Parameters: name (str) – The name of the field to get
Returns: The field with the specified name.
Return type: BaseField
Raises: FieldNotFoundError – If there is no field with the specified name.

class BaseTableInformation(table_information)

Bases: BaseTable

Base class for table information.

This represents the configuration of a table in a drillhole database. This cannot be used to access the values stored in the table, however it can be used to add new fields.

Any changes made to this object will be made to all drillholes in the drillhole database.

Parameters

name – The name of the table this object represents.
table_information (dict) –

property fields: list[FieldInformation]: A list of the fields in this table.

property custom_fields: list[FieldInformation]

Returns a list of custom fields in this table.

Custom fields are all fields which do not correspond to a field type defined in the FieldType enum.

fields_by_type(field_type)

Returns a list of fields with the specified field type.

Parameters: field_type (DrillholeFieldType) – The type of field to return fields for.
Returns: List of fields with the specified field type.
Return type: list
Raises: KeyError – If field_type is not part of the DrillholeFieldType enum.

field_by_name(name)

Returns the field with the specified name.

Parameters: name (str) – The name of the field to get
Returns: The field with the specified name.
Return type: BaseField
Raises: FieldNotFoundError – If there is no field with the specified name.

add_field(name, data_type, description, *, field_type=DrillholeFieldType.NONE, unit=None, index=None)

Add a new field to the table.

After the database is closed, this new field will be available in all drillholes in the drillhole database.

Parameters

name (str) – The name for the new field.
data_type (type) – The type of data stored in the field. This can be int, float, bool, str or a numpy dtype.
description (str) – Description for the field.
field_type (DrillholeFieldType) – A keyword only argument to specify the field type to give to the new field. This defaults to DrillholeFieldType.None.
unit (DistanceUnit | AngleUnit | NO_UNIT | None) – The unit of the data stored in the field. If None (default) the default unit for the field type will be used. This is meters for distance fields and radians for angle fields.
index (int | None) – A keyword only argument for specifying the index in the table to insert the new field at. By default the new field will be inserted at the end of the table.

Raises

TypeError – If field_name or description are not strings.
TypeError – If data_type is not a valid data type.
TypeError – If field_type is not part of the DrillholeFieldType enum.
ValueError – If index is not a number or if it is below zero or greater than the number of fields.
DuplicateFieldNameError – If there is already a field with the specified name.
FieldTypeNotSupportedError – If field_type is not supported by table.
DuplicateFieldTypeError – If there is already a field with the specified type in the table and that field type does not support duplicates.
DataTypeNotSupportedError – If data_type is not supported by field_type.
UnitNotSupportedUnitError – If unit is not supported by field_type.
FieldDoesNotSupportUnitsError – If unit is not None or NO_UNIT for a field which does not support units.

property field_count: int: The count of fields in the table.

property name: str

The table’s name.

This is a user-provided string. It may differ for equivalent tables in different databases.

property table_type: DrillholeTableType: The table’s type in the TableType enum.

class BaseDrillholeTable(table_information)

Bases: BaseTable

Base class representing a table in a Drillhole Database.

Each hole has its own copy of each table in the Database. Each table stores a group of related fields. Subclasses define convenience properties for accessing fields which are commonly part of this type of table.

Parameters

name (str) – The name of the table.
table_information (dict) –

Raises

TypeError – If name is not a string.

Warning

Users of the SDK should not create subclasses of this class. This class is only part of the public API to allow for type hinting.

HOLE_ID = 'HOLE_ID': The name of the hole ID column in pandas dataframes.

property table_type: DrillholeTableType: The table’s type in the TableType enum.

property fields: list[DrillholeDatabaseField]: A list of the fields in this table.

property custom_fields: list[DrillholeDatabaseField]

Returns a list of custom fields in this table.

Custom fields are all fields which do not correspond to a field type defined in the FieldType enum.

fields_by_type(field_type)

Returns a list of fields with the specified field type.

Parameters: field_type (DrillholeFieldType) – The type of field to return fields for.
Returns: List of fields with the specified field type.
Return type: list
Raises: KeyError – If field_type is not part of the DrillholeFieldType enum.

field_by_name(name)

Returns the field with the specified name.

Parameters: name (str) – The name of the field to get
Returns: The field with the specified name.
Return type: BaseField
Raises: FieldNotFoundError – If there is no field with the specified name.

property row_count: int: The number of rows in this table.

add_row(*, index=None)

Add a new row to the table.

Parameters

index (int | None) – The index to add the new row at. If None (default), add the new row at the end.

Raises

ValueError – If index is below zero or greater than the row count, or if index cannot be converted to an integer.
CollarTableRowError – If attempting to add a row to the collar table.

Warning

This invalidates the properties of the table, requiring them to be loaded from the database again.

add_rows(count=1, *, index=None)

Add multiple rows to the table.

This is more efficient than adding a single row to the table multiple times because the properties of the table are only invalidated once.

Parameters

count (int) – The number of new rows to add.
index (int | None) – The index of the first new row to add. If None (default), add the new rows at the end.

Raises

ValueError – If index is below zero or greater than the row count, or if index cannot be converted to an integer.
ValueError – If count is less than one or cannot be converted to an integer.
CollarTableRowError – If attempting to add rows to the collar table.

Warning

This invalidates the properties of the table, requiring them to be loaded from the database again.

remove_row(index)

Remove the specified row from the table.

Parameters

index (int) – Index of the row to remove.

Raises

ValueError – If index cannot be converted to an integer.
IndexError – If there is no row with the specified index.
CollarTableRowError – If attempting to remove a row from the collar table.

Warning

This invalidates the properties of the table, requiring them to be loaded from the database again.

remove_rows(index, count)

Remove count rows starting at index.

Parameters

index (int) – Index of the row to remove.
count (int) – The number of rows to remove.

Raises

ValueError – If index cannot be converted to an integer.
ValueError – If count cannot be converted to an integer.
IndexError – If one or more rows to delete do not exist.
CollarTableRowError – If attempting to remove rows from the collar table.

Warning

This invalidates the properties of the table, requiring them to be loaded from the database again.

dataframe(*, fields=None, include_hole_id=True, save_changes=False)

Context manager for a pandas dataframe representing this table.

Each field of the table becomes a column of the dataframe. The column name is the field name and the column contains the values of that field.

Parameters

fields (list[DrillholeDatabaseField] | None) – A list of fields to include in the dataframe. Only fields in the list will be included in the dataframe. If None (Default), the dataframe will include all fields in the table. Filtering out fields which will not be used will reduce the memory and time required to construct and perform operations on the dataframe.
include_hole_id (bool) – If True (Default) the hole id column will be included in the dataframe. This column will have the name BaseDrillholeTable.HOLE_ID and it will have a unique value for each drillhole in the underlying database. This allows for dataframes of the same table from different holes in the same database to be safely concatenated. If False, the hole id column will not be included.
save_changes (bool) – If False (default) any changes to the dataframe will not be propagated to the table. If True, and the object is open for reading, changes to the dataframe will be propagated to the table.

Yields

pd.DataFrame – Dataframe representing the table.

Raises

TypeError – If any item in fields is not a DrillholeDatabaseField.
ReadOnlyError – If save_changes is True when the object is open for reading.
TableMismatchError – If fields includes a field which is not part of this table.

Return type

Generator[pd.DataFrame, None, None]

Examples

Calculating the length of each interval in a table based on the to and from depth fields.

>>> from mapteksdk.project import Project
>>> from mapteksdk.geologycore import Drillhole
>>> project = Project()
>>> with project.read("path/to/drillhole") as drillhole:
...   drillhole: Drillhole
...   geology_table = drillhole.geology_table
...   to_depth_name = geology_table.to_depth.name
...   from_depth_name = geology_table.from_depth.name
...   with geology_table.dataframe() as frame:
...     # The dataframe is indexed via field name. Use the field name
...     # queried earlier.
...     length = frame[to_depth_name] - frame[from_depth_name]
...     print(length)

The above script only uses the to depth and from depth fields, however the dataframe includes all of the fields in the table. If the table has a large number of rows or fields, this can be very inefficient. The performance of the operation can be improved by filtering out the fields which are not needed as shown in the below version of the same script.

>>> from mapteksdk.project import Project
>>> from mapteksdk.geologycore import Drillhole
>>> project = Project()
>>> with project.read("path/to/drillhole") as drillhole:
...   drillhole: Drillhole
...   geology_table = drillhole.geology_table
...   to_depth = geology_table.to_depth
...   from_depth = geology_table.from_depth
...   with geology_table.dataframe(fields=(to_depth, from_depth)) as frame:
...     length = frame[to_depth.name] - frame[from_depth.name]
...     print(length)

property field_count: int: The count of fields in the table.

property name: str

The table’s name.

This is a user-provided string. It may differ for equivalent tables in different databases.

class CollarTable(table_information)

Bases: BaseDrillholeTable, _CollarTableMixin

Table containing information on the collar of the drillhole.

The collar is the point on the surface where the drillhole was taken.

Notes

The collar table should only have a single row in it and thus a single value for each field.

Parameters: table_information (dict) –

property table_type: The table’s type in the TableType enum.

property azimuth: DrillholeDatabaseField

Field representing the azimuth of the drillhole.

Raises

FieldNotFoundError – If there is no azimuth field.
TooManyFieldsError – If there are multiple azimuth fields in the table. This should not be possible. If this error is thrown, the database was invalid.

property dip: DrillholeDatabaseField

Field representing the dip angle of the drillhole.

Raises

FieldNotFoundError – If there is no dip field.
TooManyFieldsError – If there are multiple dip fields in the table. This should not be possible. If this error is thrown, the database was invalid.

property easting: DrillholeDatabaseField

Field representing the easting of a drillhole.

In a default project, this corresponds to the x coordinate of the drillhole. Changes to the easting field will be propogated to the collar point of the drillhole when save() is called.

Raises

FieldNotFoundError – If there is no easting field.
TooManyFieldsError – If there are multiple easting fields in the table. This should not be possible. If this error is thrown, the database was invalid.

property northing: DrillholeDatabaseField

Field representing the northing of a drillhole.

In a default project, this corresponds to the y coordinate of the drillhole. Changes to the northing field will be propogated to the collar point of the drillhole when save() is called.

Raises

FieldNotFoundError – If there is no easting field.
TooManyFieldsError – If there are multiple easting fields in the table. This should not be possible. If this error is thrown, the database was invalid.

property elevation: DrillholeDatabaseField

Field representing the elevation of a drillhole.

In a default project, this corresponds to the z coordinate of the drillhole. Changes to the elevation field will be propogated to the collar point of the drillhole when save() is called.

Raises

FieldNotFoundError – If there is no elevation field.
TooManyFieldsError – If there are multiple elevation fields in the table. This should not be possible. If this error is thrown, the database was invalid.

property total_depth: DrillholeDatabaseField

The total depth of the drillhole.

If any table has to_depth or from_depth fields, they should not contain values which exceed the total_depth of the drillhole.

Raises

FieldNotFoundError – If there is no total depth field.
TooManyFieldsError – If there are multiple total depth fields in the table. This should not be possible. If this error is thrown, the database was invalid.

property collar_point: ndarray

The collar point of the drillhole as specified by this table.

This property handles missing elevation values. This reads the x, y and z coordinate straight from the table and does not consider coordinate systems.

If the collar table does not contain an elevation field, the z component of the collar point will be zero.

Raises

TableNotFoundError – If there is no collar table.
TooManyTablesError – If there are multiple collar tables in the database.

Warns

RuntimeWarning – If the table contains no elevation field and the collar is set to a point containing a non-zero z ordinate.

add_rows(count=1, *, index=None)

Add multiple rows to the table.

This is more efficient than adding a single row to the table multiple times because the properties of the table are only invalidated once.

Parameters

count (int) – The number of new rows to add.
index (int | None) – The index of the first new row to add. If None (default), add the new rows at the end.

Raises

ValueError – If index is below zero or greater than the row count, or if index cannot be converted to an integer.
ValueError – If count is less than one or cannot be converted to an integer.
CollarTableRowError – If attempting to add rows to the collar table.

Warning

This invalidates the properties of the table, requiring them to be loaded from the database again.

remove_rows(index, count)

Remove count rows starting at index.

Parameters

index (int) – Index of the row to remove.
count (int) – The number of rows to remove.

Raises

ValueError – If index cannot be converted to an integer.
ValueError – If count cannot be converted to an integer.
IndexError – If one or more rows to delete do not exist.
CollarTableRowError – If attempting to remove rows from the collar table.

Warning

This invalidates the properties of the table, requiring them to be loaded from the database again.

HOLE_ID = 'HOLE_ID': The name of the hole ID column in pandas dataframes.

add_row(*, index=None)

Add a new row to the table.

Parameters

index (int | None) – The index to add the new row at. If None (default), add the new row at the end.

Raises

ValueError – If index is below zero or greater than the row count, or if index cannot be converted to an integer.
CollarTableRowError – If attempting to add a row to the collar table.

Warning

This invalidates the properties of the table, requiring them to be loaded from the database again.

property custom_fields: list[DrillholeDatabaseField]

Returns a list of custom fields in this table.

Custom fields are all fields which do not correspond to a field type defined in the FieldType enum.

dataframe(*, fields=None, include_hole_id=True, save_changes=False)

Context manager for a pandas dataframe representing this table.

Each field of the table becomes a column of the dataframe. The column name is the field name and the column contains the values of that field.

Parameters

fields (list[DrillholeDatabaseField] | None) – A list of fields to include in the dataframe. Only fields in the list will be included in the dataframe. If None (Default), the dataframe will include all fields in the table. Filtering out fields which will not be used will reduce the memory and time required to construct and perform operations on the dataframe.
include_hole_id (bool) – If True (Default) the hole id column will be included in the dataframe. This column will have the name BaseDrillholeTable.HOLE_ID and it will have a unique value for each drillhole in the underlying database. This allows for dataframes of the same table from different holes in the same database to be safely concatenated. If False, the hole id column will not be included.
save_changes (bool) – If False (default) any changes to the dataframe will not be propagated to the table. If True, and the object is open for reading, changes to the dataframe will be propagated to the table.

Yields

pd.DataFrame – Dataframe representing the table.

Raises

TypeError – If any item in fields is not a DrillholeDatabaseField.
ReadOnlyError – If save_changes is True when the object is open for reading.
TableMismatchError – If fields includes a field which is not part of this table.

Return type

Generator[pd.DataFrame, None, None]

Examples

Calculating the length of each interval in a table based on the to and from depth fields.

>>> from mapteksdk.project import Project
>>> from mapteksdk.geologycore import Drillhole
>>> project = Project()
>>> with project.read("path/to/drillhole") as drillhole:
...   drillhole: Drillhole
...   geology_table = drillhole.geology_table
...   to_depth_name = geology_table.to_depth.name
...   from_depth_name = geology_table.from_depth.name
...   with geology_table.dataframe() as frame:
...     # The dataframe is indexed via field name. Use the field name
...     # queried earlier.
...     length = frame[to_depth_name] - frame[from_depth_name]
...     print(length)

The above script only uses the to depth and from depth fields, however the dataframe includes all of the fields in the table. If the table has a large number of rows or fields, this can be very inefficient. The performance of the operation can be improved by filtering out the fields which are not needed as shown in the below version of the same script.

>>> from mapteksdk.project import Project
>>> from mapteksdk.geologycore import Drillhole
>>> project = Project()
>>> with project.read("path/to/drillhole") as drillhole:
...   drillhole: Drillhole
...   geology_table = drillhole.geology_table
...   to_depth = geology_table.to_depth
...   from_depth = geology_table.from_depth
...   with geology_table.dataframe(fields=(to_depth, from_depth)) as frame:
...     length = frame[to_depth.name] - frame[from_depth.name]
...     print(length)

field_by_name(name)

Returns the field with the specified name.

Parameters: name (str) – The name of the field to get
Returns: The field with the specified name.
Return type: BaseField
Raises: FieldNotFoundError – If there is no field with the specified name.

property field_count: int: The count of fields in the table.

property fields: list[DrillholeDatabaseField]: A list of the fields in this table.

fields_by_type(field_type)

Returns a list of fields with the specified field type.

Parameters: field_type (DrillholeFieldType) – The type of field to return fields for.
Returns: List of fields with the specified field type.
Return type: list
Raises: KeyError – If field_type is not part of the DrillholeFieldType enum.

property name: str

The table’s name.

This is a user-provided string. It may differ for equivalent tables in different databases.

remove_row(index)

Remove the specified row from the table.

Parameters

index (int) – Index of the row to remove.

Raises

ValueError – If index cannot be converted to an integer.
IndexError – If there is no row with the specified index.
CollarTableRowError – If attempting to remove a row from the collar table.

Warning

This invalidates the properties of the table, requiring them to be loaded from the database again.

property row_count: int: The number of rows in this table.

class SurveyTable(table_information)

Bases: BaseDrillholeTable, _SurveyTableMixin

Table containing survey information for a drillhole.

Changes to the depth and azimuth fields will be propogated to the points used to visualise the drillhole when save() is called.

Parameters: table_information (dict) –

property table_type: The table’s type in the TableType enum.

property azimuth: DrillholeDatabaseField

Field representing the azimuth of the drillhole.

Raises

FieldNotFoundError – If there is no azimuth field.
TooManyFieldsError – If there are multiple azimuth fields in the table. This should not be possible. If this error is thrown, the database was invalid.

property dip: DrillholeDatabaseField

Field representing the dip angle of the drillhole.

Raises

FieldNotFoundError – If there is no dip field.
TooManyFieldsError – If there are multiple dip fields in the table. This should not be possible. If this error is thrown, the database was invalid.

property depth: DrillholeDatabaseField

The depth values for the table.

This indicates the depth each azimuth and dip measurement were taken at.

Raises

FieldNotFoundError – If there is no depth field.
TooManyFieldsError – If there are multiple depth fields in the table. This should not be possible. If this error is thrown, the database was invalid.

HOLE_ID = 'HOLE_ID': The name of the hole ID column in pandas dataframes.

add_row(*, index=None)

Add a new row to the table.

Parameters

index (int | None) – The index to add the new row at. If None (default), add the new row at the end.

Raises

ValueError – If index is below zero or greater than the row count, or if index cannot be converted to an integer.
CollarTableRowError – If attempting to add a row to the collar table.

Warning

This invalidates the properties of the table, requiring them to be loaded from the database again.

add_rows(count=1, *, index=None)

Add multiple rows to the table.

This is more efficient than adding a single row to the table multiple times because the properties of the table are only invalidated once.

Parameters

count (int) – The number of new rows to add.
index (int | None) – The index of the first new row to add. If None (default), add the new rows at the end.

Raises

ValueError – If index is below zero or greater than the row count, or if index cannot be converted to an integer.
ValueError – If count is less than one or cannot be converted to an integer.
CollarTableRowError – If attempting to add rows to the collar table.

Warning

This invalidates the properties of the table, requiring them to be loaded from the database again.

property custom_fields: list[DrillholeDatabaseField]

Returns a list of custom fields in this table.

Custom fields are all fields which do not correspond to a field type defined in the FieldType enum.

dataframe(*, fields=None, include_hole_id=True, save_changes=False)

Context manager for a pandas dataframe representing this table.

Each field of the table becomes a column of the dataframe. The column name is the field name and the column contains the values of that field.

Parameters

fields (list[DrillholeDatabaseField] | None) – A list of fields to include in the dataframe. Only fields in the list will be included in the dataframe. If None (Default), the dataframe will include all fields in the table. Filtering out fields which will not be used will reduce the memory and time required to construct and perform operations on the dataframe.
include_hole_id (bool) – If True (Default) the hole id column will be included in the dataframe. This column will have the name BaseDrillholeTable.HOLE_ID and it will have a unique value for each drillhole in the underlying database. This allows for dataframes of the same table from different holes in the same database to be safely concatenated. If False, the hole id column will not be included.
save_changes (bool) – If False (default) any changes to the dataframe will not be propagated to the table. If True, and the object is open for reading, changes to the dataframe will be propagated to the table.

Yields

pd.DataFrame – Dataframe representing the table.

Raises

TypeError – If any item in fields is not a DrillholeDatabaseField.
ReadOnlyError – If save_changes is True when the object is open for reading.
TableMismatchError – If fields includes a field which is not part of this table.

Return type

Generator[pd.DataFrame, None, None]

Examples

Calculating the length of each interval in a table based on the to and from depth fields.

>>> from mapteksdk.project import Project
>>> from mapteksdk.geologycore import Drillhole
>>> project = Project()
>>> with project.read("path/to/drillhole") as drillhole:
...   drillhole: Drillhole
...   geology_table = drillhole.geology_table
...   to_depth_name = geology_table.to_depth.name
...   from_depth_name = geology_table.from_depth.name
...   with geology_table.dataframe() as frame:
...     # The dataframe is indexed via field name. Use the field name
...     # queried earlier.
...     length = frame[to_depth_name] - frame[from_depth_name]
...     print(length)

The above script only uses the to depth and from depth fields, however the dataframe includes all of the fields in the table. If the table has a large number of rows or fields, this can be very inefficient. The performance of the operation can be improved by filtering out the fields which are not needed as shown in the below version of the same script.

>>> from mapteksdk.project import Project
>>> from mapteksdk.geologycore import Drillhole
>>> project = Project()
>>> with project.read("path/to/drillhole") as drillhole:
...   drillhole: Drillhole
...   geology_table = drillhole.geology_table
...   to_depth = geology_table.to_depth
...   from_depth = geology_table.from_depth
...   with geology_table.dataframe(fields=(to_depth, from_depth)) as frame:
...     length = frame[to_depth.name] - frame[from_depth.name]
...     print(length)

field_by_name(name)

Returns the field with the specified name.

Parameters: name (str) – The name of the field to get
Returns: The field with the specified name.
Return type: BaseField
Raises: FieldNotFoundError – If there is no field with the specified name.

property field_count: int: The count of fields in the table.

property fields: list[DrillholeDatabaseField]: A list of the fields in this table.

fields_by_type(field_type)

Returns a list of fields with the specified field type.

Parameters: field_type (DrillholeFieldType) – The type of field to return fields for.
Returns: List of fields with the specified field type.
Return type: list
Raises: KeyError – If field_type is not part of the DrillholeFieldType enum.

property name: str

The table’s name.

This is a user-provided string. It may differ for equivalent tables in different databases.

remove_row(index)

Remove the specified row from the table.

Parameters

index (int) – Index of the row to remove.

Raises

ValueError – If index cannot be converted to an integer.
IndexError – If there is no row with the specified index.
CollarTableRowError – If attempting to remove a row from the collar table.

Warning

This invalidates the properties of the table, requiring them to be loaded from the database again.

remove_rows(index, count)

Remove count rows starting at index.

Parameters

index (int) – Index of the row to remove.
count (int) – The number of rows to remove.

Raises

ValueError – If index cannot be converted to an integer.
ValueError – If count cannot be converted to an integer.
IndexError – If one or more rows to delete do not exist.
CollarTableRowError – If attempting to remove rows from the collar table.

Warning

This invalidates the properties of the table, requiring them to be loaded from the database again.

property row_count: int: The number of rows in this table.

class GeologyTable(table_information)

Bases: BaseDrillholeTable, _GeologyTableMixin

Table containing geology information for a drillhole.

Parameters: table_information (dict) –

property table_type: The table’s type in the TableType enum.

property from_depth: DrillholeDatabaseField

The from depth field of a hole.

A value in this field represents the distance down the hole the interval the row represents starts down the hole.

Typically from_depth is coupled with the to_depth field to provide a depth range for an interval.

Raises

FieldNotFoundError – If there is no from depth field.
TooManyFieldsError – If there are multiple from fields in the table. This should not be possible. If this error is thrown, the database was invalid.

Warning

It is possible for intervals in this property to be out of order or overlap.

Notes

from_depth can be used on its own to define intervals. For example, given a from_depth field with values [A, B, C, D] then the first row represents the depth range [A, B), the second row represents the depth range [B, C), the third row represents the depth range [C, D) and the fourth row represents the depth range [D, total_depth).

property to_depth: DrillholeDatabaseField

The to depth field of the hole.

A value in this field represents the distance down the hole the interval the row represents ends at.

Typically to_depth is coupled with the from_depth field to provide a depth range for a interval.

Raises

FieldNotFoundError – If there is no to depth field.
TooManyFieldsError – If there are multiple to depth fields in the table. This should not be possible. If this error is thrown, the database was invalid.

Warning

It is possible for intervals in this property to be out of order or overlap.

Notes

to_depth can be used on its own to define intervals. For example, given a to_depth field with values [A, B, C, D] then the first row represents a depth range of [0, A), the second row represents a depth range of [A, B), the third row represents a depth range of [B, C) and the fourth row represents the depth range [C, D).

property thickness: DrillholeDatabaseField

Field representing the thickness of the hole in each interval.

Raises

FieldNotFoundError – If there is no thickness field.
TooManyFieldsError – If there are multiple thickness fields in the table. This should not be possible. If this error is thrown, the database was invalid.

property rock_type: DrillholeDatabaseField

The rock type field.

This indicates the type of rock in each interval defined by the to_depth and/or from_depth.

A table may contain multiple rock type fields. This property should only be used if you are certain that the table only contains one rock type field.

Raises: FieldNotFoundError – If there is no rock type field.
Warns: TooManyFieldsWarning – If the table contains multiple rock type fields. The first field was returned.

property horizon: DrillholeDatabaseField

The horizon field.

A table may contain multiple horizon fields. This property should only be used if you are certain that the table only contains one horizon field.

Raises: FieldNotFoundError – If there is no horizon field.
Warns: TooManyFieldsWarning – If the table contains multiple horizon fields. The first field was returned.

HOLE_ID = 'HOLE_ID': The name of the hole ID column in pandas dataframes.

add_row(*, index=None)

Add a new row to the table.

Parameters

index (int | None) – The index to add the new row at. If None (default), add the new row at the end.

Raises

ValueError – If index is below zero or greater than the row count, or if index cannot be converted to an integer.
CollarTableRowError – If attempting to add a row to the collar table.

Warning

This invalidates the properties of the table, requiring them to be loaded from the database again.

add_rows(count=1, *, index=None)

Add multiple rows to the table.

This is more efficient than adding a single row to the table multiple times because the properties of the table are only invalidated once.

Parameters

count (int) – The number of new rows to add.
index (int | None) – The index of the first new row to add. If None (default), add the new rows at the end.

Raises

ValueError – If index is below zero or greater than the row count, or if index cannot be converted to an integer.
ValueError – If count is less than one or cannot be converted to an integer.
CollarTableRowError – If attempting to add rows to the collar table.

Warning

This invalidates the properties of the table, requiring them to be loaded from the database again.

property custom_fields: list[DrillholeDatabaseField]

Returns a list of custom fields in this table.

Custom fields are all fields which do not correspond to a field type defined in the FieldType enum.

dataframe(*, fields=None, include_hole_id=True, save_changes=False)

Context manager for a pandas dataframe representing this table.

Each field of the table becomes a column of the dataframe. The column name is the field name and the column contains the values of that field.

Parameters

fields (list[DrillholeDatabaseField] | None) – A list of fields to include in the dataframe. Only fields in the list will be included in the dataframe. If None (Default), the dataframe will include all fields in the table. Filtering out fields which will not be used will reduce the memory and time required to construct and perform operations on the dataframe.
include_hole_id (bool) – If True (Default) the hole id column will be included in the dataframe. This column will have the name BaseDrillholeTable.HOLE_ID and it will have a unique value for each drillhole in the underlying database. This allows for dataframes of the same table from different holes in the same database to be safely concatenated. If False, the hole id column will not be included.
save_changes (bool) – If False (default) any changes to the dataframe will not be propagated to the table. If True, and the object is open for reading, changes to the dataframe will be propagated to the table.

Yields

pd.DataFrame – Dataframe representing the table.

Raises

TypeError – If any item in fields is not a DrillholeDatabaseField.
ReadOnlyError – If save_changes is True when the object is open for reading.
TableMismatchError – If fields includes a field which is not part of this table.

Return type

Generator[pd.DataFrame, None, None]

Examples

Calculating the length of each interval in a table based on the to and from depth fields.

>>> from mapteksdk.project import Project
>>> from mapteksdk.geologycore import Drillhole
>>> project = Project()
>>> with project.read("path/to/drillhole") as drillhole:
...   drillhole: Drillhole
...   geology_table = drillhole.geology_table
...   to_depth_name = geology_table.to_depth.name
...   from_depth_name = geology_table.from_depth.name
...   with geology_table.dataframe() as frame:
...     # The dataframe is indexed via field name. Use the field name
...     # queried earlier.
...     length = frame[to_depth_name] - frame[from_depth_name]
...     print(length)

The above script only uses the to depth and from depth fields, however the dataframe includes all of the fields in the table. If the table has a large number of rows or fields, this can be very inefficient. The performance of the operation can be improved by filtering out the fields which are not needed as shown in the below version of the same script.

>>> from mapteksdk.project import Project
>>> from mapteksdk.geologycore import Drillhole
>>> project = Project()
>>> with project.read("path/to/drillhole") as drillhole:
...   drillhole: Drillhole
...   geology_table = drillhole.geology_table
...   to_depth = geology_table.to_depth
...   from_depth = geology_table.from_depth
...   with geology_table.dataframe(fields=(to_depth, from_depth)) as frame:
...     length = frame[to_depth.name] - frame[from_depth.name]
...     print(length)

field_by_name(name)

Returns the field with the specified name.

Parameters: name (str) – The name of the field to get
Returns: The field with the specified name.
Return type: BaseField
Raises: FieldNotFoundError – If there is no field with the specified name.

property field_count: int: The count of fields in the table.

property fields: list[DrillholeDatabaseField]: A list of the fields in this table.

fields_by_type(field_type)

Returns a list of fields with the specified field type.

Parameters: field_type (DrillholeFieldType) – The type of field to return fields for.
Returns: List of fields with the specified field type.
Return type: list
Raises: KeyError – If field_type is not part of the DrillholeFieldType enum.

property name: str

The table’s name.

This is a user-provided string. It may differ for equivalent tables in different databases.

remove_row(index)

Remove the specified row from the table.

Parameters

index (int) – Index of the row to remove.

Raises

ValueError – If index cannot be converted to an integer.
IndexError – If there is no row with the specified index.
CollarTableRowError – If attempting to remove a row from the collar table.

Warning

This invalidates the properties of the table, requiring them to be loaded from the database again.

remove_rows(index, count)

Remove count rows starting at index.

Parameters

index (int) – Index of the row to remove.
count (int) – The number of rows to remove.

Raises

ValueError – If index cannot be converted to an integer.
ValueError – If count cannot be converted to an integer.
IndexError – If one or more rows to delete do not exist.
CollarTableRowError – If attempting to remove rows from the collar table.

Warning

This invalidates the properties of the table, requiring them to be loaded from the database again.

property row_count: int: The number of rows in this table.

class AssayTable(table_information)

Bases: BaseDrillholeTable, _TableWithDepthFieldsMixin

Table containing assay information for a drillhole.

Parameters: table_information (dict) –

property table_type: The table’s type in the TableType enum.

property from_depth: DrillholeDatabaseField

The from depth field of a hole.

A value in this field represents the distance down the hole the interval the row represents starts down the hole.

Typically from_depth is coupled with the to_depth field to provide a depth range for an interval.

Raises

FieldNotFoundError – If there is no from depth field.
TooManyFieldsError – If there are multiple from fields in the table. This should not be possible. If this error is thrown, the database was invalid.

Warning

It is possible for intervals in this property to be out of order or overlap.

Notes

from_depth can be used on its own to define intervals. For example, given a from_depth field with values [A, B, C, D] then the first row represents the depth range [A, B), the second row represents the depth range [B, C), the third row represents the depth range [C, D) and the fourth row represents the depth range [D, total_depth).

property to_depth: DrillholeDatabaseField

The to depth field of the hole.

A value in this field represents the distance down the hole the interval the row represents ends at.

Typically to_depth is coupled with the from_depth field to provide a depth range for a interval.

Raises

FieldNotFoundError – If there is no to depth field.
TooManyFieldsError – If there are multiple to depth fields in the table. This should not be possible. If this error is thrown, the database was invalid.

Warning

It is possible for intervals in this property to be out of order or overlap.

Notes

to_depth can be used on its own to define intervals. For example, given a to_depth field with values [A, B, C, D] then the first row represents a depth range of [0, A), the second row represents a depth range of [A, B), the third row represents a depth range of [B, C) and the fourth row represents the depth range [C, D).

property thickness: DrillholeDatabaseField

Field representing the thickness of the hole in each interval.

Raises

FieldNotFoundError – If there is no thickness field.
TooManyFieldsError – If there are multiple thickness fields in the table. This should not be possible. If this error is thrown, the database was invalid.

HOLE_ID = 'HOLE_ID': The name of the hole ID column in pandas dataframes.

add_row(*, index=None)

Add a new row to the table.

Parameters

index (int | None) – The index to add the new row at. If None (default), add the new row at the end.

Raises

ValueError – If index is below zero or greater than the row count, or if index cannot be converted to an integer.
CollarTableRowError – If attempting to add a row to the collar table.

Warning

This invalidates the properties of the table, requiring them to be loaded from the database again.

add_rows(count=1, *, index=None)

Add multiple rows to the table.

This is more efficient than adding a single row to the table multiple times because the properties of the table are only invalidated once.

Parameters

count (int) – The number of new rows to add.
index (int | None) – The index of the first new row to add. If None (default), add the new rows at the end.

Raises

ValueError – If index is below zero or greater than the row count, or if index cannot be converted to an integer.
ValueError – If count is less than one or cannot be converted to an integer.
CollarTableRowError – If attempting to add rows to the collar table.

Warning

This invalidates the properties of the table, requiring them to be loaded from the database again.

property custom_fields: list[DrillholeDatabaseField]

Returns a list of custom fields in this table.

Custom fields are all fields which do not correspond to a field type defined in the FieldType enum.

dataframe(*, fields=None, include_hole_id=True, save_changes=False)

Context manager for a pandas dataframe representing this table.

Each field of the table becomes a column of the dataframe. The column name is the field name and the column contains the values of that field.

Parameters

fields (list[DrillholeDatabaseField] | None) – A list of fields to include in the dataframe. Only fields in the list will be included in the dataframe. If None (Default), the dataframe will include all fields in the table. Filtering out fields which will not be used will reduce the memory and time required to construct and perform operations on the dataframe.
include_hole_id (bool) – If True (Default) the hole id column will be included in the dataframe. This column will have the name BaseDrillholeTable.HOLE_ID and it will have a unique value for each drillhole in the underlying database. This allows for dataframes of the same table from different holes in the same database to be safely concatenated. If False, the hole id column will not be included.
save_changes (bool) – If False (default) any changes to the dataframe will not be propagated to the table. If True, and the object is open for reading, changes to the dataframe will be propagated to the table.

Yields

pd.DataFrame – Dataframe representing the table.

Raises

TypeError – If any item in fields is not a DrillholeDatabaseField.
ReadOnlyError – If save_changes is True when the object is open for reading.
TableMismatchError – If fields includes a field which is not part of this table.

Return type

Generator[pd.DataFrame, None, None]

Examples

Calculating the length of each interval in a table based on the to and from depth fields.

>>> from mapteksdk.project import Project
>>> from mapteksdk.geologycore import Drillhole
>>> project = Project()
>>> with project.read("path/to/drillhole") as drillhole:
...   drillhole: Drillhole
...   geology_table = drillhole.geology_table
...   to_depth_name = geology_table.to_depth.name
...   from_depth_name = geology_table.from_depth.name
...   with geology_table.dataframe() as frame:
...     # The dataframe is indexed via field name. Use the field name
...     # queried earlier.
...     length = frame[to_depth_name] - frame[from_depth_name]
...     print(length)

The above script only uses the to depth and from depth fields, however the dataframe includes all of the fields in the table. If the table has a large number of rows or fields, this can be very inefficient. The performance of the operation can be improved by filtering out the fields which are not needed as shown in the below version of the same script.

>>> from mapteksdk.project import Project
>>> from mapteksdk.geologycore import Drillhole
>>> project = Project()
>>> with project.read("path/to/drillhole") as drillhole:
...   drillhole: Drillhole
...   geology_table = drillhole.geology_table
...   to_depth = geology_table.to_depth
...   from_depth = geology_table.from_depth
...   with geology_table.dataframe(fields=(to_depth, from_depth)) as frame:
...     length = frame[to_depth.name] - frame[from_depth.name]
...     print(length)

field_by_name(name)

Returns the field with the specified name.

Parameters: name (str) – The name of the field to get
Returns: The field with the specified name.
Return type: BaseField
Raises: FieldNotFoundError – If there is no field with the specified name.

property field_count: int: The count of fields in the table.

property fields: list[DrillholeDatabaseField]: A list of the fields in this table.

fields_by_type(field_type)

Returns a list of fields with the specified field type.

Parameters: field_type (DrillholeFieldType) – The type of field to return fields for.
Returns: List of fields with the specified field type.
Return type: list
Raises: KeyError – If field_type is not part of the DrillholeFieldType enum.

property name: str

The table’s name.

This is a user-provided string. It may differ for equivalent tables in different databases.

remove_row(index)

Remove the specified row from the table.

Parameters

index (int) – Index of the row to remove.

Raises

ValueError – If index cannot be converted to an integer.
IndexError – If there is no row with the specified index.
CollarTableRowError – If attempting to remove a row from the collar table.

Warning

This invalidates the properties of the table, requiring them to be loaded from the database again.

remove_rows(index, count)

Remove count rows starting at index.

Parameters

index (int) – Index of the row to remove.
count (int) – The number of rows to remove.

Raises

ValueError – If index cannot be converted to an integer.
ValueError – If count cannot be converted to an integer.
IndexError – If one or more rows to delete do not exist.
CollarTableRowError – If attempting to remove rows from the collar table.

Warning

This invalidates the properties of the table, requiring them to be loaded from the database again.

property row_count: int: The number of rows in this table.

class DownholeTable(table_information)

Bases: BaseDrillholeTable, _TableWithDepthFieldsMixin

Table containing downhole information for a drillhole.

Parameters: table_information (dict) –

property table_type: The table’s type in the TableType enum.

property from_depth: DrillholeDatabaseField

The from depth field of a hole.

A value in this field represents the distance down the hole the interval the row represents starts down the hole.

Typically from_depth is coupled with the to_depth field to provide a depth range for an interval.

Raises

FieldNotFoundError – If there is no from depth field.
TooManyFieldsError – If there are multiple from fields in the table. This should not be possible. If this error is thrown, the database was invalid.

Warning

It is possible for intervals in this property to be out of order or overlap.

Notes

from_depth can be used on its own to define intervals. For example, given a from_depth field with values [A, B, C, D] then the first row represents the depth range [A, B), the second row represents the depth range [B, C), the third row represents the depth range [C, D) and the fourth row represents the depth range [D, total_depth).

property to_depth: DrillholeDatabaseField

The to depth field of the hole.

A value in this field represents the distance down the hole the interval the row represents ends at.

Typically to_depth is coupled with the from_depth field to provide a depth range for a interval.

Raises

FieldNotFoundError – If there is no to depth field.
TooManyFieldsError – If there are multiple to depth fields in the table. This should not be possible. If this error is thrown, the database was invalid.

Warning

It is possible for intervals in this property to be out of order or overlap.

Notes

to_depth can be used on its own to define intervals. For example, given a to_depth field with values [A, B, C, D] then the first row represents a depth range of [0, A), the second row represents a depth range of [A, B), the third row represents a depth range of [B, C) and the fourth row represents the depth range [C, D).

property thickness: DrillholeDatabaseField

Field representing the thickness of the hole in each interval.

Raises

FieldNotFoundError – If there is no thickness field.
TooManyFieldsError – If there are multiple thickness fields in the table. This should not be possible. If this error is thrown, the database was invalid.

HOLE_ID = 'HOLE_ID': The name of the hole ID column in pandas dataframes.

add_row(*, index=None)

Add a new row to the table.

Parameters

index (int | None) – The index to add the new row at. If None (default), add the new row at the end.

Raises

ValueError – If index is below zero or greater than the row count, or if index cannot be converted to an integer.
CollarTableRowError – If attempting to add a row to the collar table.

Warning

This invalidates the properties of the table, requiring them to be loaded from the database again.

add_rows(count=1, *, index=None)

Add multiple rows to the table.

This is more efficient than adding a single row to the table multiple times because the properties of the table are only invalidated once.

Parameters

count (int) – The number of new rows to add.
index (int | None) – The index of the first new row to add. If None (default), add the new rows at the end.

Raises

ValueError – If index is below zero or greater than the row count, or if index cannot be converted to an integer.
ValueError – If count is less than one or cannot be converted to an integer.
CollarTableRowError – If attempting to add rows to the collar table.

Warning

This invalidates the properties of the table, requiring them to be loaded from the database again.

property custom_fields: list[DrillholeDatabaseField]

Returns a list of custom fields in this table.

Custom fields are all fields which do not correspond to a field type defined in the FieldType enum.

dataframe(*, fields=None, include_hole_id=True, save_changes=False)

Context manager for a pandas dataframe representing this table.

Each field of the table becomes a column of the dataframe. The column name is the field name and the column contains the values of that field.

Parameters

fields (list[DrillholeDatabaseField] | None) – A list of fields to include in the dataframe. Only fields in the list will be included in the dataframe. If None (Default), the dataframe will include all fields in the table. Filtering out fields which will not be used will reduce the memory and time required to construct and perform operations on the dataframe.
include_hole_id (bool) – If True (Default) the hole id column will be included in the dataframe. This column will have the name BaseDrillholeTable.HOLE_ID and it will have a unique value for each drillhole in the underlying database. This allows for dataframes of the same table from different holes in the same database to be safely concatenated. If False, the hole id column will not be included.
save_changes (bool) – If False (default) any changes to the dataframe will not be propagated to the table. If True, and the object is open for reading, changes to the dataframe will be propagated to the table.

Yields

pd.DataFrame – Dataframe representing the table.

Raises

TypeError – If any item in fields is not a DrillholeDatabaseField.
ReadOnlyError – If save_changes is True when the object is open for reading.
TableMismatchError – If fields includes a field which is not part of this table.

Return type

Generator[pd.DataFrame, None, None]

Examples

Calculating the length of each interval in a table based on the to and from depth fields.

>>> from mapteksdk.project import Project
>>> from mapteksdk.geologycore import Drillhole
>>> project = Project()
>>> with project.read("path/to/drillhole") as drillhole:
...   drillhole: Drillhole
...   geology_table = drillhole.geology_table
...   to_depth_name = geology_table.to_depth.name
...   from_depth_name = geology_table.from_depth.name
...   with geology_table.dataframe() as frame:
...     # The dataframe is indexed via field name. Use the field name
...     # queried earlier.
...     length = frame[to_depth_name] - frame[from_depth_name]
...     print(length)

The above script only uses the to depth and from depth fields, however the dataframe includes all of the fields in the table. If the table has a large number of rows or fields, this can be very inefficient. The performance of the operation can be improved by filtering out the fields which are not needed as shown in the below version of the same script.

>>> from mapteksdk.project import Project
>>> from mapteksdk.geologycore import Drillhole
>>> project = Project()
>>> with project.read("path/to/drillhole") as drillhole:
...   drillhole: Drillhole
...   geology_table = drillhole.geology_table
...   to_depth = geology_table.to_depth
...   from_depth = geology_table.from_depth
...   with geology_table.dataframe(fields=(to_depth, from_depth)) as frame:
...     length = frame[to_depth.name] - frame[from_depth.name]
...     print(length)

field_by_name(name)

Returns the field with the specified name.

Parameters: name (str) – The name of the field to get
Returns: The field with the specified name.
Return type: BaseField
Raises: FieldNotFoundError – If there is no field with the specified name.

property field_count: int: The count of fields in the table.

property fields: list[DrillholeDatabaseField]: A list of the fields in this table.

fields_by_type(field_type)

Returns a list of fields with the specified field type.

Parameters: field_type (DrillholeFieldType) – The type of field to return fields for.
Returns: List of fields with the specified field type.
Return type: list
Raises: KeyError – If field_type is not part of the DrillholeFieldType enum.

property name: str

The table’s name.

This is a user-provided string. It may differ for equivalent tables in different databases.

remove_row(index)

Remove the specified row from the table.

Parameters

index (int) – Index of the row to remove.

Raises

ValueError – If index cannot be converted to an integer.
IndexError – If there is no row with the specified index.
CollarTableRowError – If attempting to remove a row from the collar table.

Warning

This invalidates the properties of the table, requiring them to be loaded from the database again.

remove_rows(index, count)

Remove count rows starting at index.

Parameters

index (int) – Index of the row to remove.
count (int) – The number of rows to remove.

Raises

ValueError – If index cannot be converted to an integer.
ValueError – If count cannot be converted to an integer.
IndexError – If one or more rows to delete do not exist.
CollarTableRowError – If attempting to remove rows from the collar table.

Warning

This invalidates the properties of the table, requiring them to be loaded from the database again.

property row_count: int: The number of rows in this table.

class QualityTable(table_information)

Bases: BaseDrillholeTable, _TableWithDepthFieldsMixin

Table containing quality information for a drillhole.

Parameters: table_information (dict) –

property table_type: The table’s type in the TableType enum.

property from_depth: DrillholeDatabaseField

The from depth field of a hole.

A value in this field represents the distance down the hole the interval the row represents starts down the hole.

Typically from_depth is coupled with the to_depth field to provide a depth range for an interval.

Raises

FieldNotFoundError – If there is no from depth field.
TooManyFieldsError – If there are multiple from fields in the table. This should not be possible. If this error is thrown, the database was invalid.

Warning

It is possible for intervals in this property to be out of order or overlap.

Notes

from_depth can be used on its own to define intervals. For example, given a from_depth field with values [A, B, C, D] then the first row represents the depth range [A, B), the second row represents the depth range [B, C), the third row represents the depth range [C, D) and the fourth row represents the depth range [D, total_depth).

property to_depth: DrillholeDatabaseField

The to depth field of the hole.

A value in this field represents the distance down the hole the interval the row represents ends at.

Typically to_depth is coupled with the from_depth field to provide a depth range for a interval.

Raises

FieldNotFoundError – If there is no to depth field.
TooManyFieldsError – If there are multiple to depth fields in the table. This should not be possible. If this error is thrown, the database was invalid.

Warning

It is possible for intervals in this property to be out of order or overlap.

Notes

to_depth can be used on its own to define intervals. For example, given a to_depth field with values [A, B, C, D] then the first row represents a depth range of [0, A), the second row represents a depth range of [A, B), the third row represents a depth range of [B, C) and the fourth row represents the depth range [C, D).

property thickness: DrillholeDatabaseField

Field representing the thickness of the hole in each interval.

Raises

FieldNotFoundError – If there is no thickness field.
TooManyFieldsError – If there are multiple thickness fields in the table. This should not be possible. If this error is thrown, the database was invalid.

HOLE_ID = 'HOLE_ID': The name of the hole ID column in pandas dataframes.

add_row(*, index=None)

Add a new row to the table.

Parameters

index (int | None) – The index to add the new row at. If None (default), add the new row at the end.

Raises

ValueError – If index is below zero or greater than the row count, or if index cannot be converted to an integer.
CollarTableRowError – If attempting to add a row to the collar table.

Warning

This invalidates the properties of the table, requiring them to be loaded from the database again.

add_rows(count=1, *, index=None)

Add multiple rows to the table.

This is more efficient than adding a single row to the table multiple times because the properties of the table are only invalidated once.

Parameters

count (int) – The number of new rows to add.
index (int | None) – The index of the first new row to add. If None (default), add the new rows at the end.

Raises

ValueError – If index is below zero or greater than the row count, or if index cannot be converted to an integer.
ValueError – If count is less than one or cannot be converted to an integer.
CollarTableRowError – If attempting to add rows to the collar table.

Warning

This invalidates the properties of the table, requiring them to be loaded from the database again.

property custom_fields: list[DrillholeDatabaseField]

Returns a list of custom fields in this table.

Custom fields are all fields which do not correspond to a field type defined in the FieldType enum.

dataframe(*, fields=None, include_hole_id=True, save_changes=False)

Context manager for a pandas dataframe representing this table.

Each field of the table becomes a column of the dataframe. The column name is the field name and the column contains the values of that field.

Parameters

fields (list[DrillholeDatabaseField] | None) – A list of fields to include in the dataframe. Only fields in the list will be included in the dataframe. If None (Default), the dataframe will include all fields in the table. Filtering out fields which will not be used will reduce the memory and time required to construct and perform operations on the dataframe.
include_hole_id (bool) – If True (Default) the hole id column will be included in the dataframe. This column will have the name BaseDrillholeTable.HOLE_ID and it will have a unique value for each drillhole in the underlying database. This allows for dataframes of the same table from different holes in the same database to be safely concatenated. If False, the hole id column will not be included.
save_changes (bool) – If False (default) any changes to the dataframe will not be propagated to the table. If True, and the object is open for reading, changes to the dataframe will be propagated to the table.

Yields

pd.DataFrame – Dataframe representing the table.

Raises

TypeError – If any item in fields is not a DrillholeDatabaseField.
ReadOnlyError – If save_changes is True when the object is open for reading.
TableMismatchError – If fields includes a field which is not part of this table.

Return type

Generator[pd.DataFrame, None, None]

Examples

Calculating the length of each interval in a table based on the to and from depth fields.

>>> from mapteksdk.project import Project
>>> from mapteksdk.geologycore import Drillhole
>>> project = Project()
>>> with project.read("path/to/drillhole") as drillhole:
...   drillhole: Drillhole
...   geology_table = drillhole.geology_table
...   to_depth_name = geology_table.to_depth.name
...   from_depth_name = geology_table.from_depth.name
...   with geology_table.dataframe() as frame:
...     # The dataframe is indexed via field name. Use the field name
...     # queried earlier.
...     length = frame[to_depth_name] - frame[from_depth_name]
...     print(length)

The above script only uses the to depth and from depth fields, however the dataframe includes all of the fields in the table. If the table has a large number of rows or fields, this can be very inefficient. The performance of the operation can be improved by filtering out the fields which are not needed as shown in the below version of the same script.

>>> from mapteksdk.project import Project
>>> from mapteksdk.geologycore import Drillhole
>>> project = Project()
>>> with project.read("path/to/drillhole") as drillhole:
...   drillhole: Drillhole
...   geology_table = drillhole.geology_table
...   to_depth = geology_table.to_depth
...   from_depth = geology_table.from_depth
...   with geology_table.dataframe(fields=(to_depth, from_depth)) as frame:
...     length = frame[to_depth.name] - frame[from_depth.name]
...     print(length)

field_by_name(name)

Returns the field with the specified name.

Parameters: name (str) – The name of the field to get
Returns: The field with the specified name.
Return type: BaseField
Raises: FieldNotFoundError – If there is no field with the specified name.

property field_count: int: The count of fields in the table.

property fields: list[DrillholeDatabaseField]: A list of the fields in this table.

fields_by_type(field_type)

Returns a list of fields with the specified field type.

Parameters: field_type (DrillholeFieldType) – The type of field to return fields for.
Returns: List of fields with the specified field type.
Return type: list
Raises: KeyError – If field_type is not part of the DrillholeFieldType enum.

property name: str

The table’s name.

This is a user-provided string. It may differ for equivalent tables in different databases.

remove_row(index)

Remove the specified row from the table.

Parameters

index (int) – Index of the row to remove.

Raises

ValueError – If index cannot be converted to an integer.
IndexError – If there is no row with the specified index.
CollarTableRowError – If attempting to remove a row from the collar table.

Warning

This invalidates the properties of the table, requiring them to be loaded from the database again.

remove_rows(index, count)

Remove count rows starting at index.

Parameters

index (int) – Index of the row to remove.
count (int) – The number of rows to remove.

Raises

ValueError – If index cannot be converted to an integer.
ValueError – If count cannot be converted to an integer.
IndexError – If one or more rows to delete do not exist.
CollarTableRowError – If attempting to remove rows from the collar table.

Warning

This invalidates the properties of the table, requiring them to be loaded from the database again.

property row_count: int: The number of rows in this table.

class CustomTable(table_information)

Bases: BaseDrillholeTable

Table containing non-standard information for a drillhole.

Custom tables have no restrictions on the type and kind of data which is stored in them. All fields in custom tables are of type DrillholeFieldType.NONE and thus the values must be retrieved by name.

Parameters: table_information (dict) –

property table_type: The table’s type in the TableType enum.

HOLE_ID = 'HOLE_ID': The name of the hole ID column in pandas dataframes.

add_row(*, index=None)

Add a new row to the table.

Parameters

index (int | None) – The index to add the new row at. If None (default), add the new row at the end.

Raises

ValueError – If index is below zero or greater than the row count, or if index cannot be converted to an integer.
CollarTableRowError – If attempting to add a row to the collar table.

Warning

This invalidates the properties of the table, requiring them to be loaded from the database again.

add_rows(count=1, *, index=None)

Add multiple rows to the table.

This is more efficient than adding a single row to the table multiple times because the properties of the table are only invalidated once.

Parameters

count (int) – The number of new rows to add.
index (int | None) – The index of the first new row to add. If None (default), add the new rows at the end.

Raises

ValueError – If index is below zero or greater than the row count, or if index cannot be converted to an integer.
ValueError – If count is less than one or cannot be converted to an integer.
CollarTableRowError – If attempting to add rows to the collar table.

Warning

This invalidates the properties of the table, requiring them to be loaded from the database again.

property custom_fields: list[DrillholeDatabaseField]

Returns a list of custom fields in this table.

Custom fields are all fields which do not correspond to a field type defined in the FieldType enum.

dataframe(*, fields=None, include_hole_id=True, save_changes=False)

Context manager for a pandas dataframe representing this table.

Each field of the table becomes a column of the dataframe. The column name is the field name and the column contains the values of that field.

Parameters

fields (list[DrillholeDatabaseField] | None) – A list of fields to include in the dataframe. Only fields in the list will be included in the dataframe. If None (Default), the dataframe will include all fields in the table. Filtering out fields which will not be used will reduce the memory and time required to construct and perform operations on the dataframe.
include_hole_id (bool) – If True (Default) the hole id column will be included in the dataframe. This column will have the name BaseDrillholeTable.HOLE_ID and it will have a unique value for each drillhole in the underlying database. This allows for dataframes of the same table from different holes in the same database to be safely concatenated. If False, the hole id column will not be included.
save_changes (bool) – If False (default) any changes to the dataframe will not be propagated to the table. If True, and the object is open for reading, changes to the dataframe will be propagated to the table.

Yields

pd.DataFrame – Dataframe representing the table.

Raises

TypeError – If any item in fields is not a DrillholeDatabaseField.
ReadOnlyError – If save_changes is True when the object is open for reading.
TableMismatchError – If fields includes a field which is not part of this table.

Return type

Generator[pd.DataFrame, None, None]

Examples

Calculating the length of each interval in a table based on the to and from depth fields.

>>> from mapteksdk.project import Project
>>> from mapteksdk.geologycore import Drillhole
>>> project = Project()
>>> with project.read("path/to/drillhole") as drillhole:
...   drillhole: Drillhole
...   geology_table = drillhole.geology_table
...   to_depth_name = geology_table.to_depth.name
...   from_depth_name = geology_table.from_depth.name
...   with geology_table.dataframe() as frame:
...     # The dataframe is indexed via field name. Use the field name
...     # queried earlier.
...     length = frame[to_depth_name] - frame[from_depth_name]
...     print(length)

The above script only uses the to depth and from depth fields, however the dataframe includes all of the fields in the table. If the table has a large number of rows or fields, this can be very inefficient. The performance of the operation can be improved by filtering out the fields which are not needed as shown in the below version of the same script.

>>> from mapteksdk.project import Project
>>> from mapteksdk.geologycore import Drillhole
>>> project = Project()
>>> with project.read("path/to/drillhole") as drillhole:
...   drillhole: Drillhole
...   geology_table = drillhole.geology_table
...   to_depth = geology_table.to_depth
...   from_depth = geology_table.from_depth
...   with geology_table.dataframe(fields=(to_depth, from_depth)) as frame:
...     length = frame[to_depth.name] - frame[from_depth.name]
...     print(length)

field_by_name(name)

Returns the field with the specified name.

Parameters: name (str) – The name of the field to get
Returns: The field with the specified name.
Return type: BaseField
Raises: FieldNotFoundError – If there is no field with the specified name.

property field_count: int: The count of fields in the table.

property fields: list[DrillholeDatabaseField]: A list of the fields in this table.

fields_by_type(field_type)

Returns a list of fields with the specified field type.

Parameters: field_type (DrillholeFieldType) – The type of field to return fields for.
Returns: List of fields with the specified field type.
Return type: list
Raises: KeyError – If field_type is not part of the DrillholeFieldType enum.

property name: str

The table’s name.

This is a user-provided string. It may differ for equivalent tables in different databases.

remove_row(index)

Remove the specified row from the table.

Parameters

index (int) – Index of the row to remove.

Raises

ValueError – If index cannot be converted to an integer.
IndexError – If there is no row with the specified index.
CollarTableRowError – If attempting to remove a row from the collar table.

Warning

This invalidates the properties of the table, requiring them to be loaded from the database again.

remove_rows(index, count)

Remove count rows starting at index.

Parameters

index (int) – Index of the row to remove.
count (int) – The number of rows to remove.

Raises

ValueError – If index cannot be converted to an integer.
ValueError – If count cannot be converted to an integer.
IndexError – If one or more rows to delete do not exist.
CollarTableRowError – If attempting to remove rows from the collar table.

Warning

This invalidates the properties of the table, requiring them to be loaded from the database again.

property row_count: int: The number of rows in this table.

class CollarTableInformation(table_information)

Bases: BaseTableInformation, _CollarTableMixin

The configuration of the collar table.

A collar table is required to have the following fields:

DrillholeFieldType.EASTING
DrillholeFieldType.NORTHING

A collar table may also include fields of the following types:

DrillholeFieldType.ELEVATION
DrillholeFieldType.TOTAL_DEPTH
DrillholeFieldType.AZIMUTH
DrillholeFieldType.DIP
DrillholeFieldType.NONE

Parameters: table_information (dict) –

property table_type: The table’s type in the TableType enum.

property azimuth: FieldInformation

Field representing the azimuth of the drillhole.

Raises

FieldNotFoundError – If there is no azimuth field.
TooManyFieldsError – If there are multiple azimuth fields in the table. This should not be possible. If this error is thrown, the database was invalid.

property dip: FieldInformation

Field representing the dip angle of the drillhole.

Raises

FieldNotFoundError – If there is no dip field.
TooManyFieldsError – If there are multiple dip fields in the table. This should not be possible. If this error is thrown, the database was invalid.

property easting: FieldInformation

Field representing the easting of a drillhole.

In a default project, this corresponds to the x coordinate of the drillhole. Changes to the easting field will be propogated to the collar point of the drillhole when save() is called.

Raises

FieldNotFoundError – If there is no easting field.
TooManyFieldsError – If there are multiple easting fields in the table. This should not be possible. If this error is thrown, the database was invalid.

property northing: FieldInformation

Field representing the northing of a drillhole.

In a default project, this corresponds to the y coordinate of the drillhole. Changes to the northing field will be propogated to the collar point of the drillhole when save() is called.

Raises

FieldNotFoundError – If there is no easting field.
TooManyFieldsError – If there are multiple easting fields in the table. This should not be possible. If this error is thrown, the database was invalid.

property elevation: FieldInformation

Field representing the elevation of a drillhole.

In a default project, this corresponds to the z coordinate of the drillhole. Changes to the elevation field will be propogated to the collar point of the drillhole when save() is called.

Raises

FieldNotFoundError – If there is no elevation field.
TooManyFieldsError – If there are multiple elevation fields in the table. This should not be possible. If this error is thrown, the database was invalid.

property total_depth: FieldInformation

The total depth of the drillhole.

If any table has to_depth or from_depth fields, they should not contain values which exceed the total_depth of the drillhole.

Raises

FieldNotFoundError – If there is no total depth field.
TooManyFieldsError – If there are multiple total depth fields in the table. This should not be possible. If this error is thrown, the database was invalid.

add_field(name, data_type, description, *, field_type=DrillholeFieldType.NONE, unit=None, index=None)

Add a new field to the table.

After the database is closed, this new field will be available in all drillholes in the drillhole database.

Parameters

name (str) – The name for the new field.
data_type (type) – The type of data stored in the field. This can be int, float, bool, str or a numpy dtype.
description (str) – Description for the field.
field_type (DrillholeFieldType) – A keyword only argument to specify the field type to give to the new field. This defaults to DrillholeFieldType.None.
unit (DistanceUnit | AngleUnit | NO_UNIT | None) – The unit of the data stored in the field. If None (default) the default unit for the field type will be used. This is meters for distance fields and radians for angle fields.
index (int | None) – A keyword only argument for specifying the index in the table to insert the new field at. By default the new field will be inserted at the end of the table.

Raises

TypeError – If field_name or description are not strings.
TypeError – If data_type is not a valid data type.
TypeError – If field_type is not part of the DrillholeFieldType enum.
ValueError – If index is not a number or if it is below zero or greater than the number of fields.
DuplicateFieldNameError – If there is already a field with the specified name.
FieldTypeNotSupportedError – If field_type is not supported by table.
DuplicateFieldTypeError – If there is already a field with the specified type in the table and that field type does not support duplicates.
DataTypeNotSupportedError – If data_type is not supported by field_type.
UnitNotSupportedUnitError – If unit is not supported by field_type.
FieldDoesNotSupportUnitsError – If unit is not None or NO_UNIT for a field which does not support units.

property custom_fields: list[FieldInformation]

Returns a list of custom fields in this table.

Custom fields are all fields which do not correspond to a field type defined in the FieldType enum.

field_by_name(name)

Returns the field with the specified name.

Parameters: name (str) – The name of the field to get
Returns: The field with the specified name.
Return type: BaseField
Raises: FieldNotFoundError – If there is no field with the specified name.

property field_count: int: The count of fields in the table.

property fields: list[FieldInformation]: A list of the fields in this table.

fields_by_type(field_type)

Returns a list of fields with the specified field type.

Parameters: field_type (DrillholeFieldType) – The type of field to return fields for.
Returns: List of fields with the specified field type.
Return type: list
Raises: KeyError – If field_type is not part of the DrillholeFieldType enum.

property name: str

The table’s name.

This is a user-provided string. It may differ for equivalent tables in different databases.

class SurveyTableInformation(table_information)

Bases: BaseTableInformation, _SurveyTableMixin

The configuration of the survey table.

A survey table is required to include the following fields:

DrillholeFieldType.DEPTH
DrillholeFieldType.AZIMUTH
DrillholeFieldType.DIP

A survey table may also include fields of the following types:

DrillholeFieldType.NONE

Parameters: table_information (dict) –

property table_type: The table’s type in the TableType enum.

property azimuth: FieldInformation

Field representing the azimuth of the drillhole.

Raises

FieldNotFoundError – If there is no azimuth field.
TooManyFieldsError – If there are multiple azimuth fields in the table. This should not be possible. If this error is thrown, the database was invalid.

property dip: FieldInformation

Field representing the dip angle of the drillhole.

Raises

FieldNotFoundError – If there is no dip field.
TooManyFieldsError – If there are multiple dip fields in the table. This should not be possible. If this error is thrown, the database was invalid.

property depth: FieldInformation

The depth values for the table.

This indicates the depth each azimuth and dip measurement were taken at.

Raises

FieldNotFoundError – If there is no depth field.
TooManyFieldsError – If there are multiple depth fields in the table. This should not be possible. If this error is thrown, the database was invalid.

add_field(name, data_type, description, *, field_type=DrillholeFieldType.NONE, unit=None, index=None)

Add a new field to the table.

After the database is closed, this new field will be available in all drillholes in the drillhole database.

Parameters

name (str) – The name for the new field.
data_type (type) – The type of data stored in the field. This can be int, float, bool, str or a numpy dtype.
description (str) – Description for the field.
field_type (DrillholeFieldType) – A keyword only argument to specify the field type to give to the new field. This defaults to DrillholeFieldType.None.
unit (DistanceUnit | AngleUnit | NO_UNIT | None) – The unit of the data stored in the field. If None (default) the default unit for the field type will be used. This is meters for distance fields and radians for angle fields.
index (int | None) – A keyword only argument for specifying the index in the table to insert the new field at. By default the new field will be inserted at the end of the table.

Raises

TypeError – If field_name or description are not strings.
TypeError – If data_type is not a valid data type.
TypeError – If field_type is not part of the DrillholeFieldType enum.
ValueError – If index is not a number or if it is below zero or greater than the number of fields.
DuplicateFieldNameError – If there is already a field with the specified name.
FieldTypeNotSupportedError – If field_type is not supported by table.
DuplicateFieldTypeError – If there is already a field with the specified type in the table and that field type does not support duplicates.
DataTypeNotSupportedError – If data_type is not supported by field_type.
UnitNotSupportedUnitError – If unit is not supported by field_type.
FieldDoesNotSupportUnitsError – If unit is not None or NO_UNIT for a field which does not support units.

property custom_fields: list[FieldInformation]

Returns a list of custom fields in this table.

Custom fields are all fields which do not correspond to a field type defined in the FieldType enum.

field_by_name(name)

Returns the field with the specified name.

Parameters: name (str) – The name of the field to get
Returns: The field with the specified name.
Return type: BaseField
Raises: FieldNotFoundError – If there is no field with the specified name.

property field_count: int: The count of fields in the table.

property fields: list[FieldInformation]: A list of the fields in this table.

fields_by_type(field_type)

Returns a list of fields with the specified field type.

Parameters: field_type (DrillholeFieldType) – The type of field to return fields for.
Returns: List of fields with the specified field type.
Return type: list
Raises: KeyError – If field_type is not part of the DrillholeFieldType enum.

property name: str

The table’s name.

This is a user-provided string. It may differ for equivalent tables in different databases.

class GeologyTableInformation(table_information)

Bases: BaseTableInformation, _GeologyTableMixin

The configuration of a geology table.

A geology table must contain one field of the following type: * DrillholeFieldType.FROM_DEPTH * DrillholeFieldType.TO_DEPTH

Typically a geology table will contain both, however it is possible for it to only contain one. A geology table may also include fields of the following types:

DrillholeFieldType.THICKNESS
DrillholeFieldType.ROCK_TYPE
DrillholeFieldType.HORIZON
DrillholeFieldType.NONE

Parameters: table_information (dict) –

property table_type: The table’s type in the TableType enum.

property from_depth: FieldInformation

The from depth field of a hole.

A value in this field represents the distance down the hole the interval the row represents starts down the hole.

Typically from_depth is coupled with the to_depth field to provide a depth range for an interval.

Raises

FieldNotFoundError – If there is no from depth field.
TooManyFieldsError – If there are multiple from fields in the table. This should not be possible. If this error is thrown, the database was invalid.

Warning

It is possible for intervals in this property to be out of order or overlap.

Notes

from_depth can be used on its own to define intervals. For example, given a from_depth field with values [A, B, C, D] then the first row represents the depth range [A, B), the second row represents the depth range [B, C), the third row represents the depth range [C, D) and the fourth row represents the depth range [D, total_depth).

property to_depth: FieldInformation

The to depth field of the hole.

A value in this field represents the distance down the hole the interval the row represents ends at.

Typically to_depth is coupled with the from_depth field to provide a depth range for a interval.

Raises

FieldNotFoundError – If there is no to depth field.
TooManyFieldsError – If there are multiple to depth fields in the table. This should not be possible. If this error is thrown, the database was invalid.

Warning

It is possible for intervals in this property to be out of order or overlap.

Notes

to_depth can be used on its own to define intervals. For example, given a to_depth field with values [A, B, C, D] then the first row represents a depth range of [0, A), the second row represents a depth range of [A, B), the third row represents a depth range of [B, C) and the fourth row represents the depth range [C, D).

property thickness: FieldInformation

Field representing the thickness of the hole in each interval.

Raises

FieldNotFoundError – If there is no thickness field.
TooManyFieldsError – If there are multiple thickness fields in the table. This should not be possible. If this error is thrown, the database was invalid.

property rock_type: FieldInformation

The rock type field.

This indicates the type of rock in each interval defined by the to_depth and/or from_depth.

A table may contain multiple rock type fields. This property should only be used if you are certain that the table only contains one rock type field.

Raises: FieldNotFoundError – If there is no rock type field.
Warns: TooManyFieldsWarning – If the table contains multiple rock type fields. The first field was returned.

property horizon: FieldInformation

The horizon field.

A table may contain multiple horizon fields. This property should only be used if you are certain that the table only contains one horizon field.

Raises: FieldNotFoundError – If there is no horizon field.
Warns: TooManyFieldsWarning – If the table contains multiple horizon fields. The first field was returned.

add_field(name, data_type, description, *, field_type=DrillholeFieldType.NONE, unit=None, index=None)

Add a new field to the table.

After the database is closed, this new field will be available in all drillholes in the drillhole database.

Parameters

name (str) – The name for the new field.
data_type (type) – The type of data stored in the field. This can be int, float, bool, str or a numpy dtype.
description (str) – Description for the field.
field_type (DrillholeFieldType) – A keyword only argument to specify the field type to give to the new field. This defaults to DrillholeFieldType.None.
unit (DistanceUnit | AngleUnit | NO_UNIT | None) – The unit of the data stored in the field. If None (default) the default unit for the field type will be used. This is meters for distance fields and radians for angle fields.
index (int | None) – A keyword only argument for specifying the index in the table to insert the new field at. By default the new field will be inserted at the end of the table.

Raises

TypeError – If field_name or description are not strings.
TypeError – If data_type is not a valid data type.
TypeError – If field_type is not part of the DrillholeFieldType enum.
ValueError – If index is not a number or if it is below zero or greater than the number of fields.
DuplicateFieldNameError – If there is already a field with the specified name.
FieldTypeNotSupportedError – If field_type is not supported by table.
DuplicateFieldTypeError – If there is already a field with the specified type in the table and that field type does not support duplicates.
DataTypeNotSupportedError – If data_type is not supported by field_type.
UnitNotSupportedUnitError – If unit is not supported by field_type.
FieldDoesNotSupportUnitsError – If unit is not None or NO_UNIT for a field which does not support units.

property custom_fields: list[FieldInformation]

Returns a list of custom fields in this table.

Custom fields are all fields which do not correspond to a field type defined in the FieldType enum.

field_by_name(name)

Returns the field with the specified name.

Parameters: name (str) – The name of the field to get
Returns: The field with the specified name.
Return type: BaseField
Raises: FieldNotFoundError – If there is no field with the specified name.

property field_count: int: The count of fields in the table.

property fields: list[FieldInformation]: A list of the fields in this table.

fields_by_type(field_type)

Returns a list of fields with the specified field type.

Parameters: field_type (DrillholeFieldType) – The type of field to return fields for.
Returns: List of fields with the specified field type.
Return type: list
Raises: KeyError – If field_type is not part of the DrillholeFieldType enum.

property name: str

The table’s name.

This is a user-provided string. It may differ for equivalent tables in different databases.

class AssayTableInformation(table_information)

Bases: BaseTableInformation, _TableWithDepthFieldsMixin

The configuration of a assay table.

An assay table must contain one field of the following type: * DrillholeFieldType.FROM_DEPTH * DrillholeFieldType.TO_DEPTH

Typically an assay table will contain both, however it is possible for it to only contain one. An assay table may also include fields of the following types:

DrillholeFieldType.THICKNESS
DrillholeFieldType.NONE

Parameters: table_information (dict) –

property table_type: The table’s type in the TableType enum.

property from_depth: FieldInformation

The from depth field of a hole.

A value in this field represents the distance down the hole the interval the row represents starts down the hole.

Typically from_depth is coupled with the to_depth field to provide a depth range for an interval.

Raises

FieldNotFoundError – If there is no from depth field.
TooManyFieldsError – If there are multiple from fields in the table. This should not be possible. If this error is thrown, the database was invalid.

Warning

It is possible for intervals in this property to be out of order or overlap.

Notes

from_depth can be used on its own to define intervals. For example, given a from_depth field with values [A, B, C, D] then the first row represents the depth range [A, B), the second row represents the depth range [B, C), the third row represents the depth range [C, D) and the fourth row represents the depth range [D, total_depth).

property to_depth: FieldInformation

The to depth field of the hole.

A value in this field represents the distance down the hole the interval the row represents ends at.

Typically to_depth is coupled with the from_depth field to provide a depth range for a interval.

Raises

FieldNotFoundError – If there is no to depth field.
TooManyFieldsError – If there are multiple to depth fields in the table. This should not be possible. If this error is thrown, the database was invalid.

Warning

It is possible for intervals in this property to be out of order or overlap.

Notes

to_depth can be used on its own to define intervals. For example, given a to_depth field with values [A, B, C, D] then the first row represents a depth range of [0, A), the second row represents a depth range of [A, B), the third row represents a depth range of [B, C) and the fourth row represents the depth range [C, D).

property thickness: FieldInformation

Field representing the thickness of the hole in each interval.

Raises

FieldNotFoundError – If there is no thickness field.
TooManyFieldsError – If there are multiple thickness fields in the table. This should not be possible. If this error is thrown, the database was invalid.

add_field(name, data_type, description, *, field_type=DrillholeFieldType.NONE, unit=None, index=None)

Add a new field to the table.

After the database is closed, this new field will be available in all drillholes in the drillhole database.

Parameters

name (str) – The name for the new field.
data_type (type) – The type of data stored in the field. This can be int, float, bool, str or a numpy dtype.
description (str) – Description for the field.
field_type (DrillholeFieldType) – A keyword only argument to specify the field type to give to the new field. This defaults to DrillholeFieldType.None.
unit (DistanceUnit | AngleUnit | NO_UNIT | None) – The unit of the data stored in the field. If None (default) the default unit for the field type will be used. This is meters for distance fields and radians for angle fields.
index (int | None) – A keyword only argument for specifying the index in the table to insert the new field at. By default the new field will be inserted at the end of the table.

Raises

TypeError – If field_name or description are not strings.
TypeError – If data_type is not a valid data type.
TypeError – If field_type is not part of the DrillholeFieldType enum.
ValueError – If index is not a number or if it is below zero or greater than the number of fields.
DuplicateFieldNameError – If there is already a field with the specified name.
FieldTypeNotSupportedError – If field_type is not supported by table.
DuplicateFieldTypeError – If there is already a field with the specified type in the table and that field type does not support duplicates.
DataTypeNotSupportedError – If data_type is not supported by field_type.
UnitNotSupportedUnitError – If unit is not supported by field_type.
FieldDoesNotSupportUnitsError – If unit is not None or NO_UNIT for a field which does not support units.

property custom_fields: list[FieldInformation]

Returns a list of custom fields in this table.

Custom fields are all fields which do not correspond to a field type defined in the FieldType enum.

field_by_name(name)

Returns the field with the specified name.

Parameters: name (str) – The name of the field to get
Returns: The field with the specified name.
Return type: BaseField
Raises: FieldNotFoundError – If there is no field with the specified name.

property field_count: int: The count of fields in the table.

property fields: list[FieldInformation]: A list of the fields in this table.

fields_by_type(field_type)

Returns a list of fields with the specified field type.

Parameters: field_type (DrillholeFieldType) – The type of field to return fields for.
Returns: List of fields with the specified field type.
Return type: list
Raises: KeyError – If field_type is not part of the DrillholeFieldType enum.

property name: str

The table’s name.

This is a user-provided string. It may differ for equivalent tables in different databases.

class DownholeTableInformation(table_information)

Bases: BaseTableInformation, _TableWithDepthFieldsMixin

The configuration of a downhole table.

A downhole table must contain one field of the following type: * DrillholeFieldType.FROM_DEPTH * DrillholeFieldType.TO_DEPTH

Typically a downhole table will contain both, however it is possible for it to only contain one. A downhole table may also include fields of the following types:

DrillholeFieldType.THICKNESS
DrillholeFieldType.NONE

Parameters: table_information (dict) –

property table_type: The table’s type in the TableType enum.

property from_depth: FieldInformation

The from depth field of a hole.

A value in this field represents the distance down the hole the interval the row represents starts down the hole.

Typically from_depth is coupled with the to_depth field to provide a depth range for an interval.

Raises

FieldNotFoundError – If there is no from depth field.
TooManyFieldsError – If there are multiple from fields in the table. This should not be possible. If this error is thrown, the database was invalid.

Warning

It is possible for intervals in this property to be out of order or overlap.

Notes

from_depth can be used on its own to define intervals. For example, given a from_depth field with values [A, B, C, D] then the first row represents the depth range [A, B), the second row represents the depth range [B, C), the third row represents the depth range [C, D) and the fourth row represents the depth range [D, total_depth).

property to_depth: FieldInformation

The to depth field of the hole.

A value in this field represents the distance down the hole the interval the row represents ends at.

Typically to_depth is coupled with the from_depth field to provide a depth range for a interval.

Raises

FieldNotFoundError – If there is no to depth field.
TooManyFieldsError – If there are multiple to depth fields in the table. This should not be possible. If this error is thrown, the database was invalid.

Warning

It is possible for intervals in this property to be out of order or overlap.

Notes

to_depth can be used on its own to define intervals. For example, given a to_depth field with values [A, B, C, D] then the first row represents a depth range of [0, A), the second row represents a depth range of [A, B), the third row represents a depth range of [B, C) and the fourth row represents the depth range [C, D).

property thickness: FieldInformation

Field representing the thickness of the hole in each interval.

Raises

FieldNotFoundError – If there is no thickness field.
TooManyFieldsError – If there are multiple thickness fields in the table. This should not be possible. If this error is thrown, the database was invalid.

add_field(name, data_type, description, *, field_type=DrillholeFieldType.NONE, unit=None, index=None)

Add a new field to the table.

After the database is closed, this new field will be available in all drillholes in the drillhole database.

Parameters

name (str) – The name for the new field.
data_type (type) – The type of data stored in the field. This can be int, float, bool, str or a numpy dtype.
description (str) – Description for the field.
field_type (DrillholeFieldType) – A keyword only argument to specify the field type to give to the new field. This defaults to DrillholeFieldType.None.
unit (DistanceUnit | AngleUnit | NO_UNIT | None) – The unit of the data stored in the field. If None (default) the default unit for the field type will be used. This is meters for distance fields and radians for angle fields.
index (int | None) – A keyword only argument for specifying the index in the table to insert the new field at. By default the new field will be inserted at the end of the table.

Raises

TypeError – If field_name or description are not strings.
TypeError – If data_type is not a valid data type.
TypeError – If field_type is not part of the DrillholeFieldType enum.
ValueError – If index is not a number or if it is below zero or greater than the number of fields.
DuplicateFieldNameError – If there is already a field with the specified name.
FieldTypeNotSupportedError – If field_type is not supported by table.
DuplicateFieldTypeError – If there is already a field with the specified type in the table and that field type does not support duplicates.
DataTypeNotSupportedError – If data_type is not supported by field_type.
UnitNotSupportedUnitError – If unit is not supported by field_type.
FieldDoesNotSupportUnitsError – If unit is not None or NO_UNIT for a field which does not support units.

property custom_fields: list[FieldInformation]

Returns a list of custom fields in this table.

Custom fields are all fields which do not correspond to a field type defined in the FieldType enum.

field_by_name(name)

Returns the field with the specified name.

Parameters: name (str) – The name of the field to get
Returns: The field with the specified name.
Return type: BaseField
Raises: FieldNotFoundError – If there is no field with the specified name.

property field_count: int: The count of fields in the table.

property fields: list[FieldInformation]: A list of the fields in this table.

fields_by_type(field_type)

Returns a list of fields with the specified field type.

Parameters: field_type (DrillholeFieldType) – The type of field to return fields for.
Returns: List of fields with the specified field type.
Return type: list
Raises: KeyError – If field_type is not part of the DrillholeFieldType enum.

property name: str

The table’s name.

This is a user-provided string. It may differ for equivalent tables in different databases.

class QualityTableInformation(table_information)

Bases: BaseTableInformation, _TableWithDepthFieldsMixin

The configuration of a quality table.

An quality table must contain one field of the following type: * DrillholeFieldType.FROM_DEPTH * DrillholeFieldType.TO_DEPTH

Typically a quality table will contain both, however it is possible for it to only contain one. A quality table may also include fields of the following types:

DrillholeFieldType.THICKNESS
DrillholeFieldType.NONE

Parameters: table_information (dict) –

property table_type: The table’s type in the TableType enum.

property from_depth: FieldInformation

The from depth field of a hole.

A value in this field represents the distance down the hole the interval the row represents starts down the hole.

Typically from_depth is coupled with the to_depth field to provide a depth range for an interval.

Raises

FieldNotFoundError – If there is no from depth field.
TooManyFieldsError – If there are multiple from fields in the table. This should not be possible. If this error is thrown, the database was invalid.

Warning

It is possible for intervals in this property to be out of order or overlap.

Notes

from_depth can be used on its own to define intervals. For example, given a from_depth field with values [A, B, C, D] then the first row represents the depth range [A, B), the second row represents the depth range [B, C), the third row represents the depth range [C, D) and the fourth row represents the depth range [D, total_depth).

property to_depth: FieldInformation

The to depth field of the hole.

A value in this field represents the distance down the hole the interval the row represents ends at.

Typically to_depth is coupled with the from_depth field to provide a depth range for a interval.

Raises

FieldNotFoundError – If there is no to depth field.
TooManyFieldsError – If there are multiple to depth fields in the table. This should not be possible. If this error is thrown, the database was invalid.

Warning

It is possible for intervals in this property to be out of order or overlap.

Notes

to_depth can be used on its own to define intervals. For example, given a to_depth field with values [A, B, C, D] then the first row represents a depth range of [0, A), the second row represents a depth range of [A, B), the third row represents a depth range of [B, C) and the fourth row represents the depth range [C, D).

property thickness: FieldInformation

Field representing the thickness of the hole in each interval.

Raises

FieldNotFoundError – If there is no thickness field.
TooManyFieldsError – If there are multiple thickness fields in the table. This should not be possible. If this error is thrown, the database was invalid.

add_field(name, data_type, description, *, field_type=DrillholeFieldType.NONE, unit=None, index=None)

Add a new field to the table.

After the database is closed, this new field will be available in all drillholes in the drillhole database.

Parameters

name (str) – The name for the new field.
data_type (type) – The type of data stored in the field. This can be int, float, bool, str or a numpy dtype.
description (str) – Description for the field.
field_type (DrillholeFieldType) – A keyword only argument to specify the field type to give to the new field. This defaults to DrillholeFieldType.None.
unit (DistanceUnit | AngleUnit | NO_UNIT | None) – The unit of the data stored in the field. If None (default) the default unit for the field type will be used. This is meters for distance fields and radians for angle fields.
index (int | None) – A keyword only argument for specifying the index in the table to insert the new field at. By default the new field will be inserted at the end of the table.

Raises

TypeError – If field_name or description are not strings.
TypeError – If data_type is not a valid data type.
TypeError – If field_type is not part of the DrillholeFieldType enum.
ValueError – If index is not a number or if it is below zero or greater than the number of fields.
DuplicateFieldNameError – If there is already a field with the specified name.
FieldTypeNotSupportedError – If field_type is not supported by table.
DuplicateFieldTypeError – If there is already a field with the specified type in the table and that field type does not support duplicates.
DataTypeNotSupportedError – If data_type is not supported by field_type.
UnitNotSupportedUnitError – If unit is not supported by field_type.
FieldDoesNotSupportUnitsError – If unit is not None or NO_UNIT for a field which does not support units.

property custom_fields: list[FieldInformation]

Returns a list of custom fields in this table.

Custom fields are all fields which do not correspond to a field type defined in the FieldType enum.

field_by_name(name)

Returns the field with the specified name.

Parameters: name (str) – The name of the field to get
Returns: The field with the specified name.
Return type: BaseField
Raises: FieldNotFoundError – If there is no field with the specified name.

property field_count: int: The count of fields in the table.

property fields: list[FieldInformation]: A list of the fields in this table.

fields_by_type(field_type)

Returns a list of fields with the specified field type.

Parameters: field_type (DrillholeFieldType) – The type of field to return fields for.
Returns: List of fields with the specified field type.
Return type: list
Raises: KeyError – If field_type is not part of the DrillholeFieldType enum.

property name: str

The table’s name.

This is a user-provided string. It may differ for equivalent tables in different databases.

class CustomTableInformation(table_information)

Bases: BaseTableInformation

The configuration of a custom (user-defined) table.

Custom tables have no restrictions on the type and kind of data which is stored in them. They have no required fields and only support fields of type DrillholeFieldType.NONE.

Note that because these tables are custom, applications do not have any built-in support for interpreting or operating on the data stored in these tables.

Parameters: table_information (dict) –

property table_type: The table’s type in the TableType enum.

add_field(name, data_type, description, *, field_type=DrillholeFieldType.NONE, unit=None, index=None)

Add a new field to the table.

After the database is closed, this new field will be available in all drillholes in the drillhole database.

Parameters

name (str) – The name for the new field.
data_type (type) – The type of data stored in the field. This can be int, float, bool, str or a numpy dtype.
description (str) – Description for the field.
field_type (DrillholeFieldType) – A keyword only argument to specify the field type to give to the new field. This defaults to DrillholeFieldType.None.
unit (DistanceUnit | AngleUnit | NO_UNIT | None) – The unit of the data stored in the field. If None (default) the default unit for the field type will be used. This is meters for distance fields and radians for angle fields.
index (int | None) – A keyword only argument for specifying the index in the table to insert the new field at. By default the new field will be inserted at the end of the table.

Raises

TypeError – If field_name or description are not strings.
TypeError – If data_type is not a valid data type.
TypeError – If field_type is not part of the DrillholeFieldType enum.
ValueError – If index is not a number or if it is below zero or greater than the number of fields.
DuplicateFieldNameError – If there is already a field with the specified name.
FieldTypeNotSupportedError – If field_type is not supported by table.
DuplicateFieldTypeError – If there is already a field with the specified type in the table and that field type does not support duplicates.
DataTypeNotSupportedError – If data_type is not supported by field_type.
UnitNotSupportedUnitError – If unit is not supported by field_type.
FieldDoesNotSupportUnitsError – If unit is not None or NO_UNIT for a field which does not support units.

property custom_fields: list[FieldInformation]

Returns a list of custom fields in this table.

Custom fields are all fields which do not correspond to a field type defined in the FieldType enum.

field_by_name(name)

Returns the field with the specified name.

Parameters: name (str) – The name of the field to get
Returns: The field with the specified name.
Return type: BaseField
Raises: FieldNotFoundError – If there is no field with the specified name.

property field_count: int: The count of fields in the table.

property fields: list[FieldInformation]: A list of the fields in this table.

fields_by_type(field_type)

Returns a list of fields with the specified field type.

Parameters: field_type (DrillholeFieldType) – The type of field to return fields for.
Returns: List of fields with the specified field type.
Return type: list
Raises: KeyError – If field_type is not part of the DrillholeFieldType enum.

property name: str

The table’s name.

This is a user-provided string. It may differ for equivalent tables in different databases.