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 local PyVista plotting or the Trame server viewer.

Installation

Install the base package from PyPI:

pip install parq-blockmodel

Full 3-Step Workflow

For the complete experience (validate, profile, local visualization, and GIS/server options), install with all workflow extras:

pip install "parq-blockmodel[all]"

Installation by Workflow Step

Step 1: Validate — Pandera schema support for data validation:

pip install "parq-blockmodel[schema]"

Step 2: Review — HTML profiling reports for data quality inspection:

pip install "parq-blockmodel[profiling]"

Step 3: View — Local plotting with PyVista and Plotly:

pip install "parq-blockmodel[viz]"

**Optional: Spatial / GIS** — GeoDataFrame, GeoParquet, and polygon workflows:

```bash
pip install "parq-blockmodel[spatial]"

Optional: Server viewer — Trame web app support:

pip install "parq-blockmodel[server-viz]"

See the [Quick Start Guide](https://parq-blockmodel.readthedocs.io/en/stable/usage/quickstart.html) for a walkthrough of the 3-step workflow.

## 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:

```python
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.

Install parq-blockmodel[viz] for local PyVista/Plotly plotting, and add parq-blockmodel[server-viz] for Trame examples.

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.