parq_blockmodel.blockmodel.ParquetBlockModel

class parq_blockmodel.blockmodel.ParquetBlockModel(blockmodel_path, name=None, geometry=None)

A class to represent a regular Parquet block model.

Block ordering is c-style, ordered by x, y, z coordinates.

blockmodel_path

The file path to the blockmodel Parquet file. This file is the source of the block model data. Consider a .pbm.parquet extension to imply a ParquetBlockModel file.

Type:

Path

name

The name of the block model, derived from the file name.

Type:

str

geometry

The geometry of the block model, derived from the Parquet file.

Type:

RegularGeometry

__init__(blockmodel_path, name=None, geometry=None)

Methods

__init__(blockmodel_path[, name, geometry])
create_demo_block_model(filename[, shape, ...])	Create a demo block model with specified parameters.
create_heatmap_from_threshold(attribute, ...)	Create a 2D heatmap from a 3D block model at a specified attribute threshold.
create_report([columns, column_batch_size, ...])	Create a ydata-profiling report for the block model.
create_toy_blockmodel(filename[, shape, ...])	Create a toy block model with specified parameters.
downsample(new_block_size, aggregation_config)	Downsample the block model to a coarser grid with specified aggregation methods for each attribute.
from_dataframe(dataframe, filename[, ...])	Create a ParquetBlockModel from a Pandas DataFrame.
from_geometry(geometry, path[, name])	Create a ParquetBlockModel from a RegularGeometry object.
from_parquet(parquet_path[, columns, ...])	Create a ParquetBlockModel instance from a Parquet file.
plot(scalar[, grid_type, threshold, ...])	Plot the block model using PyVista.
plot_heatmap(attribute, threshold[, axis, title])	Create a 2D heatmap plotly figure from a 3D block model at a specified attribute threshold.
read([columns, index, dense])	Read the Parquet file and return a DataFrame.
to_dense_parquet(filepath[, chunk_size, ...])	Save the block model to a Parquet file.
to_pyvista([grid_type, attributes])
upsample(new_block_size, interpolation_config)	Upsample the block model to a finer grid with specified interpolation methods for each attribute.
validate_sparse()

Attributes

centroid_index	Get the centroid index of the block model.
column_categorical_ordered
index_c	Zero-based C-order (x, y, z) indices for the dense grid.
index_f	Zero-based F-order (z, y, x) indices for the dense grid.
is_sparse
sparsity

property centroid_index: MultiIndex

Get the centroid index of the block model.

Returns:

The MultiIndex representing the centroid coordinates (x, y, z).

Return type:

pd.MultiIndex

classmethod create_demo_block_model(filename, shape=(3, 3, 3), block_size=(1, 1, 1), corner=(-0.5, -0.5, -0.5), axis_azimuth=0.0, axis_dip=0.0, axis_plunge=0.0)

Create a demo block model with specified parameters.

Parameters:

• filename (Path) – The file path where the Parquet file will be saved.

• shape (tuple) – The shape of the block model.

• block_size (tuple) – The size of each block.

• corner (tuple) – The coordinates of the corner of the block model.

• axis_azimuth (float) – The azimuth angle in degrees for rotation.

• axis_dip (float) – The dip angle in degrees for rotation.

• axis_plunge (float) – The plunge angle in degrees for rotation.

Returns:

An instance of ParquetBlockModel with demo data.

Return type:

ParquetBlockModel

create_heatmap_from_threshold(attribute, threshold, axis='z', return_array=False)

Create a 2D heatmap from a 3D block model at a specified attribute threshold.

Parameters:

• attribute (str) – The name of the attribute to threshold.

• threshold (float) – The threshold value for the attribute.

• axis (str) – The axis to view from (‘x’, ‘y’, or ‘z’). Defaults to ‘z’.

• return_array (bool) – If True, returns the heatmap as a NumPy array. Defaults to False.

Returns:

A 2D heatmap as a PyVista ImageData object or a NumPy array.

Return type:

Union[pv.ImageData, np.ndarray]

create_report(columns=None, column_batch_size=10, show_progress=True, open_in_browser=False)

Create a ydata-profiling report for the block model. The report will be of the same name as the block model, with a ‘.html’ extension.

Parameters:

• columns (Optional[list[str]]) – List of column names to include in the profile. If None, all columns are used.

• column_batch_size (int) – The number of columns to process in each batch. If None, processes all columns at once.

• show_progress (bool) – bool: If True, displays a progress bar during profiling.

• open_in_browser (bool) – bool: If True, opens the report in a web browser after generation.

Return type:

Path

Returns

Path: The path to the generated profile report.

classmethod create_toy_blockmodel(filename, shape=(3, 3, 3), block_size=(1, 1, 1), corner=(-0.5, -0.5, -0.5), axis_azimuth=0.0, axis_dip=0.0, axis_plunge=0.0, deposit_bearing=20.0, deposit_dip=30.0, deposit_plunge=10.0, grade_name='grade', grade_min=50.0, grade_max=65.0, deposit_center=(10.0, 7.5, 5.0), deposit_radii=(8.0, 5.0, 3.0), noise_std=0.2)

Create a toy block model with specified parameters.

Parameters:

• filename (Path) – The file path where the Parquet file will be saved.

• shape (tuple) – The shape of the block model.

• block_size (tuple) – The size of each block.

• corner (tuple) – The coordinates of the corner of the block model.

• axis_azimuth (float) – The azimuth angle in degrees for rotation.

• axis_dip (float) – The dip angle in degrees for rotation.

• axis_plunge (float) – The plunge angle in degrees for rotation.

• deposit_bearing (float) – The azimuth angle of the deposit in degrees.

• deposit_dip (float) – The dip angle of the deposit in degrees.

• deposit_plunge (float) – The plunge angle of the deposit in degrees.

• grade_name (str) – The name of the column to store the grade values.

• grade_min (float) – The minimum grade value.

• grade_max (float) – The maximum grade value.

• deposit_center (tuple) – The center of the deposit (x, y, z).

• deposit_radii (tuple) – The radii of the deposit (rx, ry, rz).

• noise_std (float) – (float):

Returns:

An instance of ParquetBlockModel with toy data.

Return type:

ParquetBlockModel

downsample(new_block_size, aggregation_config)

Downsample the block model to a coarser grid with specified aggregation methods for each attribute. This function supports downsampling of both categorical and numeric attributes. :type new_block_size: :param new_block_size: tuple of floats (dx, dy, dz) for the new block size. :type aggregation_config: :param aggregation_config: dict mapping attribute names to aggregation methods.

Example

aggregation_config = {

‘grade’: {‘method’: ‘weighted_mean’, ‘weight’: ‘dry_mass’}, ‘density’: {‘method’: ‘weighted_mean’, ‘weight’: ‘volume’}, ‘dry_mass’: {‘method’: ‘sum’}, ‘volume’: {‘method’: ‘sum’}, ‘rock_type’: {‘method’: ‘mode’}

}

Returns:

A new ParquetBlockModel instance with the downsampled grid.

Return type:

ParquetBlockModel

classmethod from_dataframe(dataframe, filename, geometry=None, name=None, overwrite=False, axis_azimuth=0.0, axis_dip=0.0, axis_plunge=0.0)

Create a ParquetBlockModel from a Pandas DataFrame. :type dataframe: DataFrame :param dataframe: The DataFrame containing block model data. :type dataframe: pd.DataFrame :type filename: Path :param filename: The file path where the Parquet file will be saved. :type filename: Path :type geometry: Optional[RegularGeometry] :param geometry: The geometry of the block model. If None, it will be inferred from the DataFrame. :type geometry: Optional[RegularGeometry] :type name: Optional[str] :param name: The name of the block model. If None, the name will be derived from the filename. :type name: Optional[str] :type overwrite: bool :param overwrite: If True, allows overwriting an existing ParquetBlockModel file. Defaults to False. :type overwrite: bool :type axis_azimuth: float :param axis_azimuth: The azimuth angle in degrees for rotation. Defaults to 0.0. :type axis_azimuth: float :type axis_dip: float :param axis_dip: The dip angle in degrees for rotation. Defaults to 0.0. :type axis_dip: float :type axis_plunge: float :param axis_plunge: The plunge angle in degrees for rotation. Defaults to 0.0. :type axis_plunge: float

Returns:

An instance of ParquetBlockModel created from the DataFrame.

Return type:

ParquetBlockModel

classmethod from_geometry(geometry, path, name=None)

Create a ParquetBlockModel from a RegularGeometry object.

The model will have no attributes.

Parameters:

• geometry (RegularGeometry) – The geometry of the block model.

• path (Path) – The file path where the Parquet file will be saved.

• name (Optional[str]) – The name of the block model. If None, the name will be derived from the path.

Returns:

An instance of ParquetBlockModel with the specified geometry.

Return type:

ParquetBlockModel

classmethod from_parquet(parquet_path, columns=None, overwrite=False, axis_azimuth=0.0, axis_dip=0.0, axis_plunge=0.0)

Create a ParquetBlockModel instance from a Parquet file.

Parameters:

• parquet_path (Path) – The path to the Parquet file.

• columns (Optional[list[str]]) – The list of columns to extract from the Parquet file.

• overwrite (bool) – If True, allows overwriting an existing ParquetBlockModel file. Defaults to False.

• axis_azimuth (float) – The azimuth angle in degrees for rotation. Defaults to 0.0.

• axis_dip (float) – The dip angle in degrees for rotation. Defaults to 0.0.

• axis_plunge (float) – The plunge angle in degrees for rotation. Defaults to 0.0.

Return type:

ParquetBlockModel

property index_c: ndarray

Zero-based C-order (x, y, z) indices for the dense grid.

property index_f: ndarray

Zero-based F-order (z, y, x) indices for the dense grid.

plot(scalar, grid_type='image', threshold=True, show_edges=True, show_axes=True, enable_picking=False, picked_attributes=None)

Plot the block model using PyVista.

Parameters:

• scalar (str) – The name of the scalar attribute to visualize.

• grid_type (Literal['image', 'structured', 'unstructured']) – The type of grid to use for plotting. Options are “image”, “structured”, or “unstructured”.

• threshold (bool) – The thresholding option for the mesh. If True, applies a threshold to the scalar values.

• show_edges (bool) – Show edges of the mesh.

• show_axes (bool) – Show the axes in the plot.

• enable_picking (bool) – If True, enables picking mode to interactively select cells in the plot.

• picked_attributes (Optional[list[str]]) – A list of attributes that will be returned in picking mode. If None, all attributes are returned.

Return type:

Plotter

Returns:

plot_heatmap(attribute, threshold, axis='z', title=None)

Create a 2D heatmap plotly figure from a 3D block model at a specified attribute threshold.

Parameters:

• attribute (str) – The name of the attribute to threshold.

• threshold (float) – The threshold value for the attribute.

• axis (str) – The axis to view from (‘x’, ‘y’, or ‘z’). Defaults to ‘z’.

• title (Optional[str]) – The title of the heatmap. If None, a default title is used.

Returns:

A Plotly figure containing the heatmap.

Return type:

go.Figure

read(columns=None, index='xyz', dense=False)

Read the Parquet file and return a DataFrame.

Parameters:

• columns (Optional[list[str]]) – List of column names to read. If None, all columns are read.

• index (Literal['xyz', 'ijk', None]) – The index type to use for the DataFrame. Options are “xyz” for centroid coordinates, “ijk” for block indices, or None for no index.

• dense (bool) – If True, reads the data as a dense grid. If False, reads the data as a sparse grid.

Returns:

The DataFrame containing the block model data.

Return type:

pd.DataFrame

to_dense_parquet(filepath, chunk_size=100000, show_progress=False)

Save the block model to a Parquet file.

This method saves the block model as a Parquet file by chunk. If dense is True, it saves the block model as a dense grid, :type filepath: Path :param filepath: The file path where the Parquet file will be saved. :type filepath: Path :type chunk_size: int :param chunk_size: The number of blocks to save in each chunk. Defaults to 100_000. :type chunk_size: int :type show_progress: bool :param show_progress: If True, show a progress bar. Defaults to False. :type show_progress: bool

Return type:

None

upsample(new_block_size, interpolation_config)

Upsample the block model to a finer grid with specified interpolation methods for each attribute. This function supports upsampling of both categorical and numeric attributes. :type new_block_size: :param new_block_size: tuple of floats (dx, dy, dz) for the new block size. :type interpolation_config: :param interpolation_config: dict mapping attribute names to interpolation methods.

Example

interpolation_config = {

‘grade’: {‘method’: ‘linear’}, ‘density’: {‘method’: ‘nearest’}, ‘dry_mass’: {‘method’: ‘linear’}, ‘volume’: {‘method’: ‘linear’}, ‘rock_type’: {‘method’: ‘nearest’}

}

Returns:

A new ParquetBlockModel instance with the upsampled grid.

Return type:

ParquetBlockModel