parq-blockmodel

Overview

A Python package for efficient storage, manipulation, and analysis of mining block models using Parquet files. parq-blockmodel provides tools for reading, writing, indexing, and transforming large-scale block model datasets, leveraging the performance of Apache Arrow and Parquet for scalable geoscience data workflows.

Typical 3-step workflow

parq-blockmodel is designed around a practical 3-step process:

1. Validate block model attributes against a Pandera schema.
2. Review (profile) data quality and distributions with an HTML profile report.
3. View the model interactively with the PyVista/Trame visualization path.

Installation

Install the base package from PyPI:

pip install parq-blockmodel

Install the optional schema validation support when you want to validate block model attributes with Pandera schemas or load schema definitions from YAML:

pip install "parq-blockmodel[schema]"

Install the visualization extras when you want to use the Trame viewer:

pip install "parq-blockmodel[viz]"

Schema validation

ParquetBlockModel accepts an optional schema= argument on its main constructors. You can pass either a Pandera DataFrameSchema object or a path to a YAML schema file, then validate the resulting model in chunks:

from pathlib import Path

from parq_blockmodel import ParquetBlockModel

pbm = ParquetBlockModel.from_parquet(
    Path("path/to/blockmodel.parquet"),
    schema=Path("schemas/blockmodel.schema.yaml"),
)

pbm.validate()
pbm.validate(sample_chunks=1)  # quick spot-check for large models

See the User Guide for detailed documentation on calculated attributes, including custom lookups and functions.

Profiling report review

Install profiling support and create an HTML profile report:

pip install "parq-blockmodel[profiling]"

report = pbm.create_report(columns_per_batch=None)
print(report.output_path)

When a schema includes column title / description, those values are included in report variable descriptions. See the Profiling Reports guide and the examples gallery for a full walkthrough.

Visualization

The block-model plotting path now delegates through parq_blockmodel.visualization, which keeps the rendering logic isolated from ParquetBlockModel itself.

from parq_blockmodel import ParquetBlockModel
from parq_blockmodel.visualization import BlockModelTrameApp, TrameBlockModelPlotEngine

pbm = ParquetBlockModel.from_parquet("orebody.parquet")
plotter = pbm.plot(scalar="grade", z_up_lock=True, z_up_hotkey="z")

# Optional terrain context for the PyVista engine:
# - elevation_raster adds a DEM surface
# - imagery_raster textures the DEM when both rasters align
plotter = pbm.plot(
    scalar="grade",
    elevation_raster="dem.tif",
    imagery_raster="imagery.tif",
)

trame_app_from_plot = pbm.plot(
    scalar="grade",
    engine=TrameBlockModelPlotEngine(),
    z_up_lock=True,
    z_up_hotkey="z",
)

app = BlockModelTrameApp(pbm, scalar="grade", z_up_lock=True, z_up_hotkey="z")

With z_up_lock=True, hold z for turntable-style orbit (yaw/pitch, no roll) with camera up aligned to +Z.

Geometry operations

parq-blockmodel supports three geometry flagging workflows:

• Polygon flagging for 2D XY regions.
• Surface encoding for 2.5D elevation surfaces (z = f(x, y)).
• Solid flagging for closed 3D volumes.