GitHub source

evo.blockmodels.typed.base.BaseTypedBlockModel

Abstract base class for typed block model wrappers.

Provides shared functionality for all block model types including: - Data access via pandas DataFrames - Attribute management (add, update, delete, set units) - Report creation and listing - Version management - Metadata access

Subclasses must implement grid-type-specific properties and factory methods.

id 

id: UUID

The unique identifier of the block model.

name 

name: str

The name of the block model.

description 

description: str | None

The description of the block model.

origin 

origin: Point3

The origin point of the block model grid.

metadata 

metadata: BlockModel

The full block model metadata.

version 

version: Version

The current version information.

cell_data 

cell_data: DataFrame

The cell data as a pandas DataFrame.

__init__ 

__init__(client: BlockModelAPIClient, metadata: BlockModel, version: Version, cell_data: DataFrame) -> None

Initialize a BaseTypedBlockModel instance.

Parameters:

Name Type Description Default
client BlockModelAPIClient

The BlockModelAPIClient used for API operations.

 required
metadata BlockModel

The block model metadata.

 required
version Version

The current version information.

 required
cell_data DataFrame

The cell data as a pandas DataFrame.

 required

to_dataframe 

to_dataframe(
    columns: list[str] | None = None,
    version_uuid: UUID | None | Literal["latest"] = "latest",
    fb: IFeedback = NoFeedback,
) -> pd.DataFrame

Get block model data as a DataFrame.

Retrieves data from the Block Model Service and returns it as a pandas DataFrame with user-friendly column names.

Parameters:

Name Type Description Default
columns list[str] | None

List of column names to retrieve. Defaults to all columns ["*"].

 None
version_uuid UUID | None | Literal['latest']

Specific version to query. Use "latest" (default) for the latest version, or None to use the version referenced by this object.

 'latest'
fb IFeedback

Optional feedback interface for progress reporting.

 NoFeedback

Returns:

Type Description
DataFrame

DataFrame containing the block model data. Example: >>> df = await block_model.to_dataframe() >>> df.head()

add_attribute 

add_attribute(data: DataFrame, attribute_name: str, unit: str | None = None, fb: IFeedback = NoFeedback) -> Version

Add a new attribute to the block model.

The DataFrame must contain geometry columns (i, j, k) or (x, y, z) and the attribute column to add.

Parameters:

Name Type Description Default
data DataFrame

DataFrame containing geometry columns and the new attribute.

 required
attribute_name str

Name of the attribute column in the DataFrame to add.

 required
unit str | None

Optional unit ID for the attribute (must be a valid unit ID from the Block Model Service).

 None
fb IFeedback

Optional feedback interface for progress reporting.

 NoFeedback

Returns:

Type Description
Version

The new version created by adding the attribute.

update_attributes 

update_attributes(
    data: DataFrame,
    new_columns: list[str] | None = None,
    update_columns: set[str] | None = None,
    delete_columns: set[str] | None = None,
    units: dict[str, str] | None = None,
    fb: IFeedback = NoFeedback,
) -> Version

Update attributes in the block model.

Parameters:

Name Type Description Default
data DataFrame

DataFrame containing the updated data with geometry columns.

 required
new_columns list[str] | None

List of new column names to add.

 None
update_columns set[str] | None

Set of existing column names to update.

 None
delete_columns set[str] | None

Set of column names to delete.

 None
units dict[str, str] | None

Optional dictionary mapping column names to unit identifiers.

 None
fb IFeedback

Optional feedback interface for progress reporting.

 NoFeedback

Returns:

Type Description
Version

The new version created by the update.

set_attribute_units 

set_attribute_units(units: dict[str, str], fb: IFeedback = NoFeedback) -> Version

Set units for attributes on this block model.

This is required before creating reports, as reports need columns to have units defined.

Parameters:

Name Type Description Default
units dict[str, str]

Dictionary mapping attribute names to unit IDs (e.g., {"Au": "g/t", "density": "t/m3"}).

 required
fb IFeedback

Optional feedback interface for progress reporting.

 NoFeedback

Returns:

Type Description
Version

The new version created by the metadata update. Example: >>> from evo.blockmodels import Units >>> version = await block_model.set_attribute_units({ ... "Au": Units.GRAMS_PER_TONNE, ... "density": Units.TONNES_PER_CUBIC_METRE, ... })

get_versions 

get_versions() -> list[Version]

Get all versions of this block model.

Returns:

Type Description
list[Version]

List of versions, ordered from newest to oldest.

get_block_model_metadata 

get_block_model_metadata() -> BlockModel

Get the full block model metadata from the Block Model Service.

Returns:

Type Description
BlockModel

The BlockModel metadata from the Block Model Service.

create_report 

create_report(data: ReportSpecificationData, fb: IFeedback = NoFeedback) -> Report

Create a new report specification for this block model.

Reports require: 1. Columns to have units set (use set_attribute_units() first) 2. At least one category column for grouping (e.g., domain, rock type)

Parameters:

Name Type Description Default
data ReportSpecificationData

The report specification data.

 required
fb IFeedback

Optional feedback interface for progress reporting.

 NoFeedback

Returns:

Type Description
Report

A Report instance representing the created report. Example: >>> from evo.blockmodels.typed import ReportSpecificationData, ReportColumnSpec, ReportCategorySpec >>> report = await block_model.create_report(ReportSpecificationData( ... name="Gold Resource Report", ... columns=[ReportColumnSpec(column_name="Au", aggregation="WEIGHTED_MEAN", output_unit_id="g/t")], ... categories=[ReportCategorySpec(column_name="domain")], ... mass_unit_id="t", ... density_value=2.7, ... density_unit_id="t/m3", ... ))

list_reports 

list_reports(fb: IFeedback = NoFeedback) -> list[Report]

List all report specifications for this block model.

Parameters:

Name Type Description Default
fb IFeedback

Optional feedback interface for progress reporting.

 NoFeedback

Returns:

Type Description
list[Report]

List of Report instances.

refresh 

refresh(fb: IFeedback = NoFeedback) -> None

Refresh the block model data from the server.

Parameters:

Name Type Description Default
fb IFeedback

Optional feedback interface for progress reporting.

 NoFeedback