From f05579db6a7ea5586fd6501f2c4e32f6bc01d69e Mon Sep 17 00:00:00 2001
From: Amirabbas Jalali
<258926044+amirabbas-jalali-bentley@users.noreply.github.com>
Date: Mon, 16 Nov 2026 20:04:21 -0600
Subject: [PATCH 1/2] Add cross-validation task SDK client
---
.github/workflows/mkdocs-build.yaml | 3 +
.../docs/examples/cross_validation.ipynb | 420 +++++++
.../src/evo/compute/tasks/__init__.py | 4 +
.../src/evo/compute/tasks/common/results.py | 4 +-
.../src/evo/compute/tasks/common/search.py | 13 +-
.../compute/tasks/geostatistics/__init__.py | 4 +
.../tasks/geostatistics/cross_validation.py | 907 ++++++++++++++
.../compute/tasks/geostatistics/kriging.py | 4 +
.../test_cross_validation_tasks.py | 1043 +++++++++++++++++
9 files changed, 2394 insertions(+), 8 deletions(-)
create mode 100644 packages/evo-compute/docs/examples/cross_validation.ipynb
create mode 100644 packages/evo-compute/src/evo/compute/tasks/geostatistics/cross_validation.py
create mode 100644 packages/evo-compute/tests/geostatistics/test_cross_validation_tasks.py
diff --git a/.github/workflows/mkdocs-build.yaml b/.github/workflows/mkdocs-build.yaml
index 369f21f9c..665c88b06 100644
--- a/.github/workflows/mkdocs-build.yaml
+++ b/.github/workflows/mkdocs-build.yaml
@@ -35,6 +35,9 @@ jobs:
run: |
uv run mkdocs build --config-file mkdocs/mkdocs.yml --site-dir site
+ - name: Include new generated pages in the documentation diff
+ run: git add --intent-to-add mkdocs
+
- name: Check for changes
id: changes
run: |
diff --git a/packages/evo-compute/docs/examples/cross_validation.ipynb b/packages/evo-compute/docs/examples/cross_validation.ipynb
new file mode 100644
index 000000000..e0d255464
--- /dev/null
+++ b/packages/evo-compute/docs/examples/cross_validation.ipynb
@@ -0,0 +1,420 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "id": "0",
+ "metadata": {},
+ "source": [
+ "# Cross-Validation Compute Task\n",
+ "\n",
+ "This notebook demonstrates how to evaluate estimation parameters using the `geostatistics/cross-validation` compute task in `evo-compute`.\n",
+ "\n",
+ "Cross-validation holds samples out of a source dataset, re-estimates them at their own locations from the remaining samples, writes the estimates (and optional signed errors and kriging diagnostics) back onto the source object, and returns summary statistics.\n",
+ "\n",
+ "Two tagged unions configure each run:\n",
+ "\n",
+ "- **Hold-out strategy (`validation`)**:\n",
+ " - `LeaveOneSampleOut()` — holds out each sample and any coincident samples.\n",
+ " - `LeaveOneDrillholeOut()` — holds out every sample sharing one drillhole ID (requires a `DownholeIntervals` source).\n",
+ "- **Estimator (`estimator`)**:\n",
+ " - `KrigingEstimator` — ordinary or simple kriging with a variogram and optional `KrigingDiagnostics`.\n",
+ " - `IDWEstimator` — inverse-distance weighting with a positive `power`.\n",
+ " - `KNNEstimator` — k-nearest-neighbour arithmetic mean."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "1",
+ "metadata": {},
+ "source": [
+ "## Authentication\n",
+ "\n",
+ "Authenticate with Seequent Evo using `ServiceManagerWidget`:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "2",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from evo.notebooks import ServiceManagerWidget\n",
+ "\n",
+ "manager = await ServiceManagerWidget.with_auth_code(\n",
+ " client_id=\"your-client-id\", cache_location=\"./notebook-data\"\n",
+ ").login()"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "3",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Load the widgets extension for rich HTML display\n",
+ "%load_ext evo.widgets"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "4",
+ "metadata": {},
+ "source": [
+ "## Example 1: Sample Cross-Validation (`LeaveOneSampleOut`)\n",
+ "\n",
+ "Create a synthetic `PointSet` and `Variogram`, then compare kriging, IDW, and KNN using leave-one-sample-out cross-validation."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "5",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import uuid\n",
+ "\n",
+ "import numpy as np\n",
+ "import pandas as pd\n",
+ "from evo.objects.typed import (\n",
+ " Ellipsoid,\n",
+ " EllipsoidRanges,\n",
+ " EpsgCode,\n",
+ " PointSet,\n",
+ " PointSetData,\n",
+ " Rotation,\n",
+ " SphericalStructure,\n",
+ " Variogram,\n",
+ " VariogramData,\n",
+ ")\n",
+ "\n",
+ "rng = np.random.default_rng(42)\n",
+ "n_samples = 120\n",
+ "x = rng.uniform(0.0, 500.0, n_samples)\n",
+ "y = rng.uniform(0.0, 500.0, n_samples)\n",
+ "z = rng.uniform(0.0, 100.0, n_samples)\n",
+ "grade = 1.2 + 0.002 * x + 0.001 * y + rng.normal(0.0, 0.25, n_samples)\n",
+ "domain = np.where(x < 250.0, \"West\", \"East\")\n",
+ "\n",
+ "sample_points = await PointSet.create(\n",
+ " manager,\n",
+ " PointSetData(\n",
+ " name=f\"Cross-Validation Samples - {uuid.uuid4()}\",\n",
+ " coordinate_reference_system=EpsgCode(32632),\n",
+ " locations=pd.DataFrame({\"x\": x, \"y\": y, \"z\": z, \"grade\": grade, \"domain\": pd.Categorical(domain)}),\n",
+ " ),\n",
+ ")\n",
+ "\n",
+ "variogram = await Variogram.create(\n",
+ " manager,\n",
+ " VariogramData(\n",
+ " name=f\"Grade Variogram - {uuid.uuid4()}\",\n",
+ " sill=0.20,\n",
+ " nugget=0.03,\n",
+ " is_rotation_fixed=True,\n",
+ " modelling_space=\"data\",\n",
+ " data_variance=0.20,\n",
+ " structures=[\n",
+ " SphericalStructure(\n",
+ " contribution=0.17,\n",
+ " anisotropy=Ellipsoid(\n",
+ " ranges=EllipsoidRanges(major=200.0, semi_major=150.0, minor=80.0),\n",
+ " rotation=Rotation(dip_azimuth=30.0, dip=15.0, pitch=0.0),\n",
+ " ),\n",
+ " )\n",
+ " ],\n",
+ " attribute=\"grade\",\n",
+ " domain=\"all\",\n",
+ " ),\n",
+ ")\n",
+ "\n",
+ "sample_points"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "6",
+ "metadata": {},
+ "source": [
+ "### Run Kriging, IDW, and KNN Sample Cross-Validation\n",
+ "\n",
+ "Define one `CrossValidationParameters` per estimator and submit all three concurrently with `run(..., preview=True)`.\n",
+ "For kriging, request per-sample `KrigingDiagnostics` alongside the estimate and signed error (`estimate - true`)."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "7",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from evo.compute.tasks import KrigingDiagnostics, SearchNeighborhood, run\n",
+ "from evo.compute.tasks.geostatistics.cross_validation import (\n",
+ " CrossValidationOutputs,\n",
+ " CrossValidationParameters,\n",
+ " IDWEstimator,\n",
+ " KNNEstimator,\n",
+ " KrigingEstimator,\n",
+ " LeaveOneSampleOut,\n",
+ ")\n",
+ "\n",
+ "search = SearchNeighborhood(\n",
+ " ellipsoid=variogram.get_ellipsoid().scaled(1.5),\n",
+ " max_samples=20,\n",
+ " min_samples=3,\n",
+ ")\n",
+ "\n",
+ "kriging_cv = CrossValidationParameters(\n",
+ " source=sample_points.attributes[\"grade\"],\n",
+ " validation=LeaveOneSampleOut(),\n",
+ " estimator=KrigingEstimator(\n",
+ " variogram=variogram,\n",
+ " neighborhood=search,\n",
+ " diagnostics=KrigingDiagnostics(\n",
+ " kriging_variance=\"ok_cv_kv\",\n",
+ " slope_of_regression=\"ok_cv_sor\",\n",
+ " num_samples=\"ok_cv_ns\",\n",
+ " ),\n",
+ " ),\n",
+ " outputs=CrossValidationOutputs(estimate=\"ok_cv_est\", error=\"ok_cv_err\"),\n",
+ ")\n",
+ "\n",
+ "idw_cv = CrossValidationParameters(\n",
+ " source=sample_points.attributes[\"grade\"],\n",
+ " validation=LeaveOneSampleOut(),\n",
+ " estimator=IDWEstimator(neighborhood=search, power=2.0),\n",
+ " outputs=CrossValidationOutputs(estimate=\"idw_cv_est\", error=\"idw_cv_err\"),\n",
+ ")\n",
+ "\n",
+ "knn_cv = CrossValidationParameters(\n",
+ " source=sample_points.attributes[\"grade\"],\n",
+ " validation=LeaveOneSampleOut(),\n",
+ " estimator=KNNEstimator(neighborhood=search),\n",
+ " outputs=CrossValidationOutputs(estimate=\"knn_cv_est\", error=\"knn_cv_err\"),\n",
+ ")\n",
+ "\n",
+ "sample_results = await run(manager, [kriging_cv, idw_cv, knn_cv], preview=True)\n",
+ "kriging_result, idw_result, knn_result = sample_results\n",
+ "print(kriging_result)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "8",
+ "metadata": {},
+ "source": [
+ "### Compare Summary Statistics Across Estimators\n",
+ "\n",
+ "Every result carries `result.statistics` over the samples that produced a valid estimate (`valid_count`).\n",
+ "Kriging additionally returns `result.kriging_statistics` with standardized error metrics (`mean_standardized_error` ideally near `0`, `standardized_error_variance` ideally near `1`)."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "9",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "summary_rows = []\n",
+ "for label, res in [(\"Ordinary Kriging\", kriging_result), (\"IDW (p=2)\", idw_result), (\"KNN\", knn_result)]:\n",
+ " s = res.statistics\n",
+ " ks = res.kriging_statistics\n",
+ " summary_rows.append(\n",
+ " {\n",
+ " \"Estimator\": label,\n",
+ " \"Evaluated\": s.evaluated_count,\n",
+ " \"Valid\": s.valid_count,\n",
+ " \"Invalid\": s.invalid_count,\n",
+ " \"Mean Error\": s.mean_error,\n",
+ " \"MAE\": s.mean_absolute_error,\n",
+ " \"RMSE\": s.root_mean_squared_error,\n",
+ " \"Correlation\": s.correlation,\n",
+ " \"Regression Slope\": s.regression_slope,\n",
+ " \"Std Error Var\": ks.standardized_error_variance if ks is not None else None,\n",
+ " }\n",
+ " )\n",
+ "\n",
+ "pd.DataFrame(summary_rows).set_index(\"Estimator\")"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "10",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Inspect the per-sample estimates, signed errors, and kriging diagnostics as a DataFrame.\n",
+ "# Samples that did not satisfy the search constraints carry NaN in the estimate and error columns.\n",
+ "sample_df = await kriging_result.to_dataframe(\n",
+ " \"grade\",\n",
+ " kriging_result.estimate_name,\n",
+ " kriging_result.error_name,\n",
+ " *(attr.name for attr in kriging_result.diagnostics.values()),\n",
+ ")\n",
+ "sample_df.head()"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "11",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import plotly.express as px\n",
+ "\n",
+ "valid_df = sample_df.dropna(subset=[kriging_result.estimate_name])\n",
+ "fig = px.scatter(\n",
+ " valid_df,\n",
+ " x=kriging_result.estimate_name,\n",
+ " y=\"grade\",\n",
+ " title=\"Leave-One-Sample-Out Cross-Validation: True vs Estimated Grade\",\n",
+ " labels={kriging_result.estimate_name: \"Estimated Grade\", \"grade\": \"True Grade\"},\n",
+ ")\n",
+ "bounds = [\n",
+ " min(valid_df[\"grade\"].min(), valid_df[kriging_result.estimate_name].min()),\n",
+ " max(valid_df[\"grade\"].max(), valid_df[kriging_result.estimate_name].max()),\n",
+ "]\n",
+ "fig.add_scatter(x=bounds, y=bounds, mode=\"lines\", name=\"1:1 Reference\", line=dict(dash=\"dash\", color=\"gray\"))\n",
+ "fig.show()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "12",
+ "metadata": {},
+ "source": [
+ "## Example 2: Drillhole Cross-Validation (`LeaveOneDrillholeOut`)\n",
+ "\n",
+ "When samples come from drillholes (`DownholeIntervals`), nearby intervals along the same hole strongly correlate with each other.\n",
+ "`LeaveOneDrillholeOut()` holds out an entire drillhole at a time and re-estimates all of its intervals strictly from the remaining holes."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "13",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from evo.objects.typed import DownholeIntervals, DownholeIntervalsData\n",
+ "\n",
+ "hole_frames = []\n",
+ "collar_xy = [(100.0, 100.0), (180.0, 120.0), (140.0, 200.0), (240.0, 190.0), (200.0, 280.0), (300.0, 260.0)]\n",
+ "n_intervals = 15\n",
+ "\n",
+ "for idx, (cx, cy) in enumerate(collar_xy, start=1):\n",
+ " hole_id = f\"DH{idx:03d}\"\n",
+ " depths = np.linspace(0.0, 75.0, n_intervals + 1)\n",
+ " from_d, to_d = depths[:-1], depths[1:]\n",
+ " mid_d = 0.5 * (from_d + to_d)\n",
+ " hole_grade = 1.0 + 0.002 * cx + 0.0015 * cy - 0.004 * mid_d + rng.normal(0.0, 0.15, n_intervals)\n",
+ " hole_frames.append(\n",
+ " pd.DataFrame(\n",
+ " {\n",
+ " \"hole_id\": hole_id,\n",
+ " \"from\": from_d,\n",
+ " \"to\": to_d,\n",
+ " \"x_start\": np.full(n_intervals, cx),\n",
+ " \"y_start\": np.full(n_intervals, cy),\n",
+ " \"z_start\": -from_d,\n",
+ " \"x_end\": np.full(n_intervals, cx),\n",
+ " \"y_end\": np.full(n_intervals, cy),\n",
+ " \"z_end\": -to_d,\n",
+ " \"x_mid\": np.full(n_intervals, cx),\n",
+ " \"y_mid\": np.full(n_intervals, cy),\n",
+ " \"z_mid\": -mid_d,\n",
+ " \"grade\": hole_grade,\n",
+ " }\n",
+ " )\n",
+ " )\n",
+ "\n",
+ "intervals_df = pd.concat(hole_frames, ignore_index=True)\n",
+ "intervals_df[\"hole_id\"] = pd.Categorical(intervals_df[\"hole_id\"])\n",
+ "\n",
+ "downhole = await DownholeIntervals.create(\n",
+ " manager,\n",
+ " DownholeIntervalsData(\n",
+ " name=f\"Cross-Validation Drillholes - {uuid.uuid4()}\",\n",
+ " coordinate_reference_system=EpsgCode(32632),\n",
+ " intervals=intervals_df,\n",
+ " is_composited=True,\n",
+ " depth_unit=\"m\",\n",
+ " ),\n",
+ ")\n",
+ "\n",
+ "downhole"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "14",
+ "metadata": {},
+ "source": [
+ "### Run Leave-One-Drillhole-Out Cross-Validation\n",
+ "\n",
+ "Configure per-drillhole limits on `SearchNeighborhood` (`max_samples_per_drillhole` and `max_drillholes`) and request `num_drillholes` in `KrigingDiagnostics` to verify how many external holes contributed to each interval's estimate."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "15",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from evo.compute.tasks.geostatistics.cross_validation import LeaveOneDrillholeOut\n",
+ "\n",
+ "drillhole_search = SearchNeighborhood(\n",
+ " ellipsoid=Ellipsoid(ranges=EllipsoidRanges(major=300.0, semi_major=300.0, minor=120.0)),\n",
+ " max_samples=16,\n",
+ " min_samples=4,\n",
+ " max_samples_per_drillhole=4,\n",
+ " max_drillholes=4,\n",
+ ")\n",
+ "\n",
+ "drillhole_cv_params = CrossValidationParameters(\n",
+ " source=downhole.attributes[\"grade\"],\n",
+ " validation=LeaveOneDrillholeOut(),\n",
+ " estimator=KrigingEstimator(\n",
+ " variogram=variogram,\n",
+ " neighborhood=drillhole_search,\n",
+ " diagnostics=KrigingDiagnostics(\n",
+ " kriging_variance=True,\n",
+ " num_drillholes=True,\n",
+ " num_samples=True,\n",
+ " ),\n",
+ " ),\n",
+ " outputs=CrossValidationOutputs(estimate=\"dh_cv_est\", error=\"dh_cv_err\"),\n",
+ ")\n",
+ "\n",
+ "drillhole_result = await run(manager, drillhole_cv_params, preview=True)\n",
+ "print(drillhole_result)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "16",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Load interval estimates, errors, and contributing-drillhole counts by hole\n",
+ "dh_df = await drillhole_result.to_dataframe()\n",
+ "dh_df[[\"hole_id\", \"from\", \"to\", \"grade\", \"dh_cv_est\", \"dh_cv_err\", \"KV\", \"NDh\", \"NS\"]].head(10)"
+ ]
+ }
+ ],
+ "metadata": {
+ "language_info": {
+ "name": "python"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/packages/evo-compute/src/evo/compute/tasks/__init__.py b/packages/evo-compute/src/evo/compute/tasks/__init__.py
index a3f860014..c95bfe705 100644
--- a/packages/evo-compute/src/evo/compute/tasks/__init__.py
+++ b/packages/evo-compute/src/evo/compute/tasks/__init__.py
@@ -67,6 +67,9 @@
# Break Ties-specific result types
from .geostatistics.break_ties import BreakTiesResult
+# Cross-Validation result types
+from .geostatistics.cross_validation import CrossValidationResult
+
# Declustering result types
from .geostatistics.declustering import DeclusteringResult
@@ -177,6 +180,7 @@ async def run(
"BlockDiscretization",
"BreakTiesResult",
"CreateAttribute",
+ "CrossValidationResult",
"DeclusteringResult",
"Ellipsoid",
"EllipsoidRanges",
diff --git a/packages/evo-compute/src/evo/compute/tasks/common/results.py b/packages/evo-compute/src/evo/compute/tasks/common/results.py
index d002a6b53..3613d8ed2 100644
--- a/packages/evo-compute/src/evo/compute/tasks/common/results.py
+++ b/packages/evo-compute/src/evo/compute/tasks/common/results.py
@@ -100,7 +100,7 @@ def __str__(self) -> str:
result_type = getattr(self._results[0], "TASK_DISPLAY_NAME", "Task")
lines = [f"✓ {len(self._results)} {result_type} Result(s)"]
for i, result in enumerate(self._results):
- target = getattr(result, "target_name", "?")
- attr = getattr(result, "attribute_name", "?")
+ target = getattr(result, "target_name", None) or getattr(result, "source_name", "?")
+ attr = getattr(result, "attribute_name", None) or getattr(result, "estimate_name", "?")
lines.append(f" {i + 1}. {target} → {attr}")
return "\n".join(lines)
diff --git a/packages/evo-compute/src/evo/compute/tasks/common/search.py b/packages/evo-compute/src/evo/compute/tasks/common/search.py
index 93ff79e25..c1df4c6c0 100644
--- a/packages/evo-compute/src/evo/compute/tasks/common/search.py
+++ b/packages/evo-compute/src/evo/compute/tasks/common/search.py
@@ -150,11 +150,11 @@ class SearchNeighborhood(BaseModel):
The search neighborhood is defined by an ellipsoid (spatial extent and
orientation) and constraints on the number of samples to use.
- Kriging, IDW, KNN and declustering can further limit the samples by octant,
- quadrant and drillhole (``max_samples_per_drillhole`` and ``max_drillholes``).
- Kriging additionally supports ``min_drillholes`` and non-global
- ``drillhole_limit_scope``. The other tasks do not support these limits and
- refuse a neighborhood that sets them.
+ Kriging, IDW, KNN, cross-validation and declustering can further limit the
+ samples by octant, quadrant and drillhole (``max_samples_per_drillhole`` and
+ ``max_drillholes``). Kriging additionally supports ``min_drillholes`` and
+ non-global ``drillhole_limit_scope``. The other tasks do not support these
+ limits and refuse a neighborhood that sets them.
Example::
@@ -350,7 +350,8 @@ def _reject_sector_and_drillhole_limits(neighborhood: SearchNeighborhood) -> Sea
if limits:
raise ValueError(
f"This task does not support {', '.join(limits)}. "
- "Octant, quadrant and drillhole limits are only available for kriging, IDW, KNN and declustering."
+ "Octant, quadrant and drillhole limits are only available for kriging, IDW, KNN, cross-validation "
+ "and declustering."
)
return neighborhood
diff --git a/packages/evo-compute/src/evo/compute/tasks/geostatistics/__init__.py b/packages/evo-compute/src/evo/compute/tasks/geostatistics/__init__.py
index d8896dfd4..2753cc6d5 100644
--- a/packages/evo-compute/src/evo/compute/tasks/geostatistics/__init__.py
+++ b/packages/evo-compute/src/evo/compute/tasks/geostatistics/__init__.py
@@ -16,6 +16,7 @@
- **kriging** — Kriging interpolation
- **knn** — K-nearest neighbour estimation
- **idw** — Inverse distance weighting estimation
+- **cross_validation** — Cross-validation for kriging, KNN, and IDW
- **break_ties** — Spatial tie-breaking
- **conditioned_simulator** — Conditional turning-band simulation
- **conditional_turning_bands** — Conditional turning-band simulation (pre-computed distribution)
@@ -42,6 +43,7 @@
from . import conditional_turning_bands as _conditional_turning_bands_module # noqa: F401
from . import conditioned_simulator as _conditioned_simulator_module # noqa: F401
from . import continuous_distribution as _continuous_distribution_module # noqa: F401
+from . import cross_validation as _cross_validation_module # noqa: F401
from . import declustering as _declustering_module # noqa: F401
from . import idw as _idw_module # noqa: F401
from . import knn as _knn_module # noqa: F401
@@ -53,6 +55,7 @@
from . import simulation_report as _simulation_report_module # noqa: F401
from .break_ties import BreakTiesResult
from .conditional_turning_bands import ConditionalTurningBandsResult
+from .cross_validation import CrossValidationResult
from .declustering import DeclusteringResult
from .idw import IDWResult
from .knn import KNNResult
@@ -68,6 +71,7 @@
"BlockDiscretization",
"BreakTiesResult",
"ConditionalTurningBandsResult",
+ "CrossValidationResult",
"DeclusteringResult",
"Filter",
"IDWResult",
diff --git a/packages/evo-compute/src/evo/compute/tasks/geostatistics/cross_validation.py b/packages/evo-compute/src/evo/compute/tasks/geostatistics/cross_validation.py
new file mode 100644
index 000000000..d85eb14d2
--- /dev/null
+++ b/packages/evo-compute/src/evo/compute/tasks/geostatistics/cross_validation.py
@@ -0,0 +1,907 @@
+# Copyright © 2026 Bentley Systems, Incorporated
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Cross-validation compute task client.
+
+This module provides typed models for running the cross-validation task
+(``geostatistics/cross-validation``). Cross-validation holds samples out of the
+source data, re-estimates them at their own locations from the remaining
+samples, writes the estimates (and optional signed errors and kriging
+diagnostics) back onto the source object, and returns summary statistics.
+
+Two tagged unions select how each run behaves without exposing conditionally
+valid fields:
+
+- ``validation`` (:data:`ValidationStrategy`) — what is held out:
+
+ - :class:`LeaveOneSampleOut` holds out each sample and any coincident samples.
+ - :class:`LeaveOneDrillholeOut` holds out every sample sharing one drillhole
+ ID and requires a :class:`~evo.objects.typed.DownholeIntervals` source.
+
+- ``estimator`` (:data:`CrossValidationEstimator`) — how held-out locations are
+ re-estimated:
+
+ - :class:`KrigingEstimator` — simple or ordinary kriging with a variogram and
+ optional :class:`~evo.compute.tasks.geostatistics.kriging.KrigingDiagnostics`.
+ - :class:`KNNEstimator` — k-nearest-neighbour arithmetic mean.
+ - :class:`IDWEstimator` — inverse-distance weighting with a positive ``power``.
+
+Example — Leave-one-sample-out cross-validation on a pointset::
+
+ >>> from evo.compute.tasks import Ellipsoid, EllipsoidRanges, KrigingDiagnostics, SearchNeighborhood, run
+ >>> from evo.compute.tasks.geostatistics.cross_validation import (
+ ... CrossValidationOutputs,
+ ... CrossValidationParameters,
+ ... KrigingEstimator,
+ ... LeaveOneSampleOut,
+ ... )
+ >>>
+ >>> params = CrossValidationParameters(
+ ... source=pointset.attributes["grade"],
+ ... validation=LeaveOneSampleOut(),
+ ... estimator=KrigingEstimator(
+ ... variogram=variogram,
+ ... neighborhood=SearchNeighborhood(
+ ... ellipsoid=Ellipsoid(ranges=EllipsoidRanges(200, 150, 100)),
+ ... max_samples=20,
+ ... ),
+ ... diagnostics=KrigingDiagnostics(kriging_variance=True),
+ ... ),
+ ... outputs=CrossValidationOutputs(estimate="cv_estimate", error="cv_error"),
+ ... )
+ >>> result = await run(manager, params, preview=True)
+ >>> result.statistics.root_mean_squared_error
+
+Example — Leave-one-drillhole-out cross-validation on downhole intervals::
+
+ >>> from evo.compute.tasks.geostatistics.cross_validation import (
+ ... CrossValidationOutputs,
+ ... CrossValidationParameters,
+ ... IDWEstimator,
+ ... LeaveOneDrillholeOut,
+ ... )
+ >>>
+ >>> params = CrossValidationParameters(
+ ... source=downhole_intervals.attributes["grade"],
+ ... validation=LeaveOneDrillholeOut(),
+ ... estimator=IDWEstimator(
+ ... neighborhood=SearchNeighborhood(
+ ... ellipsoid=Ellipsoid(ranges=EllipsoidRanges(200, 150, 100)),
+ ... max_samples=24,
+ ... max_samples_per_drillhole=4,
+ ... ),
+ ... power=2.0,
+ ... ),
+ ... outputs=CrossValidationOutputs(estimate="idw_cv_estimate", error="idw_cv_error"),
+ ... )
+ >>> result = await run(manager, params, preview=True)
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Annotated, Any, ClassVar, Literal, Protocol, TypeAlias, runtime_checkable
+
+import pandas as pd
+from evo.common import IContext, IFeedback
+from evo.objects import ObjectSchema
+from evo.objects.typed import BaseObject, BlockModel, object_from_reference
+from pydantic import (
+ AliasChoices,
+ BaseModel,
+ BeforeValidator,
+ Field,
+ PrivateAttr,
+ SerializerFunctionWrapHandler,
+ ValidationInfo,
+ ValidatorFunctionWrapHandler,
+ field_validator,
+ model_serializer,
+ model_validator,
+)
+
+from ..common import (
+ CreateAttribute,
+ Filter,
+ GeoscienceObjectReference,
+ SearchNeighborhood,
+ Source,
+ UpdateAttribute,
+ attribute_spec,
+)
+from ..common.results import TaskAttribute
+from ..common.runner import TaskRunner
+from ..common.source_target import AnyTypedAttribute, _source_from_attribute
+from .kriging import (
+ _ATTRIBUTE_TYPES_BY_KIND,
+ KrigingDiagnostics,
+ KrigingDiagnosticsResult,
+ OrdinaryKriging,
+ SimpleKriging,
+ _object_identity,
+)
+
+__all__ = [
+ "CrossValidationEstimator",
+ "CrossValidationOutputs",
+ "CrossValidationParameters",
+ "CrossValidationResult",
+ "CrossValidationResultModel",
+ "CrossValidationRunner",
+ "CrossValidationSource",
+ "CrossValidationSourceResult",
+ "CrossValidationStatistics",
+ "IDWEstimator",
+ "KNNEstimator",
+ "KrigingCrossValidationStatistics",
+ "KrigingEstimator",
+ "LeaveOneDrillholeOut",
+ "LeaveOneSampleOut",
+ "ValidationStrategy",
+]
+
+
+# =============================================================================
+# Validation Strategy Tagged Union
+# =============================================================================
+
+
+class LeaveOneSampleOut(BaseModel):
+ """Hold out each sample and any samples coincident with its location.
+
+ Estimates every selected sample in one pass, excluding the sample's own
+ location (including coincident samples strictly closer than ``1e-8`` world
+ units) before applying neighbour quotas.
+
+ Example::
+
+ >>> validation = LeaveOneSampleOut()
+ """
+
+ model_config = {"extra": "forbid"}
+
+ type: Literal["sample"] = "sample"
+ """Discriminator selecting leave-one-sample-out validation."""
+
+
+class LeaveOneDrillholeOut(BaseModel):
+ """Hold out one drillhole at a time, estimating its samples from the remaining holes.
+
+ Requires a :class:`~evo.objects.typed.DownholeIntervals` source object to
+ supply drillhole IDs. Each query excludes every sample sharing its drillhole
+ ID before neighbour quotas are applied, while keeping samples from other
+ holes eligible.
+
+ Example::
+
+ >>> validation = LeaveOneDrillholeOut()
+ """
+
+ model_config = {"extra": "forbid"}
+
+ type: Literal["drillhole"] = "drillhole"
+ """Discriminator selecting leave-one-drillhole-out validation."""
+
+
+ValidationStrategy: TypeAlias = Annotated[
+ LeaveOneSampleOut | LeaveOneDrillholeOut,
+ Field(discriminator="type"),
+]
+"""Tagged union of supported cross-validation hold-out strategies."""
+
+
+# =============================================================================
+# Estimator Tagged Union
+# =============================================================================
+
+_ALLOWED_NEIGHBORHOOD_KEYS: frozenset[str] = frozenset(
+ {
+ *SearchNeighborhood.model_fields,
+ "max_drillholes_per_estimate",
+ "min_drillholes_per_estimate",
+ }
+)
+
+
+def _validate_cross_validation_neighborhood(value: Any) -> Any:
+ """Reject unknown fields on raw neighborhood mappings before delegating to :class:`SearchNeighborhood`."""
+ if isinstance(value, Mapping):
+ unknown = set(value) - _ALLOWED_NEIGHBORHOOD_KEYS
+ if unknown:
+ raise ValueError(f"Unknown neighborhood field(s): {', '.join(sorted(map(str, unknown)))}.")
+ return value
+
+
+_CrossValidationNeighborhood: TypeAlias = Annotated[
+ SearchNeighborhood,
+ BeforeValidator(_validate_cross_validation_neighborhood),
+]
+
+
+class KrigingEstimator(BaseModel):
+ """Re-estimate held-out locations using simple or ordinary kriging.
+
+ Carries the variogram, kriging method, search neighborhood, and optional
+ per-sample :class:`~evo.compute.tasks.geostatistics.kriging.KrigingDiagnostics`
+ written onto the source object alongside the cross-validated estimate.
+
+ Example::
+
+ >>> from evo.compute.tasks import KrigingDiagnostics, SearchNeighborhood
+ >>> from evo.compute.tasks.geostatistics.kriging import KrigingMethod
+ >>>
+ >>> estimator = KrigingEstimator(
+ ... variogram=variogram,
+ ... neighborhood=SearchNeighborhood(ellipsoid=ellipsoid, max_samples=20),
+ ... kriging_method=KrigingMethod.ORDINARY,
+ ... diagnostics=KrigingDiagnostics(kriging_variance=True, num_samples=True),
+ ... )
+ """
+
+ model_config = {"populate_by_name": True, "extra": "forbid"}
+
+ type: Literal["kriging"] = "kriging"
+ """Discriminator selecting the kriging estimator."""
+
+ variogram: GeoscienceObjectReference
+ """Model of the covariance within the domain (Variogram object or reference URL)."""
+
+ neighborhood: _CrossValidationNeighborhood = Field(validation_alias=AliasChoices("neighborhood", "search"))
+ """Search neighborhood deciding which remaining samples estimate each held-out location."""
+
+ kriging_method: Annotated[SimpleKriging | OrdinaryKriging, Field(discriminator="type")] = Field(
+ default_factory=OrdinaryKriging,
+ validation_alias=AliasChoices("kriging_method", "method"),
+ )
+ """The kriging method to use. Defaults to ordinary kriging."""
+
+ diagnostics: KrigingDiagnostics | None = None
+ """Optional per-sample kriging diagnostic attributes to write onto the source object."""
+
+ @property
+ def search(self) -> SearchNeighborhood:
+ """Backwards-compatible alias for :attr:`neighborhood`."""
+ return self.neighborhood
+
+ @property
+ def method(self) -> SimpleKriging | OrdinaryKriging:
+ """Backwards-compatible alias for :attr:`kriging_method`."""
+ return self.kriging_method
+
+ @model_serializer(mode="wrap")
+ def _serialize(self, handler: SerializerFunctionWrapHandler) -> dict[str, Any]:
+ result = handler(self)
+ if self.diagnostics is None:
+ result.pop("diagnostics", None)
+ else:
+ result["diagnostics"] = self.diagnostics.model_dump(mode="json", exclude_none=True)
+ return result
+
+
+class KNNEstimator(BaseModel):
+ """Re-estimate held-out locations with the arithmetic mean of their nearest neighbours.
+
+ Example::
+
+ >>> estimator = KNNEstimator(
+ ... neighborhood=SearchNeighborhood(ellipsoid=ellipsoid, max_samples=12),
+ ... )
+ """
+
+ model_config = {"populate_by_name": True, "extra": "forbid"}
+
+ type: Literal["knn"] = "knn"
+ """Discriminator selecting the k-nearest-neighbour estimator."""
+
+ neighborhood: _CrossValidationNeighborhood = Field(validation_alias=AliasChoices("neighborhood", "search"))
+ """Search neighborhood deciding which remaining samples estimate each held-out location."""
+
+ @property
+ def search(self) -> SearchNeighborhood:
+ """Backwards-compatible alias for :attr:`neighborhood`."""
+ return self.neighborhood
+
+
+class IDWEstimator(BaseModel):
+ """Re-estimate held-out locations using inverse-distance weighting.
+
+ Example::
+
+ >>> estimator = IDWEstimator(
+ ... neighborhood=SearchNeighborhood(ellipsoid=ellipsoid, max_samples=20),
+ ... power=2.0,
+ ... )
+ """
+
+ model_config = {"populate_by_name": True, "extra": "forbid"}
+
+ type: Literal["idw"] = "idw"
+ """Discriminator selecting the inverse-distance-weighting estimator."""
+
+ neighborhood: _CrossValidationNeighborhood = Field(validation_alias=AliasChoices("neighborhood", "search"))
+ """Search neighborhood deciding which remaining samples estimate each held-out location."""
+
+ power: float = Field(gt=0.0, allow_inf_nan=False)
+ """Distance-weighting exponent (must be strictly positive, e.g. ``1.0`` or ``2.0``)."""
+
+ @property
+ def search(self) -> SearchNeighborhood:
+ """Backwards-compatible alias for :attr:`neighborhood`."""
+ return self.neighborhood
+
+ @field_validator("power", mode="before")
+ @classmethod
+ def _reject_boolean_power(cls, value: Any) -> Any:
+ if isinstance(value, bool):
+ raise ValueError("power must be a positive number, not a boolean.")
+ return value
+
+
+CrossValidationEstimator: TypeAlias = Annotated[
+ KrigingEstimator | KNNEstimator | IDWEstimator,
+ Field(discriminator="type"),
+]
+"""Tagged union of supported cross-validation estimators."""
+
+
+# =============================================================================
+# Source & Output Specifications
+# =============================================================================
+
+
+def _claim_cross_validation_attribute(claimed: dict[str, str], attribute: str, output: str) -> None:
+ """Record that ``output`` writes to ``attribute``, raising if another output already does."""
+ if attribute in claimed:
+ raise ValueError(
+ f"{claimed[attribute]} and {output} both write to the attribute {attribute!r}. "
+ "Every cross-validation output needs its own attribute."
+ )
+ claimed[attribute] = output
+
+
+def _validate_attribute_spec_mapping(value: Any) -> Any:
+ """Reject extra keys on raw attribute-operation dicts so invalid combinations fail fast."""
+ if isinstance(value, dict):
+ operation = value.get("operation")
+ allowed = {"operation", "name"} if operation == "create" else {"operation", "reference"}
+ if operation in ("create", "update"):
+ unknown = set(value) - allowed
+ if unknown:
+ raise ValueError(f"Operation {operation!r} does not accept field(s): {', '.join(sorted(unknown))}.")
+ return value
+
+
+class CrossValidationSource(Source):
+ """The samples to cross-validate and the attribute holding their known values.
+
+ Can be constructed explicitly or converted automatically from a typed
+ attribute such as ``pointset.attributes["grade"]`` or
+ ``downhole_intervals.attributes["grade"]``.
+ """
+
+ model_config = {"extra": "forbid"}
+
+ filter: Filter | None = None
+ """Optional filter restricting which source locations are cross-validated and used as neighbours."""
+
+ @model_serializer(mode="wrap")
+ def _serialize(self, handler: SerializerFunctionWrapHandler) -> dict[str, Any]:
+ result = handler(self)
+ if self.filter is None:
+ result.pop("filter", None)
+ else:
+ result["filter"] = self.filter.model_dump(mode="json", exclude_none=True)
+ return result
+
+
+def _convert_cross_validation_source(value: Any) -> Any:
+ """Convert a typed attribute or :class:`Source` into a :class:`CrossValidationSource`."""
+ if isinstance(value, CrossValidationSource):
+ return value
+ converted = _source_from_attribute(value)
+ if isinstance(converted, Source) and not isinstance(converted, CrossValidationSource):
+ return CrossValidationSource(object=converted.object, attribute=converted.attribute)
+ return converted
+
+
+class CrossValidationOutputs(BaseModel):
+ """Per-sample attributes written back onto the source object.
+
+ Both ``estimate`` and ``error`` accept:
+
+ - a ``str`` — create a new attribute with that name.
+ - a typed attribute from the source object — update it if it already exists
+ (must be a floating-point attribute), otherwise create it.
+ - a :class:`~evo.compute.tasks.common.CreateAttribute` or
+ :class:`~evo.compute.tasks.common.UpdateAttribute` for explicit control.
+
+ Samples that produced no valid estimate carry ``NaN`` in the written
+ ``estimate`` and ``error`` attributes. The ``error`` attribute stores the
+ signed error ``estimate - true``, so a positive value is an overestimate.
+
+ Example::
+
+ >>> outputs = CrossValidationOutputs(
+ ... estimate="cv_estimate",
+ ... error="cv_error",
+ ... )
+ """
+
+ model_config = {"extra": "forbid"}
+
+ _source_objects: dict[str, str] = PrivateAttr(default_factory=dict)
+ """The object each typed attribute came from, checked against the cross-validation source."""
+
+ _attribute_names: dict[str, str] = PrivateAttr(default_factory=dict)
+ """The name of each typed attribute, which an update reference does not carry."""
+
+ estimate: Annotated[CreateAttribute | UpdateAttribute, Field(discriminator="operation")]
+ """Attribute to create or update on the source object with each sample's cross-validated estimate."""
+
+ error: Annotated[CreateAttribute | UpdateAttribute, Field(discriminator="operation")] | None = None
+ """Optional attribute to create or update with the signed error (``estimate - true``)."""
+
+ @field_validator("estimate", "error", mode="before")
+ @classmethod
+ def _resolve_attribute(cls, value: Any, info: ValidationInfo) -> Any:
+ if isinstance(value, str):
+ return CreateAttribute(name=value)
+ if isinstance(value, AnyTypedAttribute):
+ if value.exists and value.attribute_type not in _ATTRIBUTE_TYPES_BY_KIND["floating-point"]:
+ raise ValueError(
+ f"Output {info.field_name!r} writes floating-point values, so it cannot update {value.name!r}, "
+ f"which is a {value.attribute_type} attribute. Pass a name to create a new attribute instead."
+ )
+ return attribute_spec(value)
+ return _validate_attribute_spec_mapping(value)
+
+ @model_validator(mode="wrap")
+ @classmethod
+ def _remember_typed_attributes_and_check_duplicates(
+ cls, data: Any, handler: ValidatorFunctionWrapHandler
+ ) -> CrossValidationOutputs:
+ names: dict[str, str] = {}
+ sources: dict[str, str] = {}
+ if isinstance(data, dict):
+ for field, value in data.items():
+ if isinstance(value, AnyTypedAttribute):
+ names[field] = value.name
+ if value._obj is not None:
+ sources[field] = str(value._obj.metadata.url)
+
+ outputs = handler(data)
+ outputs._attribute_names.update(names)
+ outputs._source_objects.update(sources)
+
+ if outputs.error is not None:
+ claimed_names: dict[str, str] = {}
+ claimed_references: dict[str, str] = {}
+ for field in ("estimate", "error"):
+ spec = getattr(outputs, field)
+ label = f"output {field!r}"
+ name = spec.name if isinstance(spec, CreateAttribute) else outputs._attribute_names.get(field)
+ if name is not None:
+ _claim_cross_validation_attribute(claimed_names, name, label)
+ if isinstance(spec, UpdateAttribute):
+ _claim_cross_validation_attribute(claimed_references, spec.reference, label)
+
+ return outputs
+
+ @model_serializer(mode="wrap")
+ def _serialize(self, handler: SerializerFunctionWrapHandler) -> dict[str, Any]:
+ result = handler(self)
+ if self.error is None:
+ result.pop("error", None)
+ return result
+
+
+# =============================================================================
+# Cross-Validation Parameters
+# =============================================================================
+
+
+class CrossValidationParameters(BaseModel):
+ """Parameters for the ``geostatistics/cross-validation`` compute task.
+
+ Example::
+
+ >>> from evo.compute.tasks import Filter, FilterCondition, KrigingDiagnostics, SearchNeighborhood, run
+ >>> from evo.compute.tasks.geostatistics.cross_validation import (
+ ... CrossValidationOutputs,
+ ... CrossValidationParameters,
+ ... KrigingEstimator,
+ ... LeaveOneSampleOut,
+ ... )
+ >>>
+ >>> params = CrossValidationParameters(
+ ... source=pointset.attributes["Cu_pct"],
+ ... source_filter=Filter(
+ ... where=FilterCondition(
+ ... attribute=pointset.attributes["domain"],
+ ... operator="in",
+ ... values=["Early Diorite"],
+ ... ),
+ ... ),
+ ... validation=LeaveOneSampleOut(),
+ ... estimator=KrigingEstimator(
+ ... variogram=variogram,
+ ... neighborhood=SearchNeighborhood(ellipsoid=ellipsoid, max_samples=24),
+ ... diagnostics=KrigingDiagnostics(kriging_variance=True, slope_of_regression=True),
+ ... ),
+ ... outputs=CrossValidationOutputs(estimate="Cu_cv_est", error="Cu_cv_err"),
+ ... )
+ >>> result = await run(manager, params, preview=True)
+ """
+
+ model_config = {"populate_by_name": True, "extra": "forbid"}
+
+ source: Annotated[CrossValidationSource, BeforeValidator(_convert_cross_validation_source)]
+ """Source object and attribute containing the known sample values to cross-validate."""
+
+ validation: ValidationStrategy
+ """Hold-out strategy (:class:`LeaveOneSampleOut` or :class:`LeaveOneDrillholeOut`)."""
+
+ estimator: CrossValidationEstimator
+ """Estimator configuration (:class:`KrigingEstimator`, :class:`KNNEstimator`, or :class:`IDWEstimator`)."""
+
+ outputs: CrossValidationOutputs
+ """Per-sample output attributes to write back onto the source object."""
+
+ source_filter: Filter | None = Field(None, exclude=True)
+ """Optional filter restricting cross-validation to a subset of the source samples.
+
+ Excluded from top-level serialization and injected into ``source["filter"]``.
+ """
+
+ @model_validator(mode="after")
+ def _validate_cross_validation_outputs(self) -> CrossValidationParameters:
+ if self.source.filter is not None and self.source_filter is not None:
+ raise ValueError("Specify a source filter either on 'source.filter' or via 'source_filter', not both.")
+
+ source_object = _object_identity(self.source.object)
+ for field, attr_source in self.outputs._source_objects.items():
+ if _object_identity(attr_source) != source_object:
+ raise ValueError(
+ f"Output {field!r} references an attribute of a different object than the cross-validation "
+ f"source. Outputs are written onto the source object, {source_object}."
+ )
+
+ diagnostics = self.estimator.diagnostics if isinstance(self.estimator, KrigingEstimator) else None
+ if diagnostics is not None:
+ for field, attr_source in diagnostics._source_objects.items():
+ if _object_identity(attr_source) != source_object:
+ raise ValueError(
+ f"Diagnostic {field!r} references an attribute of a different object than the "
+ f"cross-validation source. Diagnostics are written onto the source object, {source_object}."
+ )
+
+ outputs_to_check: list[tuple[str, CreateAttribute | UpdateAttribute, str | None]] = [
+ ("output 'estimate'", self.outputs.estimate, self.outputs._attribute_names.get("estimate")),
+ ]
+ if self.outputs.error is not None:
+ outputs_to_check.append(
+ ("output 'error'", self.outputs.error, self.outputs._attribute_names.get("error")),
+ )
+ if diagnostics is not None:
+ outputs_to_check.extend(
+ (f"diagnostic {field!r}", spec, diagnostics._attribute_names.get(field))
+ for field in KrigingDiagnostics.model_fields
+ if (spec := getattr(diagnostics, field)) is not None
+ )
+
+ claimed_names: dict[str, str] = {}
+ claimed_references: dict[str, str] = {}
+ for label, spec, known_name in outputs_to_check:
+ name = spec.name if isinstance(spec, CreateAttribute) else known_name
+ if name is not None:
+ _claim_cross_validation_attribute(claimed_names, name, label)
+ if isinstance(spec, UpdateAttribute):
+ _claim_cross_validation_attribute(claimed_references, spec.reference, label)
+
+ return self
+
+ @model_serializer(mode="wrap")
+ def _serialize(self, handler: SerializerFunctionWrapHandler) -> dict[str, Any]:
+ result = handler(self)
+ if self.source_filter is not None:
+ result["source"]["filter"] = self.source_filter.model_dump(mode="json", exclude_none=True)
+ return result
+
+
+# =============================================================================
+# Cross-Validation Result Types
+# =============================================================================
+
+
+@runtime_checkable
+class _ObjToDataframeProtocol(Protocol):
+ async def to_dataframe(self, *keys: str, fb: IFeedback = ...) -> pd.DataFrame: ...
+
+
+class CrossValidationStatistics(BaseModel):
+ """Summary statistics comparing held-out true values with their estimates.
+
+ Statistics are computed over samples that produced a valid estimate
+ (``valid_count``). Samples without a valid estimate are counted in
+ ``invalid_count``, carry ``NaN`` in the written attributes, and are excluded
+ from the summary statistics. Any statistic that is undefined for the
+ available valid samples (such as ``correlation`` when fewer than two samples
+ are valid or variance is zero) is ``None``.
+ """
+
+ model_config = {"extra": "forbid"}
+
+ evaluated_count: int
+ """Number of samples cross-validated after applying any source filter."""
+
+ valid_count: int
+ """Number of cross-validated samples that produced a finite estimate."""
+
+ invalid_count: int
+ """Number of cross-validated samples that produced no estimate."""
+
+ mean_true: float | None
+ """Mean of the held-out true values over the valid samples."""
+
+ mean_estimate: float | None
+ """Mean of the cross-validated estimates over the valid samples."""
+
+ variance_true: float | None
+ """Population variance of the held-out true values over the valid samples."""
+
+ variance_estimate: float | None
+ """Population variance of the cross-validated estimates over the valid samples."""
+
+ mean_error: float | None
+ """Mean of ``estimate - true``. Positive values indicate overestimation bias."""
+
+ mean_absolute_error: float | None
+ """Mean of ``|estimate - true|``."""
+
+ mean_squared_error: float | None
+ """Mean of ``(estimate - true) ** 2``."""
+
+ root_mean_squared_error: float | None
+ """Square root of ``mean_squared_error``, in the units of the estimated attribute."""
+
+ error_variance: float | None
+ """Population variance of ``estimate - true``."""
+
+ correlation: float | None
+ """Pearson correlation coefficient between true values and estimates, or ``None`` when undefined."""
+
+ regression_slope: float | None
+ """Slope of true values regressed on estimates, or ``None`` when undefined."""
+
+ regression_intercept: float | None
+ """Intercept of true values regressed on estimates, or ``None`` when ``regression_slope`` is ``None``."""
+
+
+class KrigingCrossValidationStatistics(BaseModel):
+ """Standardized error summary statistics returned for kriging cross-validation only.
+
+ Computed over valid samples that also have a positive kriging variance
+ (``standardized_count``). Absent (``None`` on the result) for KNN and IDW.
+ """
+
+ model_config = {"extra": "forbid"}
+
+ standardized_count: int
+ """Number of valid samples with a positive kriging variance."""
+
+ mean_kriging_variance: float | None
+ """Mean kriging variance over the standardized samples, or ``None`` when ``standardized_count == 0``."""
+
+ mean_standardized_error: float | None
+ """Mean of ``(estimate - true) / sqrt(kriging_variance)``, or ``None`` when ``standardized_count == 0``."""
+
+ standardized_error_variance: float | None
+ """Population variance of the standardized error, or ``None`` when ``standardized_count == 0``."""
+
+
+class CrossValidationSourceResult(BaseModel):
+ """The source object updated with the per-sample cross-validation attributes."""
+
+ model_config = {"extra": "forbid"}
+
+ reference: str
+ """Reference URL to the updated source geoscience object."""
+
+ name: str
+ """Name of the source geoscience object."""
+
+ description: str | None = None
+ """Optional description of the source geoscience object."""
+
+ schema_id: str
+ """Schema identifier of the source geoscience object."""
+
+ estimate: TaskAttribute
+ """Attribute written with each sample's cross-validated estimate."""
+
+ error: TaskAttribute | None = None
+ """Attribute written with each sample's signed error, when requested."""
+
+ diagnostics: KrigingDiagnosticsResult | None = None
+ """Kriging diagnostic attributes written alongside the estimate, when requested."""
+
+
+class CrossValidationResultModel(BaseModel):
+ """Pydantic model for the raw cross-validation task result payload."""
+
+ model_config = {"extra": "forbid"}
+
+ message: str
+ """A message describing what happened in the task."""
+
+ source: CrossValidationSourceResult
+ """The source object updated with the cross-validation output attributes."""
+
+ statistics: CrossValidationStatistics
+ """Summary statistics comparing held-out true values with their estimates."""
+
+ kriging_statistics: KrigingCrossValidationStatistics | None = None
+ """Standardized kriging statistics (present for kriging only; ``None`` for KNN and IDW)."""
+
+
+class CrossValidationResult:
+ """Rich result object for the cross-validation task.
+
+ Provides typed access to the updated source object, output attributes,
+ kriging diagnostics, common summary statistics, and kriging-only
+ standardized error statistics.
+ """
+
+ TASK_DISPLAY_NAME: ClassVar[str] = "Cross-Validation"
+
+ def __init__(self, context: IContext, model: CrossValidationResultModel) -> None:
+ self._context = context
+ self._message = model.message
+ self._source = model.source
+ self._statistics = model.statistics
+ self._kriging_statistics = model.kriging_statistics
+
+ @property
+ def message(self) -> str:
+ """A message describing what happened in the task."""
+ return self._message
+
+ @property
+ def source(self) -> CrossValidationSourceResult:
+ """Metadata and written attribute references for the updated source object."""
+ return self._source
+
+ @property
+ def source_name(self) -> str:
+ """The name of the source object updated with cross-validation attributes."""
+ return self._source.name
+
+ @property
+ def source_reference(self) -> str:
+ """Reference URL to the updated source object."""
+ return self._source.reference
+
+ @property
+ def estimate_attribute(self) -> TaskAttribute:
+ """The attribute containing each sample's cross-validated estimate."""
+ return self._source.estimate
+
+ @property
+ def estimate_name(self) -> str:
+ """The name of the attribute containing each sample's cross-validated estimate."""
+ return self._source.estimate.name
+
+ @property
+ def error_attribute(self) -> TaskAttribute | None:
+ """The attribute containing each sample's signed error, or ``None`` if not requested."""
+ return self._source.error
+
+ @property
+ def error_name(self) -> str | None:
+ """The name of the signed-error attribute, or ``None`` if not requested."""
+ if self._source.error is None:
+ return None
+ return self._source.error.name
+
+ @property
+ def diagnostics(self) -> dict[str, TaskAttribute]:
+ """The kriging diagnostic attributes that were written, keyed by diagnostic name.
+
+ Empty when no diagnostics were requested or when the estimator is KNN or IDW.
+ """
+ diagnostics = self._source.diagnostics
+ if diagnostics is None:
+ return {}
+ return {
+ name: attribute
+ for name in type(diagnostics).model_fields
+ if (attribute := getattr(diagnostics, name)) is not None
+ }
+
+ @property
+ def statistics(self) -> CrossValidationStatistics:
+ """Summary statistics comparing held-out true values with their estimates."""
+ return self._statistics
+
+ @property
+ def kriging_statistics(self) -> KrigingCrossValidationStatistics | None:
+ """Kriging standardized error statistics, or ``None`` for KNN and IDW."""
+ return self._kriging_statistics
+
+ @property
+ def schema(self) -> ObjectSchema:
+ """The schema type of the source object (e.g., ``'pointset'`` or ``'downhole-intervals'``)."""
+ return ObjectSchema.from_id(self._source.schema_id)
+
+ async def get_source_object(self) -> BaseObject:
+ """Load and return the updated source geoscience object."""
+ return await object_from_reference(self._context, self._source.reference)
+
+ async def to_dataframe(self, *columns: str) -> pd.DataFrame:
+ """Load the updated source object and return its data as a DataFrame.
+
+ Args:
+ *columns: Optional column names to select. If omitted, returns all columns.
+
+ Returns:
+ A pandas DataFrame containing the source data and written cross-validation attributes.
+
+ Raises:
+ TypeError: If the source object type does not support DataFrame export.
+ """
+ source_obj = await self.get_source_object()
+ if isinstance(source_obj, BlockModel):
+ return await source_obj.to_dataframe(columns=list(columns) if columns else None)
+ if isinstance(source_obj, _ObjToDataframeProtocol):
+ return await source_obj.to_dataframe(*columns)
+ raise TypeError(
+ f"Don't know how to get DataFrame from {type(source_obj).__name__}. "
+ "Use get_source_object() and access the data manually."
+ )
+
+ def __str__(self) -> str:
+ lines = [
+ f"✓ {self.TASK_DISPLAY_NAME} Result",
+ f" Message: {self.message}",
+ f" Source: {self.source_name}",
+ f" Estimate: {self.estimate_name}",
+ ]
+ if self.error_name is not None:
+ lines.append(f" Error: {self.error_name}")
+ if diagnostics := self.diagnostics:
+ lines.append(f" Diagnostics: {', '.join(a.name for a in diagnostics.values())}")
+ stats = self._statistics
+ lines.append(f" Samples: {stats.valid_count}/{stats.evaluated_count} valid ({stats.invalid_count} invalid)")
+ if stats.root_mean_squared_error is not None:
+ lines.append(f" RMSE: {stats.root_mean_squared_error:.4f}")
+ return "\n".join(lines)
+
+
+# =============================================================================
+# Task Runner
+# =============================================================================
+
+
+class CrossValidationRunner(
+ TaskRunner[CrossValidationParameters, CrossValidationResultModel, CrossValidationResult],
+ topic="geostatistics",
+ task="cross-validation",
+):
+ """Runner for cross-validation compute tasks.
+
+ Automatically registered — used by :func:`~evo.compute.tasks.run` for
+ dispatch, or directly::
+
+ result = await CrossValidationRunner(context, params, preview=True)
+ """
+
+ async def _get_result(self, raw_result: CrossValidationResultModel) -> CrossValidationResult:
+ return CrossValidationResult(self._context, raw_result)
diff --git a/packages/evo-compute/src/evo/compute/tasks/geostatistics/kriging.py b/packages/evo-compute/src/evo/compute/tasks/geostatistics/kriging.py
index fb03cefe3..812f11099 100644
--- a/packages/evo-compute/src/evo/compute/tasks/geostatistics/kriging.py
+++ b/packages/evo-compute/src/evo/compute/tasks/geostatistics/kriging.py
@@ -103,6 +103,8 @@ class SimpleKriging(BaseModel):
>>> method = SimpleKriging(mean=100.0)
"""
+ model_config = {"extra": "forbid"}
+
type: Literal["simple"] = "simple"
"""The method type discriminator."""
@@ -117,6 +119,8 @@ class OrdinaryKriging(BaseModel):
This is the default kriging method if none is specified.
"""
+ model_config = {"extra": "forbid"}
+
type: Literal["ordinary"] = "ordinary"
"""The method type discriminator."""
diff --git a/packages/evo-compute/tests/geostatistics/test_cross_validation_tasks.py b/packages/evo-compute/tests/geostatistics/test_cross_validation_tasks.py
new file mode 100644
index 000000000..57b116081
--- /dev/null
+++ b/packages/evo-compute/tests/geostatistics/test_cross_validation_tasks.py
@@ -0,0 +1,1043 @@
+# Copyright © 2026 Bentley Systems, Incorporated
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Contract and unit tests for the cross-validation compute task SDK client."""
+
+from __future__ import annotations
+
+import ast
+import math
+import re
+import unittest
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import nbformat
+import numpy as np
+import pandas as pd
+from evo.objects import ObjectReference
+from evo.objects.typed import BlockModel
+from evo.objects.typed.attributes import (
+ Attribute,
+ BlockModelAttribute,
+ BlockModelPendingAttribute,
+ PendingAttribute,
+)
+from pydantic import ValidationError
+
+from evo.compute.tasks import (
+ AllOfFilter,
+ AnyOfFilter,
+ BlockDiscretization,
+ CreateAttribute,
+ Ellipsoid,
+ EllipsoidRanges,
+ Filter,
+ FilterCondition,
+ KrigingDiagnostics,
+ Rotation,
+ SearchNeighborhood,
+ Source,
+ Target,
+ TaskResultList,
+ UpdateAttribute,
+ run,
+)
+from evo.compute.tasks import (
+ CrossValidationResult as TopLevelCrossValidationResult,
+)
+from evo.compute.tasks.common.results import TaskAttribute
+from evo.compute.tasks.common.runner import TaskRegistry
+from evo.compute.tasks.geostatistics import CrossValidationResult as TopicCrossValidationResult
+from evo.compute.tasks.geostatistics.cross_validation import (
+ CrossValidationOutputs,
+ CrossValidationParameters,
+ CrossValidationResult,
+ CrossValidationResultModel,
+ CrossValidationRunner,
+ CrossValidationSource,
+ CrossValidationSourceResult,
+ CrossValidationStatistics,
+ IDWEstimator,
+ KNNEstimator,
+ KrigingCrossValidationStatistics,
+ KrigingEstimator,
+ LeaveOneDrillholeOut,
+ LeaveOneSampleOut,
+)
+from evo.compute.tasks.geostatistics.kriging import (
+ KrigingDiagnosticsResult,
+ KrigingMethod,
+ SimpleKriging,
+)
+
+# ---------------------------------------------------------------------------
+# Test helpers
+# ---------------------------------------------------------------------------
+
+_BASE = "https://hub.test.evo.bentley.com"
+_ORG = "00000000-0000-0000-0000-000000000001"
+_WS = "00000000-0000-0000-0000-000000000002"
+
+
+def _obj_url(obj_id: str = "00000000-0000-0000-0000-000000000003") -> str:
+ return f"{_BASE}/geoscience-object/orgs/{_ORG}/workspaces/{_WS}/objects/{obj_id}"
+
+
+POINTSET_URL = _obj_url("00000000-0000-0000-0000-000000000010")
+DOWNHOLE_URL = _obj_url("00000000-0000-0000-0000-000000000020")
+VARIOGRAM_URL = _obj_url("00000000-0000-0000-0000-000000000030")
+OTHER_URL = _obj_url("00000000-0000-0000-0000-000000000040")
+
+
+def _search(**kwargs) -> SearchNeighborhood:
+ defaults = dict(
+ ellipsoid=Ellipsoid(
+ ranges=EllipsoidRanges(major=200.0, semi_major=150.0, minor=100.0),
+ rotation=Rotation(dip_azimuth=15.0, dip=70.0, pitch=0.0),
+ ),
+ max_samples=20,
+ )
+ defaults.update(kwargs)
+ return SearchNeighborhood(**defaults)
+
+
+def _create_mock_attribute(
+ name: str,
+ key: str,
+ object_url: str = POINTSET_URL,
+ schema_path: str = "locations.attributes",
+ attribute_type: str = "scalar",
+) -> MagicMock:
+ attr = MagicMock(spec=Attribute)
+ attr.name = name
+ attr.key = key
+ attr.exists = True
+ attr.attribute_type = attribute_type
+
+ mock_context = MagicMock()
+ mock_context.schema_path = schema_path
+ attr._context = mock_context
+
+ mock_obj = MagicMock()
+ mock_obj.metadata.url = ObjectReference(object_url)
+ attr._obj = mock_obj
+ return attr
+
+
+def _create_pending_attribute(name: str, object_url: str | None = POINTSET_URL) -> PendingAttribute:
+ mock_parent = MagicMock()
+ if object_url is not None:
+ mock_obj = MagicMock()
+ mock_obj.metadata.url = ObjectReference(object_url)
+ mock_parent._obj = mock_obj
+ else:
+ mock_parent._obj = None
+ return PendingAttribute(mock_parent, name)
+
+
+def _dump(params: CrossValidationParameters) -> dict:
+ return params.model_dump(mode="json", by_alias=True, exclude_none=True)
+
+
+def _make_statistics(**overrides) -> CrossValidationStatistics:
+ values = dict(
+ evaluated_count=50,
+ valid_count=48,
+ invalid_count=2,
+ mean_true=1.25,
+ mean_estimate=1.22,
+ variance_true=0.64,
+ variance_estimate=0.49,
+ mean_error=-0.03,
+ mean_absolute_error=0.18,
+ mean_squared_error=0.0625,
+ root_mean_squared_error=0.25,
+ error_variance=0.0616,
+ correlation=0.88,
+ regression_slope=0.96,
+ regression_intercept=0.0788,
+ )
+ values.update(overrides)
+ return CrossValidationStatistics(**values)
+
+
+def _make_kriging_statistics(**overrides) -> KrigingCrossValidationStatistics:
+ values = dict(
+ standardized_count=48,
+ mean_kriging_variance=0.065,
+ mean_standardized_error=-0.04,
+ standardized_error_variance=0.97,
+ )
+ values.update(overrides)
+ return KrigingCrossValidationStatistics(**values)
+
+
+def _make_result_model(
+ *,
+ with_error: bool = True,
+ with_diagnostics: bool = False,
+ with_kriging_stats: bool = False,
+ schema_id: str = "/objects/pointset/1.2.0/pointset.schema.json",
+ source_url: str = POINTSET_URL,
+ source_name: str = "WP comps",
+ statistics: CrossValidationStatistics | None = None,
+ kriging_statistics: KrigingCrossValidationStatistics | None = None,
+) -> CrossValidationResultModel:
+ diagnostics = (
+ KrigingDiagnosticsResult(
+ kriging_variance=TaskAttribute(reference="locations.attributes[?key=='kv']", name="KV"),
+ num_samples=TaskAttribute(reference="locations.attributes[?key=='ns']", name="NS"),
+ )
+ if with_diagnostics
+ else None
+ )
+ return CrossValidationResultModel(
+ message="Cross-validation completed: 48 of 50 samples produced an estimate.",
+ source=CrossValidationSourceResult(
+ reference=source_url,
+ name=source_name,
+ description="Composited samples",
+ schema_id=schema_id,
+ estimate=TaskAttribute(reference="locations.attributes[?key=='est']", name="cv_estimate"),
+ error=(
+ TaskAttribute(reference="locations.attributes[?key=='err']", name="cv_error") if with_error else None
+ ),
+ diagnostics=diagnostics,
+ ),
+ statistics=statistics or _make_statistics(),
+ kriging_statistics=kriging_statistics
+ if kriging_statistics is not None
+ else (_make_kriging_statistics() if with_kriging_stats else None),
+ )
+
+
+# ---------------------------------------------------------------------------
+# Registration & Public Surface
+# ---------------------------------------------------------------------------
+
+
+class TestCrossValidationRegistration(unittest.TestCase):
+ def test_runner_registered(self):
+ self.assertIs(TaskRegistry().get_runner(CrossValidationParameters), CrossValidationRunner)
+
+ def test_topic_and_task(self):
+ self.assertEqual(CrossValidationRunner.topic, "geostatistics")
+ self.assertEqual(CrossValidationRunner.task, "cross-validation")
+
+ def test_runner_generic_types(self):
+ self.assertIs(CrossValidationRunner.params_type, CrossValidationParameters)
+ self.assertIs(CrossValidationRunner.result_model_type, CrossValidationResultModel)
+ self.assertIs(CrossValidationRunner.result_type, CrossValidationResult)
+
+ def test_result_reexported_at_package_levels(self):
+ self.assertIs(TopLevelCrossValidationResult, CrossValidationResult)
+ self.assertIs(TopicCrossValidationResult, CrossValidationResult)
+
+
+# ---------------------------------------------------------------------------
+# Tagged Union Contract Tests: Validation & Estimator Branches
+# ---------------------------------------------------------------------------
+
+
+class TestCrossValidationTaggedUnions(unittest.TestCase):
+ """Verify all six (validation × estimator) branches and reject invalid combinations."""
+
+ def test_all_six_validation_and_estimator_branches_serialize_to_openapi_contract(self):
+ validations = [
+ ("sample", LeaveOneSampleOut(), POINTSET_URL, "locations.attributes[?key=='cu']"),
+ ("drillhole", LeaveOneDrillholeOut(), DOWNHOLE_URL, "attributes[?key=='cu']"),
+ ]
+ estimators = [
+ (
+ "kriging",
+ KrigingEstimator(
+ variogram=VARIOGRAM_URL,
+ neighborhood=_search(min_samples=3),
+ kriging_method=KrigingMethod.ORDINARY,
+ diagnostics=KrigingDiagnostics(kriging_variance=True),
+ ),
+ ),
+ (
+ "knn",
+ KNNEstimator(neighborhood=_search()),
+ ),
+ (
+ "idw",
+ IDWEstimator(neighborhood=_search(), power=2.0),
+ ),
+ ]
+
+ for expected_val_type, validation, source_url, attr_expr in validations:
+ for expected_est_type, estimator in estimators:
+ with self.subTest(validation=expected_val_type, estimator=expected_est_type):
+ params = CrossValidationParameters(
+ source=Source(object=source_url, attribute=attr_expr),
+ validation=validation,
+ estimator=estimator,
+ outputs=CrossValidationOutputs(estimate="cv_est", error="cv_err"),
+ )
+ payload = _dump(params)
+
+ self.assertEqual(set(payload), {"source", "validation", "estimator", "outputs"})
+ self.assertEqual(payload["source"], {"object": source_url, "attribute": attr_expr})
+ self.assertEqual(payload["validation"], {"type": expected_val_type})
+ self.assertEqual(payload["estimator"]["type"], expected_est_type)
+ self.assertEqual(
+ payload["outputs"],
+ {
+ "estimate": {"operation": "create", "name": "cv_est"},
+ "error": {"operation": "create", "name": "cv_err"},
+ },
+ )
+
+ if expected_est_type == "kriging":
+ self.assertEqual(
+ set(payload["estimator"]),
+ {"type", "variogram", "neighborhood", "kriging_method", "diagnostics"},
+ )
+ self.assertEqual(payload["estimator"]["kriging_method"], {"type": "ordinary"})
+ self.assertEqual(
+ payload["estimator"]["diagnostics"],
+ {"kriging_variance": {"operation": "create", "name": "KV"}},
+ )
+ elif expected_est_type == "knn":
+ self.assertEqual(set(payload["estimator"]), {"type", "neighborhood"})
+ else:
+ self.assertEqual(set(payload["estimator"]), {"type", "neighborhood", "power"})
+ self.assertEqual(payload["estimator"]["power"], 2.0)
+
+ # Round-trip wire payload back through CrossValidationParameters
+ round_tripped = CrossValidationParameters.model_validate(payload)
+ self.assertEqual(_dump(round_tripped), payload)
+
+ def test_simple_kriging_branch_and_method_search_aliases(self):
+ search = _search()
+ params = CrossValidationParameters(
+ source=Source(object=POINTSET_URL, attribute="locations.attributes[?key=='cu']"),
+ validation={"type": "sample"},
+ estimator=KrigingEstimator(
+ variogram=VARIOGRAM_URL,
+ search=search,
+ method=KrigingMethod.simple(mean=1.45),
+ ),
+ outputs=CrossValidationOutputs(estimate="cv_est"),
+ )
+ self.assertIsInstance(params.validation, LeaveOneSampleOut)
+ self.assertIsInstance(params.estimator, KrigingEstimator)
+ self.assertIsInstance(params.estimator.kriging_method, SimpleKriging)
+ self.assertIs(params.estimator.search, params.estimator.neighborhood)
+ self.assertIs(params.estimator.method, params.estimator.kriging_method)
+ self.assertIs(KNNEstimator(search=search).search, search)
+ self.assertIs(IDWEstimator(search=search, power=2.0).search, search)
+
+ payload = _dump(params)
+ self.assertEqual(payload["estimator"]["kriging_method"], {"type": "simple", "mean": 1.45})
+ self.assertNotIn("diagnostics", payload["estimator"])
+ self.assertNotIn("error", payload["outputs"])
+ # Plain model_dump without exclude_none also omits None diagnostics and error
+ plain = params.model_dump(mode="json")
+ self.assertNotIn("diagnostics", plain["estimator"])
+ self.assertNotIn("error", plain["outputs"])
+ self.assertNotIn("filter", plain["source"])
+
+ def test_neighborhood_drillhole_and_sector_limits_serialize_to_openapi_names(self):
+ search = _search(
+ min_samples=4,
+ max_empty_octants=3,
+ max_samples_per_octant=3,
+ max_empty_quadrants=1,
+ max_samples_per_quadrant=5,
+ max_samples_per_drillhole=4,
+ max_drillholes=6,
+ min_drillholes=2,
+ drillhole_limit_scope="octant",
+ )
+ for estimator in (
+ KrigingEstimator(variogram=VARIOGRAM_URL, neighborhood=search),
+ KNNEstimator(neighborhood=search),
+ IDWEstimator(neighborhood=search, power=1.5),
+ ):
+ with self.subTest(estimator=estimator.type):
+ params = CrossValidationParameters(
+ source=Source(object=DOWNHOLE_URL, attribute="attributes[?key=='cu']"),
+ validation=LeaveOneDrillholeOut(),
+ estimator=estimator,
+ outputs=CrossValidationOutputs(estimate="cv_est"),
+ )
+ payload = _dump(params)
+ nbr = payload["estimator"]["neighborhood"]
+ self.assertEqual(nbr["min_samples"], 4)
+ self.assertEqual(nbr["max_empty_octants"], 3)
+ self.assertEqual(nbr["max_samples_per_octant"], 3)
+ self.assertEqual(nbr["max_empty_quadrants"], 1)
+ self.assertEqual(nbr["max_samples_per_quadrant"], 5)
+ self.assertEqual(nbr["max_samples_per_drillhole"], 4)
+ self.assertEqual(nbr["max_drillholes"], 6)
+ self.assertEqual(nbr["min_drillholes"], 2)
+ self.assertEqual(nbr["drillhole_limit_scope"], "octant")
+ self.assertNotIn("max_drillholes_per_estimate", nbr)
+ self.assertNotIn("min_drillholes_per_estimate", nbr)
+
+ # Round-trip wire payload carrying canonical drillhole properties
+ reloaded = CrossValidationParameters.model_validate(payload)
+ self.assertEqual(reloaded.estimator.neighborhood.max_drillholes, 6)
+ self.assertEqual(reloaded.estimator.neighborhood.max_drillholes_per_estimate, 6)
+ self.assertEqual(reloaded.estimator.neighborhood.min_drillholes, 2)
+ self.assertEqual(reloaded.estimator.neighborhood.drillhole_limit_scope, "octant")
+ self.assertEqual(_dump(reloaded), payload)
+
+ # Backwards-compatible legacy drillhole aliases also serialize to canonical OpenAPI names
+ legacy_search = _search(
+ max_drillholes_per_estimate=5, min_drillholes_per_estimate=0, drillhole_limit_scope="global"
+ )
+ legacy_payload = _dump(
+ CrossValidationParameters(
+ source=Source(object=DOWNHOLE_URL, attribute="attributes[?key=='cu']"),
+ validation=LeaveOneDrillholeOut(),
+ estimator=KNNEstimator(neighborhood=legacy_search),
+ outputs=CrossValidationOutputs(estimate="cv_est"),
+ )
+ )
+ legacy_nbr = legacy_payload["estimator"]["neighborhood"]
+ self.assertEqual(legacy_nbr["max_drillholes"], 5)
+ self.assertNotIn("max_drillholes_per_estimate", legacy_nbr)
+ self.assertNotIn("min_drillholes", legacy_nbr)
+ self.assertNotIn("drillhole_limit_scope", legacy_nbr)
+
+ def test_validation_rejects_invalid_strategies_and_arbitrary_groups(self):
+ base = dict(
+ source={"object": POINTSET_URL, "attribute": "locations.attributes[?key=='cu']"},
+ estimator={"type": "knn", "neighborhood": _search().model_dump()},
+ outputs={"estimate": {"operation": "create", "name": "cv_est"}},
+ )
+ invalid_validations = [
+ ("missing-type", {}),
+ ("unknown-k-fold", {"type": "k_fold", "folds": 5}),
+ ("arbitrary-group", {"type": "group", "samples": [0, 1, 2]}),
+ ("sample-subset", {"type": "sample", "samples": [0, 5]}),
+ ("single-selected-hole", {"type": "drillhole", "drillhole_id": "DH001"}),
+ ("multiple-holes", {"type": "drillhole", "drillhole_ids": ["DH001", "DH002"]}),
+ ]
+ for label, invalid_validation in invalid_validations:
+ with self.subTest(case=label), self.assertRaises(ValidationError):
+ CrossValidationParameters.model_validate({**base, "validation": invalid_validation})
+
+ def test_estimator_rejects_cross_branch_and_invalid_combinations(self):
+ nbr = _search().model_dump()
+ base = dict(
+ source={"object": POINTSET_URL, "attribute": "locations.attributes[?key=='cu']"},
+ validation={"type": "sample"},
+ outputs={"estimate": {"operation": "create", "name": "cv_est"}},
+ )
+ invalid_estimators = [
+ ("missing-type", {"neighborhood": nbr}),
+ ("unknown-type", {"type": "rbf", "neighborhood": nbr}),
+ ("knn-with-power", {"type": "knn", "neighborhood": nbr, "power": 2.0}),
+ ("knn-with-variogram", {"type": "knn", "neighborhood": nbr, "variogram": VARIOGRAM_URL}),
+ ("knn-with-diagnostics", {"type": "knn", "neighborhood": nbr, "diagnostics": {}}),
+ ("knn-with-kriging-method", {"type": "knn", "neighborhood": nbr, "kriging_method": {"type": "ordinary"}}),
+ ("idw-without-power", {"type": "idw", "neighborhood": nbr}),
+ ("idw-zero-power", {"type": "idw", "neighborhood": nbr, "power": 0.0}),
+ ("idw-negative-power", {"type": "idw", "neighborhood": nbr, "power": -2.0}),
+ ("idw-nan-power", {"type": "idw", "neighborhood": nbr, "power": math.nan}),
+ ("idw-inf-power", {"type": "idw", "neighborhood": nbr, "power": math.inf}),
+ ("idw-bool-power", {"type": "idw", "neighborhood": nbr, "power": True}),
+ ("idw-with-variogram", {"type": "idw", "neighborhood": nbr, "power": 2.0, "variogram": VARIOGRAM_URL}),
+ ("idw-with-diagnostics", {"type": "idw", "neighborhood": nbr, "power": 2.0, "diagnostics": {}}),
+ (
+ "idw-with-kriging-method",
+ {"type": "idw", "neighborhood": nbr, "power": 2.0, "kriging_method": {"type": "ordinary"}},
+ ),
+ ("kriging-without-variogram", {"type": "kriging", "neighborhood": nbr}),
+ (
+ "kriging-with-power",
+ {"type": "kriging", "variogram": VARIOGRAM_URL, "neighborhood": nbr, "power": 2.0},
+ ),
+ (
+ "ordinary-kriging-with-mean",
+ {
+ "type": "kriging",
+ "variogram": VARIOGRAM_URL,
+ "neighborhood": nbr,
+ "kriging_method": {"type": "ordinary", "mean": 1.0},
+ },
+ ),
+ (
+ "simple-kriging-without-mean",
+ {
+ "type": "kriging",
+ "variogram": VARIOGRAM_URL,
+ "neighborhood": nbr,
+ "kriging_method": {"type": "simple"},
+ },
+ ),
+ (
+ "unknown-kriging-method",
+ {
+ "type": "kriging",
+ "variogram": VARIOGRAM_URL,
+ "neighborhood": nbr,
+ "kriging_method": {"type": "universal"},
+ },
+ ),
+ ]
+ for label, invalid_estimator in invalid_estimators:
+ with self.subTest(case=label), self.assertRaises(ValidationError):
+ CrossValidationParameters.model_validate({**base, "estimator": invalid_estimator})
+
+ def test_top_level_rejects_flattened_estimator_or_target_fields(self):
+ base = dict(
+ source=Source(object=POINTSET_URL, attribute="locations.attributes[?key=='cu']"),
+ validation=LeaveOneSampleOut(),
+ estimator=KNNEstimator(neighborhood=_search()),
+ outputs=CrossValidationOutputs(estimate="cv_est"),
+ )
+ flattened_extras = [
+ ("target", Target.new_attribute(POINTSET_URL, "cv_est")),
+ ("target_filter", Filter(where=FilterCondition(attribute="dom", operator="in", values=["A"]))),
+ ("block_discretization", BlockDiscretization(nx=2, ny=2, nz=2)),
+ ("variogram", VARIOGRAM_URL),
+ ("power", 2.0),
+ ("diagnostics", KrigingDiagnostics(kriging_variance=True)),
+ ]
+ for key, value in flattened_extras:
+ with self.subTest(extra_field=key), self.assertRaises(ValidationError):
+ CrossValidationParameters(**base, **{key: value})
+
+ def test_neighborhood_mapping_validation_rejects_unknown_or_conflicting_fields(self):
+ valid_ellipsoid = _search().ellipsoid.to_dict()
+ bad_neighborhoods = [
+ ("unknown-key", {"ellipsoid": valid_ellipsoid, "max_samples": 10, "k": 5}),
+ (
+ "conflicting-max-drillholes",
+ {
+ "ellipsoid": valid_ellipsoid,
+ "max_samples": 10,
+ "max_drillholes": 3,
+ "max_drillholes_per_estimate": 4,
+ },
+ ),
+ (
+ "conflicting-min-drillholes",
+ {
+ "ellipsoid": valid_ellipsoid,
+ "max_samples": 10,
+ "min_drillholes": 2,
+ "min_drillholes_per_estimate": 3,
+ },
+ ),
+ ("zero-max-drillholes", {"ellipsoid": valid_ellipsoid, "max_samples": 10, "max_drillholes": 0}),
+ ("unknown-ellipsoid-key", {"ellipsoid": {**valid_ellipsoid, "extra": 1}, "max_samples": 10}),
+ ("missing-ellipsoid-ranges", {"ellipsoid": {"rotation": valid_ellipsoid["rotation"]}, "max_samples": 10}),
+ ("incomplete-ranges", {"ellipsoid": {"ellipsoid_ranges": {"major": 100}}, "max_samples": 10}),
+ (
+ "unknown-rotation-key",
+ {
+ "ellipsoid": {
+ "ellipsoid_ranges": valid_ellipsoid["ellipsoid_ranges"],
+ "rotation": {"dip": 10, "roll": 5},
+ },
+ "max_samples": 10,
+ },
+ ),
+ (
+ "out-of-bounds-rotation",
+ {
+ "ellipsoid": {
+ "ellipsoid_ranges": valid_ellipsoid["ellipsoid_ranges"],
+ "rotation": {"dip": 200},
+ },
+ "max_samples": 10,
+ },
+ ),
+ ]
+ for label, bad_nbr in bad_neighborhoods:
+ with self.subTest(case=label), self.assertRaises(ValidationError):
+ KNNEstimator.model_validate({"type": "knn", "neighborhood": bad_nbr})
+
+ def test_ellipsoid_mapping_without_or_partial_rotation_defaults_cleanly(self):
+ est = KNNEstimator.model_validate(
+ {
+ "type": "knn",
+ "neighborhood": {
+ "ellipsoid": {"ellipsoid_ranges": {"major": 100.0, "semi_major": 80.0, "minor": 50.0}},
+ "max_samples": 10,
+ },
+ }
+ )
+ self.assertEqual(est.neighborhood.ellipsoid.rotation, Rotation(0.0, 0.0, 0.0))
+
+ partial_rot = KNNEstimator.model_validate(
+ {
+ "type": "knn",
+ "neighborhood": {
+ "ellipsoid": {
+ "ellipsoid_ranges": {"major": 100.0, "semi_major": 80.0, "minor": 50.0},
+ "rotation": {"dip": 25.0},
+ },
+ "max_samples": 10,
+ },
+ }
+ )
+ self.assertEqual(partial_rot.neighborhood.ellipsoid.rotation, Rotation(0.0, 25.0, 0.0))
+
+
+# ---------------------------------------------------------------------------
+# Source, Filter, Outputs, & Diagnostics Validation
+# ---------------------------------------------------------------------------
+
+
+class TestCrossValidationSourceAndOutputs(unittest.TestCase):
+ def test_typed_pointset_and_downhole_attributes_convert_to_source(self):
+ ps_attr = _create_mock_attribute("Cu_pct", "cu-key", POINTSET_URL, schema_path="locations.attributes")
+ dh_attr = _create_mock_attribute("Cu_pct", "dh-cu-key", DOWNHOLE_URL, schema_path="attributes")
+
+ ps_params = CrossValidationParameters(
+ source=ps_attr,
+ validation=LeaveOneSampleOut(),
+ estimator=KNNEstimator(neighborhood=_search()),
+ outputs=CrossValidationOutputs(estimate="cv_est"),
+ )
+ dh_params = CrossValidationParameters(
+ source=dh_attr,
+ validation=LeaveOneDrillholeOut(),
+ estimator=KNNEstimator(neighborhood=_search()),
+ outputs=CrossValidationOutputs(estimate="cv_est"),
+ )
+
+ self.assertEqual(
+ _dump(ps_params)["source"],
+ {"object": POINTSET_URL, "attribute": "locations.attributes[?key=='cu-key']"},
+ )
+ self.assertEqual(
+ _dump(dh_params)["source"],
+ {"object": DOWNHOLE_URL, "attribute": "attributes[?key=='dh-cu-key']"},
+ )
+
+ def test_pending_source_attribute_is_rejected(self):
+ pending = _create_pending_attribute("missing_grade")
+ with self.assertRaisesRegex(ValidationError, "does not exist"):
+ CrossValidationParameters(
+ source=pending,
+ validation=LeaveOneSampleOut(),
+ estimator=KNNEstimator(neighborhood=_search()),
+ outputs=CrossValidationOutputs(estimate="cv_est"),
+ )
+
+ def test_source_rejects_unknown_extra_fields(self):
+ with self.assertRaises(ValidationError):
+ CrossValidationParameters.model_validate(
+ {
+ "source": {"object": POINTSET_URL, "attribute": "grade", "unexpected": True},
+ "validation": {"type": "sample"},
+ "estimator": {"type": "knn", "neighborhood": _search().model_dump()},
+ "outputs": {"estimate": {"operation": "create", "name": "cv_est"}},
+ }
+ )
+
+ def test_source_filter_injected_into_source_and_composite_filters_supported(self):
+ domain_attr = _create_mock_attribute("domain", "dom-key", POINTSET_URL, attribute_type="category")
+ grade_attr = _create_mock_attribute("grade", "grd-key", POINTSET_URL, attribute_type="scalar")
+
+ source_filter = Filter(
+ where=AllOfFilter(
+ filters=[
+ FilterCondition(attribute=domain_attr, operator="in", values=["LMS1", "LMS2"]),
+ AnyOfFilter(
+ filters=[
+ FilterCondition(attribute=grade_attr, operator="greater_than", threshold=0.2),
+ FilterCondition(attribute=grade_attr, operator="equal", threshold=0.0),
+ ]
+ ),
+ ]
+ )
+ )
+ params = CrossValidationParameters(
+ source=grade_attr,
+ source_filter=source_filter,
+ validation=LeaveOneSampleOut(),
+ estimator=KNNEstimator(neighborhood=_search()),
+ outputs=CrossValidationOutputs(estimate="cv_est"),
+ )
+ payload = _dump(params)
+ self.assertNotIn("source_filter", payload)
+ self.assertEqual(payload["source"]["filter"]["where"]["type"], "all_of")
+ self.assertNotIn("threshold", payload["source"]["filter"]["where"]["filters"][0])
+
+ def test_both_source_filter_and_nested_source_filter_rejected(self):
+ f = Filter(where=FilterCondition(attribute="domain", operator="in", values=["A"]))
+ with self.assertRaisesRegex(ValidationError, "not both"):
+ CrossValidationParameters(
+ source=CrossValidationSource(object=POINTSET_URL, attribute="grade", filter=f),
+ source_filter=f,
+ validation=LeaveOneSampleOut(),
+ estimator=KNNEstimator(neighborhood=_search()),
+ outputs=CrossValidationOutputs(estimate="cv_est"),
+ )
+
+ def test_outputs_accept_strings_typed_attributes_and_explicit_specs(self):
+ existing_est = _create_mock_attribute("cv_est", "est-key", POINTSET_URL, attribute_type="scalar")
+ pending_err = _create_pending_attribute("cv_err", POINTSET_URL)
+
+ outputs = CrossValidationOutputs(estimate=existing_est, error=pending_err)
+ self.assertEqual(outputs.estimate, UpdateAttribute(reference="locations.attributes[?key=='est-key']"))
+ self.assertEqual(outputs.error, CreateAttribute(name="cv_err"))
+
+ mock_bm = MagicMock()
+ mock_bm.metadata.url = ObjectReference(POINTSET_URL)
+ bm_est = BlockModelAttribute(name="bm_est", attribute_type="Float64", obj=mock_bm)
+ bm_err = BlockModelPendingAttribute(obj=mock_bm, name="bm_err")
+ bm_outputs = CrossValidationOutputs(estimate=bm_est, error=bm_err)
+ self.assertEqual(bm_outputs.estimate, UpdateAttribute(reference="attributes[?name=='bm_est']"))
+ self.assertEqual(bm_outputs.error, CreateAttribute(name="bm_err"))
+
+ def test_outputs_reject_non_floating_point_existing_attributes(self):
+ for field in ("estimate", "error"):
+ for bad_type in ("bool", "integer", "category"):
+ with self.subTest(field=field, attribute_type=bad_type):
+ bad_attr = _create_mock_attribute("flag", "flag-key", POINTSET_URL, attribute_type=bad_type)
+ kwargs = {"estimate": "cv_est", field: bad_attr}
+ with self.assertRaisesRegex(ValidationError, f"Output {field!r} writes floating-point values"):
+ CrossValidationOutputs(**kwargs)
+
+ def test_outputs_reject_invalid_attribute_operation_mappings(self):
+ invalid_specs = [
+ {"operation": "create", "name": "cv_est", "reference": "locations.attributes[0]"},
+ {"operation": "update", "reference": "locations.attributes[0]", "name": "cv_est"},
+ {"operation": "delete", "name": "cv_est"},
+ ]
+ for spec in invalid_specs:
+ with self.subTest(spec=spec), self.assertRaises(ValidationError):
+ CrossValidationOutputs.model_validate({"estimate": spec})
+
+ def test_outputs_and_diagnostics_must_belong_to_source_object(self):
+ wrong_attr = _create_mock_attribute("other_col", "other-key", OTHER_URL)
+
+ with self.assertRaisesRegex(ValidationError, "Output 'estimate' references an attribute of a different object"):
+ CrossValidationParameters(
+ source=Source(object=POINTSET_URL, attribute="grade"),
+ validation=LeaveOneSampleOut(),
+ estimator=KNNEstimator(neighborhood=_search()),
+ outputs=CrossValidationOutputs(estimate=wrong_attr),
+ )
+
+ with self.assertRaisesRegex(ValidationError, "Output 'error' references an attribute of a different object"):
+ CrossValidationParameters(
+ source=Source(object=POINTSET_URL, attribute="grade"),
+ validation=LeaveOneSampleOut(),
+ estimator=KNNEstimator(neighborhood=_search()),
+ outputs=CrossValidationOutputs(estimate="cv_est", error=wrong_attr),
+ )
+
+ with self.assertRaisesRegex(
+ ValidationError, "Diagnostic 'kriging_variance' references an attribute of a different object"
+ ):
+ CrossValidationParameters(
+ source=Source(object=POINTSET_URL, attribute="grade"),
+ validation=LeaveOneSampleOut(),
+ estimator=KrigingEstimator(
+ variogram=VARIOGRAM_URL,
+ neighborhood=_search(),
+ diagnostics=KrigingDiagnostics(kriging_variance=wrong_attr),
+ ),
+ outputs=CrossValidationOutputs(estimate="cv_est"),
+ )
+
+ def test_version_query_string_ignored_when_matching_source_object(self):
+ attr_without_version = _create_mock_attribute("cv_est", "est-key", POINTSET_URL)
+ params = CrossValidationParameters(
+ source=Source(object=f"{POINTSET_URL}?version=123", attribute="grade"),
+ validation=LeaveOneSampleOut(),
+ estimator=KNNEstimator(neighborhood=_search()),
+ outputs=CrossValidationOutputs(estimate=attr_without_version),
+ )
+ self.assertEqual(
+ _dump(params)["outputs"]["estimate"],
+ {"operation": "update", "reference": "locations.attributes[?key=='est-key']"},
+ )
+
+ def test_duplicate_output_and_diagnostic_attributes_rejected(self):
+ with self.assertRaisesRegex(ValidationError, "output 'estimate' and output 'error'"):
+ CrossValidationOutputs(estimate="same_col", error="same_col")
+
+ ref = "locations.attributes[?key=='same']"
+ with self.assertRaisesRegex(ValidationError, "output 'estimate' and output 'error'"):
+ CrossValidationOutputs(
+ estimate=UpdateAttribute(reference=ref),
+ error=UpdateAttribute(reference=ref),
+ )
+
+ with self.assertRaisesRegex(ValidationError, "output 'estimate' and diagnostic 'kriging_variance'"):
+ CrossValidationParameters(
+ source=Source(object=POINTSET_URL, attribute="grade"),
+ validation=LeaveOneSampleOut(),
+ estimator=KrigingEstimator(
+ variogram=VARIOGRAM_URL,
+ neighborhood=_search(),
+ diagnostics=KrigingDiagnostics(kriging_variance=True),
+ ),
+ outputs=CrossValidationOutputs(estimate="KV"),
+ )
+
+ with self.assertRaisesRegex(ValidationError, "output 'error' and diagnostic 'num_samples'"):
+ CrossValidationParameters(
+ source=Source(object=POINTSET_URL, attribute="grade"),
+ validation=LeaveOneSampleOut(),
+ estimator=KrigingEstimator(
+ variogram=VARIOGRAM_URL,
+ neighborhood=_search(),
+ diagnostics=KrigingDiagnostics(num_samples=True),
+ ),
+ outputs=CrossValidationOutputs(estimate="cv_est", error="NS"),
+ )
+
+ typed_kv = _create_mock_attribute("KV", "kv-key", POINTSET_URL)
+ with self.assertRaisesRegex(ValidationError, "output 'estimate' and diagnostic 'kriging_variance'"):
+ CrossValidationParameters(
+ source=Source(object=POINTSET_URL, attribute="grade"),
+ validation=LeaveOneSampleOut(),
+ estimator=KrigingEstimator(
+ variogram=VARIOGRAM_URL,
+ neighborhood=_search(),
+ diagnostics=KrigingDiagnostics(
+ kriging_variance=UpdateAttribute(reference="locations.attributes[?key=='kv-key']")
+ ),
+ ),
+ outputs=CrossValidationOutputs(estimate=typed_kv),
+ )
+
+
+# ---------------------------------------------------------------------------
+# Result Contract, Null/Invalid Behavior, & DataFrame Loading
+# ---------------------------------------------------------------------------
+
+
+class TestCrossValidationResults(unittest.IsolatedAsyncioTestCase):
+ def test_common_and_kriging_results_expose_all_contract_fields(self):
+ model = _make_result_model(with_error=True, with_diagnostics=True, with_kriging_stats=True)
+ result = CrossValidationResult(MagicMock(), model)
+
+ self.assertEqual(result.message, "Cross-validation completed: 48 of 50 samples produced an estimate.")
+ self.assertIs(result.source, model.source)
+ self.assertEqual(result.source_name, "WP comps")
+ self.assertEqual(result.source_reference, POINTSET_URL)
+ self.assertEqual(result.estimate_name, "cv_estimate")
+ self.assertEqual(result.estimate_attribute.name, "cv_estimate")
+ self.assertEqual(result.error_name, "cv_error")
+ self.assertIsNotNone(result.error_attribute)
+ self.assertEqual(
+ {k: v.name for k, v in result.diagnostics.items()}, {"kriging_variance": "KV", "num_samples": "NS"}
+ )
+ self.assertEqual(result.schema.sub_classification, "pointset")
+ self.assertEqual(result.statistics.evaluated_count, 50)
+ self.assertEqual(result.statistics.valid_count, 48)
+ self.assertEqual(result.statistics.invalid_count, 2)
+ self.assertAlmostEqual(result.statistics.root_mean_squared_error, 0.25)
+ self.assertIsNotNone(result.kriging_statistics)
+ self.assertEqual(result.kriging_statistics.standardized_count, 48)
+ self.assertAlmostEqual(result.kriging_statistics.standardized_error_variance, 0.97)
+
+ rendered = str(result)
+ self.assertIn("Cross-Validation Result", rendered)
+ self.assertIn("WP comps", rendered)
+ self.assertIn("cv_estimate", rendered)
+ self.assertIn("cv_error", rendered)
+ self.assertIn("KV, NS", rendered)
+ self.assertIn("48/50 valid (2 invalid)", rendered)
+ self.assertIn("0.2500", rendered)
+
+ def test_knn_and_idw_results_omit_optional_error_diagnostics_and_kriging_stats(self):
+ model = _make_result_model(
+ with_error=False,
+ with_diagnostics=False,
+ with_kriging_stats=False,
+ schema_id="/objects/downhole-intervals/1.3.0/downhole-intervals.schema.json",
+ source_url=DOWNHOLE_URL,
+ source_name="Drillholes",
+ )
+ result = CrossValidationResult(MagicMock(), model)
+
+ self.assertIsNone(result.error_attribute)
+ self.assertIsNone(result.error_name)
+ self.assertEqual(result.diagnostics, {})
+ self.assertIsNone(result.kriging_statistics)
+ self.assertEqual(result.schema.sub_classification, "downhole-intervals")
+
+ rendered = str(result)
+ self.assertNotIn("Error:", rendered)
+ self.assertNotIn("Diagnostics:", rendered)
+
+ def test_null_statistics_and_zero_standardized_samples_preserved(self):
+ """Single valid sample or zero-variance estimates produce null correlation/regression and null kriging stats."""
+ stats = _make_statistics(
+ evaluated_count=10,
+ valid_count=1,
+ invalid_count=9,
+ variance_true=0.0,
+ variance_estimate=0.0,
+ correlation=None,
+ regression_slope=None,
+ regression_intercept=None,
+ root_mean_squared_error=None,
+ )
+ kriging_stats = KrigingCrossValidationStatistics(
+ standardized_count=0,
+ mean_kriging_variance=None,
+ mean_standardized_error=None,
+ standardized_error_variance=None,
+ )
+ payload = _make_result_model(
+ with_error=False,
+ statistics=stats,
+ kriging_statistics=kriging_stats,
+ ).model_dump(mode="json")
+
+ parsed = CrossValidationResultModel.model_validate(payload)
+ result = CrossValidationResult(MagicMock(), parsed)
+
+ self.assertEqual(result.statistics.evaluated_count, 10)
+ self.assertEqual(result.statistics.valid_count, 1)
+ self.assertEqual(result.statistics.invalid_count, 9)
+ self.assertIsNone(result.statistics.correlation)
+ self.assertIsNone(result.statistics.regression_slope)
+ self.assertIsNone(result.statistics.regression_intercept)
+ self.assertIsNone(result.statistics.root_mean_squared_error)
+ self.assertEqual(result.kriging_statistics.standardized_count, 0)
+ self.assertIsNone(result.kriging_statistics.mean_kriging_variance)
+ self.assertIsNone(result.kriging_statistics.mean_standardized_error)
+ self.assertIsNone(result.kriging_statistics.standardized_error_variance)
+ self.assertNotIn("RMSE:", str(result))
+
+ def test_result_models_reject_unexpected_or_missing_fields(self):
+ valid_payload = _make_result_model().model_dump(mode="json")
+ with self.assertRaises(ValidationError):
+ CrossValidationResultModel.model_validate({**valid_payload, "extra_field": 1})
+
+ missing_stat = dict(valid_payload["statistics"])
+ missing_stat.pop("correlation")
+ with self.assertRaises(ValidationError):
+ CrossValidationResultModel.model_validate({**valid_payload, "statistics": missing_stat})
+
+ def test_task_result_list_renders_cross_validation_source_and_estimate(self):
+ r1 = CrossValidationResult(MagicMock(), _make_result_model())
+ result_list = TaskResultList([r1])
+ self.assertIn("WP comps → cv_estimate", str(result_list))
+
+ async def test_to_dataframe_preserves_nan_estimates_for_spatial_and_block_model_sources(self):
+ ctx = MagicMock()
+ result = CrossValidationResult(ctx, _make_result_model())
+ expected_df = pd.DataFrame({"grade": [1.2, 0.8], "cv_estimate": [1.1, np.nan], "cv_error": [-0.1, np.nan]})
+
+ spatial_obj = MagicMock()
+ spatial_obj.to_dataframe = AsyncMock(return_value=expected_df)
+ with patch(
+ "evo.compute.tasks.geostatistics.cross_validation.object_from_reference",
+ new_callable=AsyncMock,
+ return_value=spatial_obj,
+ ) as mock_load:
+ df = await result.to_dataframe("grade", "cv_estimate", "cv_error")
+
+ mock_load.assert_awaited_once_with(ctx, POINTSET_URL)
+ spatial_obj.to_dataframe.assert_awaited_once_with("grade", "cv_estimate", "cv_error")
+ self.assertTrue(math.isnan(df.loc[1, "cv_estimate"]))
+
+ bm_obj = MagicMock(spec=BlockModel)
+ bm_obj.to_dataframe = AsyncMock(return_value=expected_df)
+ with patch(
+ "evo.compute.tasks.geostatistics.cross_validation.object_from_reference",
+ new_callable=AsyncMock,
+ return_value=bm_obj,
+ ):
+ await result.to_dataframe("grade", "cv_estimate")
+ bm_obj.to_dataframe.assert_awaited_once_with(columns=["grade", "cv_estimate"])
+
+ with patch(
+ "evo.compute.tasks.geostatistics.cross_validation.object_from_reference",
+ new_callable=AsyncMock,
+ return_value=object(),
+ ):
+ with self.assertRaisesRegex(TypeError, "Don't know how to get DataFrame"):
+ await result.to_dataframe()
+
+
+# ---------------------------------------------------------------------------
+# Async Runner & tasks.run Integration
+# ---------------------------------------------------------------------------
+
+
+class TestCrossValidationRunnerAsync(unittest.IsolatedAsyncioTestCase):
+ def _make_context(self) -> MagicMock:
+ ctx = MagicMock()
+ ctx.get_connector.return_value = MagicMock()
+ ctx.get_org_id.return_value = _ORG
+ return ctx
+
+ async def test_runner_and_unified_run_submit_expected_payload(self):
+ ctx = self._make_context()
+ params = CrossValidationParameters(
+ source=Source(object=POINTSET_URL, attribute="locations.attributes[?key=='cu']"),
+ validation=LeaveOneSampleOut(),
+ estimator=IDWEstimator(neighborhood=_search(), power=2.0),
+ outputs=CrossValidationOutputs(estimate="cv_estimate", error="cv_error"),
+ )
+ job = AsyncMock()
+ job.wait_for_results.return_value = _make_result_model()
+
+ with patch(
+ "evo.compute.tasks.common.runner.JobClient.submit",
+ new_callable=AsyncMock,
+ return_value=job,
+ ) as mock_submit:
+ result = await run(ctx, params, preview=True)
+
+ mock_submit.assert_awaited_once()
+ _, kwargs = mock_submit.call_args
+ self.assertEqual(kwargs["topic"], "geostatistics")
+ self.assertEqual(kwargs["task"], "cross-validation")
+ self.assertIs(kwargs["result_type"], CrossValidationResultModel)
+ self.assertTrue(kwargs["preview"])
+ self.assertEqual(kwargs["parameters"], _dump(params))
+ self.assertIsInstance(result, CrossValidationResult)
+
+
+# ---------------------------------------------------------------------------
+# Example Notebook Validation
+# ---------------------------------------------------------------------------
+
+
+class TestCrossValidationExampleNotebook(unittest.TestCase):
+ NOTEBOOK_PATH = Path(__file__).resolve().parents[2] / "docs" / "examples" / "cross_validation.ipynb"
+
+ def test_notebook_valid_syntax_clean_outputs_and_no_client_ids(self):
+ nb = nbformat.read(str(self.NOTEBOOK_PATH), as_version=4)
+ nbformat.validate(nb)
+
+ code_cells = [c for c in nb.cells if c.cell_type == "code"]
+ self.assertGreaterEqual(len(code_cells), 8)
+
+ full_source = "\n".join(c.source for c in code_cells)
+ self.assertIn("LeaveOneSampleOut", full_source)
+ self.assertIn("LeaveOneDrillholeOut", full_source)
+ self.assertIn("KrigingEstimator", full_source)
+ self.assertIn("IDWEstimator", full_source)
+ self.assertIn("KNNEstimator", full_source)
+ self.assertIsNone(re.search(r"native-[A-Za-z0-9]{12,}", full_source))
+
+ for cell in code_cells:
+ self.assertEqual(cell.outputs, [])
+ self.assertIsNone(cell.execution_count)
+ filtered_lines = [line for line in cell.source.splitlines() if not line.strip().startswith("%")]
+ ast.parse("\n".join(filtered_lines), mode="exec", feature_version=(3, 10))
+
+
+if __name__ == "__main__":
+ unittest.main()
From 001c8aec8b72b7a00938fb98edb16a41f3cd5bb9 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
<41898282+github-actions[bot]@users.noreply.github.com>
Date: Wed, 18 Nov 2026 16:02:52 +0000
Subject: [PATCH 2/2] Update to MkDocs documentation
---
.../typed-objects/report/ReportCell.md | 4 +
.../typed-objects/report/ReportCellStatus.md | 4 +
.../CrossValidationEstimator.md | 4 +
.../CrossValidationOutputs.md | 4 +
.../CrossValidationParameters.md | 4 +
.../cross-validation/CrossValidationResult.md | 4 +
.../CrossValidationResultModel.md | 4 +
.../cross-validation/CrossValidationRunner.md | 4 +
.../cross-validation/CrossValidationSource.md | 4 +
.../CrossValidationSourceResult.md | 4 +
.../CrossValidationStatistics.md | 4 +
.../cross-validation/IDWEstimator.md | 4 +
.../cross-validation/KNNEstimator.md | 4 +
.../KrigingCrossValidationStatistics.md | 4 +
.../cross-validation/KrigingEstimator.md | 4 +
.../cross-validation/LeaveOneDrillholeOut.md | 4 +
.../cross-validation/LeaveOneSampleOut.md | 4 +
.../cross-validation/ValidationStrategy.md | 4 +
.../kriging/KrigingDiagnostics.md | 4 +
.../kriging/KrigingDiagnosticsResult.md | 4 +
.../kriging/KrigingTargetResult.md | 4 +
.../kriging/RECOMMENDED_DIAGNOSTIC_NAMES.md | 4 +
.../source-target/attribute_spec.md | 4 +
.../typed-objects/report/ReportCell.html | 213 +++++++
.../report/ReportCellStatus.html | 199 +++++++
.../continuous-distribution/UpperTail.html | 2 +-
.../CrossValidationEstimator.html | 147 +++++
.../CrossValidationOutputs.html | 228 ++++++++
.../CrossValidationParameters.html | 300 ++++++++++
.../CrossValidationResult.html | 461 ++++++++++++++++
.../CrossValidationResultModel.html | 251 +++++++++
.../CrossValidationRunner.html | 175 ++++++
.../CrossValidationSource.html | 194 +++++++
.../CrossValidationSourceResult.html | 311 +++++++++++
.../CrossValidationStatistics.html | 477 ++++++++++++++++
.../cross-validation/IDWEstimator.html | 257 +++++++++
.../cross-validation/KNNEstimator.html | 236 ++++++++
.../KrigingCrossValidationStatistics.html | 253 +++++++++
.../cross-validation/KrigingEstimator.html | 327 +++++++++++
.../LeaveOneDrillholeOut.html | 198 +++++++
.../cross-validation/LeaveOneSampleOut.html | 197 +++++++
.../cross-validation/ValidationStrategy.html | 145 +++++
.../declustering/DeclusteringParameters.html | 2 +-
.../kriging/KrigingDiagnostics.html | 518 ++++++++++++++++++
.../kriging/KrigingDiagnosticsResult.html | 172 ++++++
.../kriging/KrigingTargetResult.html | 191 +++++++
.../kriging/RECOMMENDED_DIAGNOSTIC_NAMES.html | 162 ++++++
.../search/SearchNeighborhood.html | 10 +-
.../source-target/attribute_spec.html | 154 ++++++
49 files changed, 5865 insertions(+), 7 deletions(-)
create mode 100644 mkdocs/docs/packages/evo-blockmodels/typed-objects/report/ReportCell.md
create mode 100644 mkdocs/docs/packages/evo-blockmodels/typed-objects/report/ReportCellStatus.md
create mode 100644 mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationEstimator.md
create mode 100644 mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationOutputs.md
create mode 100644 mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationParameters.md
create mode 100644 mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationResult.md
create mode 100644 mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationResultModel.md
create mode 100644 mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationRunner.md
create mode 100644 mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationSource.md
create mode 100644 mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationSourceResult.md
create mode 100644 mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationStatistics.md
create mode 100644 mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/IDWEstimator.md
create mode 100644 mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/KNNEstimator.md
create mode 100644 mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/KrigingCrossValidationStatistics.md
create mode 100644 mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/KrigingEstimator.md
create mode 100644 mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/LeaveOneDrillholeOut.md
create mode 100644 mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/LeaveOneSampleOut.md
create mode 100644 mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/ValidationStrategy.md
create mode 100644 mkdocs/docs/packages/evo-compute/typed-objects/kriging/KrigingDiagnostics.md
create mode 100644 mkdocs/docs/packages/evo-compute/typed-objects/kriging/KrigingDiagnosticsResult.md
create mode 100644 mkdocs/docs/packages/evo-compute/typed-objects/kriging/KrigingTargetResult.md
create mode 100644 mkdocs/docs/packages/evo-compute/typed-objects/kriging/RECOMMENDED_DIAGNOSTIC_NAMES.md
create mode 100644 mkdocs/docs/packages/evo-compute/typed-objects/source-target/attribute_spec.md
create mode 100644 mkdocs/site/packages/evo-blockmodels/typed-objects/report/ReportCell.html
create mode 100644 mkdocs/site/packages/evo-blockmodels/typed-objects/report/ReportCellStatus.html
create mode 100644 mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationEstimator.html
create mode 100644 mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationOutputs.html
create mode 100644 mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationParameters.html
create mode 100644 mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationResult.html
create mode 100644 mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationResultModel.html
create mode 100644 mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationRunner.html
create mode 100644 mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationSource.html
create mode 100644 mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationSourceResult.html
create mode 100644 mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationStatistics.html
create mode 100644 mkdocs/site/packages/evo-compute/typed-objects/cross-validation/IDWEstimator.html
create mode 100644 mkdocs/site/packages/evo-compute/typed-objects/cross-validation/KNNEstimator.html
create mode 100644 mkdocs/site/packages/evo-compute/typed-objects/cross-validation/KrigingCrossValidationStatistics.html
create mode 100644 mkdocs/site/packages/evo-compute/typed-objects/cross-validation/KrigingEstimator.html
create mode 100644 mkdocs/site/packages/evo-compute/typed-objects/cross-validation/LeaveOneDrillholeOut.html
create mode 100644 mkdocs/site/packages/evo-compute/typed-objects/cross-validation/LeaveOneSampleOut.html
create mode 100644 mkdocs/site/packages/evo-compute/typed-objects/cross-validation/ValidationStrategy.html
create mode 100644 mkdocs/site/packages/evo-compute/typed-objects/kriging/KrigingDiagnostics.html
create mode 100644 mkdocs/site/packages/evo-compute/typed-objects/kriging/KrigingDiagnosticsResult.html
create mode 100644 mkdocs/site/packages/evo-compute/typed-objects/kriging/KrigingTargetResult.html
create mode 100644 mkdocs/site/packages/evo-compute/typed-objects/kriging/RECOMMENDED_DIAGNOSTIC_NAMES.html
create mode 100644 mkdocs/site/packages/evo-compute/typed-objects/source-target/attribute_spec.html
diff --git a/mkdocs/docs/packages/evo-blockmodels/typed-objects/report/ReportCell.md b/mkdocs/docs/packages/evo-blockmodels/typed-objects/report/ReportCell.md
new file mode 100644
index 000000000..2d1e10d03
--- /dev/null
+++ b/mkdocs/docs/packages/evo-blockmodels/typed-objects/report/ReportCell.md
@@ -0,0 +1,4 @@
+[GitHub source](https://github.com/SeequentEvo/evo-python-sdk/blob/main/packages/evo-blockmodels/src/evo/blockmodels/typed/report.py)
+::: evo.blockmodels.typed.report.ReportCell
+ options:
+ show_labels: false
diff --git a/mkdocs/docs/packages/evo-blockmodels/typed-objects/report/ReportCellStatus.md b/mkdocs/docs/packages/evo-blockmodels/typed-objects/report/ReportCellStatus.md
new file mode 100644
index 000000000..4a5a6ec86
--- /dev/null
+++ b/mkdocs/docs/packages/evo-blockmodels/typed-objects/report/ReportCellStatus.md
@@ -0,0 +1,4 @@
+[GitHub source](https://github.com/SeequentEvo/evo-python-sdk/blob/main/packages/evo-blockmodels/src/evo/blockmodels/typed/report.py)
+::: evo.blockmodels.typed.report.ReportCellStatus
+ options:
+ show_labels: false
diff --git a/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationEstimator.md b/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationEstimator.md
new file mode 100644
index 000000000..7918855b3
--- /dev/null
+++ b/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationEstimator.md
@@ -0,0 +1,4 @@
+[GitHub source](https://github.com/SeequentEvo/evo-python-sdk/blob/main/packages/evo-compute/src/evo/compute/tasks/geostatistics/cross_validation.py)
+::: evo.compute.tasks.geostatistics.cross_validation.CrossValidationEstimator
+ options:
+ show_labels: false
diff --git a/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationOutputs.md b/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationOutputs.md
new file mode 100644
index 000000000..105952f13
--- /dev/null
+++ b/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationOutputs.md
@@ -0,0 +1,4 @@
+[GitHub source](https://github.com/SeequentEvo/evo-python-sdk/blob/main/packages/evo-compute/src/evo/compute/tasks/geostatistics/cross_validation.py)
+::: evo.compute.tasks.geostatistics.cross_validation.CrossValidationOutputs
+ options:
+ show_labels: false
diff --git a/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationParameters.md b/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationParameters.md
new file mode 100644
index 000000000..699fdf3cb
--- /dev/null
+++ b/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationParameters.md
@@ -0,0 +1,4 @@
+[GitHub source](https://github.com/SeequentEvo/evo-python-sdk/blob/main/packages/evo-compute/src/evo/compute/tasks/geostatistics/cross_validation.py)
+::: evo.compute.tasks.geostatistics.cross_validation.CrossValidationParameters
+ options:
+ show_labels: false
diff --git a/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationResult.md b/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationResult.md
new file mode 100644
index 000000000..5711f443a
--- /dev/null
+++ b/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationResult.md
@@ -0,0 +1,4 @@
+[GitHub source](https://github.com/SeequentEvo/evo-python-sdk/blob/main/packages/evo-compute/src/evo/compute/tasks/geostatistics/cross_validation.py)
+::: evo.compute.tasks.geostatistics.cross_validation.CrossValidationResult
+ options:
+ show_labels: false
diff --git a/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationResultModel.md b/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationResultModel.md
new file mode 100644
index 000000000..6e0a44478
--- /dev/null
+++ b/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationResultModel.md
@@ -0,0 +1,4 @@
+[GitHub source](https://github.com/SeequentEvo/evo-python-sdk/blob/main/packages/evo-compute/src/evo/compute/tasks/geostatistics/cross_validation.py)
+::: evo.compute.tasks.geostatistics.cross_validation.CrossValidationResultModel
+ options:
+ show_labels: false
diff --git a/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationRunner.md b/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationRunner.md
new file mode 100644
index 000000000..c2fdefd0a
--- /dev/null
+++ b/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationRunner.md
@@ -0,0 +1,4 @@
+[GitHub source](https://github.com/SeequentEvo/evo-python-sdk/blob/main/packages/evo-compute/src/evo/compute/tasks/geostatistics/cross_validation.py)
+::: evo.compute.tasks.geostatistics.cross_validation.CrossValidationRunner
+ options:
+ show_labels: false
diff --git a/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationSource.md b/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationSource.md
new file mode 100644
index 000000000..279bdc7f2
--- /dev/null
+++ b/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationSource.md
@@ -0,0 +1,4 @@
+[GitHub source](https://github.com/SeequentEvo/evo-python-sdk/blob/main/packages/evo-compute/src/evo/compute/tasks/geostatistics/cross_validation.py)
+::: evo.compute.tasks.geostatistics.cross_validation.CrossValidationSource
+ options:
+ show_labels: false
diff --git a/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationSourceResult.md b/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationSourceResult.md
new file mode 100644
index 000000000..642e68a87
--- /dev/null
+++ b/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationSourceResult.md
@@ -0,0 +1,4 @@
+[GitHub source](https://github.com/SeequentEvo/evo-python-sdk/blob/main/packages/evo-compute/src/evo/compute/tasks/geostatistics/cross_validation.py)
+::: evo.compute.tasks.geostatistics.cross_validation.CrossValidationSourceResult
+ options:
+ show_labels: false
diff --git a/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationStatistics.md b/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationStatistics.md
new file mode 100644
index 000000000..d8961ad66
--- /dev/null
+++ b/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/CrossValidationStatistics.md
@@ -0,0 +1,4 @@
+[GitHub source](https://github.com/SeequentEvo/evo-python-sdk/blob/main/packages/evo-compute/src/evo/compute/tasks/geostatistics/cross_validation.py)
+::: evo.compute.tasks.geostatistics.cross_validation.CrossValidationStatistics
+ options:
+ show_labels: false
diff --git a/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/IDWEstimator.md b/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/IDWEstimator.md
new file mode 100644
index 000000000..1bb10962e
--- /dev/null
+++ b/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/IDWEstimator.md
@@ -0,0 +1,4 @@
+[GitHub source](https://github.com/SeequentEvo/evo-python-sdk/blob/main/packages/evo-compute/src/evo/compute/tasks/geostatistics/cross_validation.py)
+::: evo.compute.tasks.geostatistics.cross_validation.IDWEstimator
+ options:
+ show_labels: false
diff --git a/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/KNNEstimator.md b/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/KNNEstimator.md
new file mode 100644
index 000000000..9e63d1c5f
--- /dev/null
+++ b/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/KNNEstimator.md
@@ -0,0 +1,4 @@
+[GitHub source](https://github.com/SeequentEvo/evo-python-sdk/blob/main/packages/evo-compute/src/evo/compute/tasks/geostatistics/cross_validation.py)
+::: evo.compute.tasks.geostatistics.cross_validation.KNNEstimator
+ options:
+ show_labels: false
diff --git a/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/KrigingCrossValidationStatistics.md b/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/KrigingCrossValidationStatistics.md
new file mode 100644
index 000000000..a12d72822
--- /dev/null
+++ b/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/KrigingCrossValidationStatistics.md
@@ -0,0 +1,4 @@
+[GitHub source](https://github.com/SeequentEvo/evo-python-sdk/blob/main/packages/evo-compute/src/evo/compute/tasks/geostatistics/cross_validation.py)
+::: evo.compute.tasks.geostatistics.cross_validation.KrigingCrossValidationStatistics
+ options:
+ show_labels: false
diff --git a/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/KrigingEstimator.md b/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/KrigingEstimator.md
new file mode 100644
index 000000000..6b904ae78
--- /dev/null
+++ b/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/KrigingEstimator.md
@@ -0,0 +1,4 @@
+[GitHub source](https://github.com/SeequentEvo/evo-python-sdk/blob/main/packages/evo-compute/src/evo/compute/tasks/geostatistics/cross_validation.py)
+::: evo.compute.tasks.geostatistics.cross_validation.KrigingEstimator
+ options:
+ show_labels: false
diff --git a/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/LeaveOneDrillholeOut.md b/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/LeaveOneDrillholeOut.md
new file mode 100644
index 000000000..ea0aeab8e
--- /dev/null
+++ b/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/LeaveOneDrillholeOut.md
@@ -0,0 +1,4 @@
+[GitHub source](https://github.com/SeequentEvo/evo-python-sdk/blob/main/packages/evo-compute/src/evo/compute/tasks/geostatistics/cross_validation.py)
+::: evo.compute.tasks.geostatistics.cross_validation.LeaveOneDrillholeOut
+ options:
+ show_labels: false
diff --git a/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/LeaveOneSampleOut.md b/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/LeaveOneSampleOut.md
new file mode 100644
index 000000000..ebe1faa77
--- /dev/null
+++ b/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/LeaveOneSampleOut.md
@@ -0,0 +1,4 @@
+[GitHub source](https://github.com/SeequentEvo/evo-python-sdk/blob/main/packages/evo-compute/src/evo/compute/tasks/geostatistics/cross_validation.py)
+::: evo.compute.tasks.geostatistics.cross_validation.LeaveOneSampleOut
+ options:
+ show_labels: false
diff --git a/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/ValidationStrategy.md b/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/ValidationStrategy.md
new file mode 100644
index 000000000..e4d9386b7
--- /dev/null
+++ b/mkdocs/docs/packages/evo-compute/typed-objects/cross-validation/ValidationStrategy.md
@@ -0,0 +1,4 @@
+[GitHub source](https://github.com/SeequentEvo/evo-python-sdk/blob/main/packages/evo-compute/src/evo/compute/tasks/geostatistics/cross_validation.py)
+::: evo.compute.tasks.geostatistics.cross_validation.ValidationStrategy
+ options:
+ show_labels: false
diff --git a/mkdocs/docs/packages/evo-compute/typed-objects/kriging/KrigingDiagnostics.md b/mkdocs/docs/packages/evo-compute/typed-objects/kriging/KrigingDiagnostics.md
new file mode 100644
index 000000000..06c2776ce
--- /dev/null
+++ b/mkdocs/docs/packages/evo-compute/typed-objects/kriging/KrigingDiagnostics.md
@@ -0,0 +1,4 @@
+[GitHub source](https://github.com/SeequentEvo/evo-python-sdk/blob/main/packages/evo-compute/src/evo/compute/tasks/geostatistics/kriging.py)
+::: evo.compute.tasks.geostatistics.kriging.KrigingDiagnostics
+ options:
+ show_labels: false
diff --git a/mkdocs/docs/packages/evo-compute/typed-objects/kriging/KrigingDiagnosticsResult.md b/mkdocs/docs/packages/evo-compute/typed-objects/kriging/KrigingDiagnosticsResult.md
new file mode 100644
index 000000000..26b10488f
--- /dev/null
+++ b/mkdocs/docs/packages/evo-compute/typed-objects/kriging/KrigingDiagnosticsResult.md
@@ -0,0 +1,4 @@
+[GitHub source](https://github.com/SeequentEvo/evo-python-sdk/blob/main/packages/evo-compute/src/evo/compute/tasks/geostatistics/kriging.py)
+::: evo.compute.tasks.geostatistics.kriging.KrigingDiagnosticsResult
+ options:
+ show_labels: false
diff --git a/mkdocs/docs/packages/evo-compute/typed-objects/kriging/KrigingTargetResult.md b/mkdocs/docs/packages/evo-compute/typed-objects/kriging/KrigingTargetResult.md
new file mode 100644
index 000000000..2eb2b8d34
--- /dev/null
+++ b/mkdocs/docs/packages/evo-compute/typed-objects/kriging/KrigingTargetResult.md
@@ -0,0 +1,4 @@
+[GitHub source](https://github.com/SeequentEvo/evo-python-sdk/blob/main/packages/evo-compute/src/evo/compute/tasks/geostatistics/kriging.py)
+::: evo.compute.tasks.geostatistics.kriging.KrigingTargetResult
+ options:
+ show_labels: false
diff --git a/mkdocs/docs/packages/evo-compute/typed-objects/kriging/RECOMMENDED_DIAGNOSTIC_NAMES.md b/mkdocs/docs/packages/evo-compute/typed-objects/kriging/RECOMMENDED_DIAGNOSTIC_NAMES.md
new file mode 100644
index 000000000..9626767c7
--- /dev/null
+++ b/mkdocs/docs/packages/evo-compute/typed-objects/kriging/RECOMMENDED_DIAGNOSTIC_NAMES.md
@@ -0,0 +1,4 @@
+[GitHub source](https://github.com/SeequentEvo/evo-python-sdk/blob/main/packages/evo-compute/src/evo/compute/tasks/geostatistics/kriging.py)
+::: evo.compute.tasks.geostatistics.kriging.RECOMMENDED_DIAGNOSTIC_NAMES
+ options:
+ show_labels: false
diff --git a/mkdocs/docs/packages/evo-compute/typed-objects/source-target/attribute_spec.md b/mkdocs/docs/packages/evo-compute/typed-objects/source-target/attribute_spec.md
new file mode 100644
index 000000000..c11a955f5
--- /dev/null
+++ b/mkdocs/docs/packages/evo-compute/typed-objects/source-target/attribute_spec.md
@@ -0,0 +1,4 @@
+[GitHub source](https://github.com/SeequentEvo/evo-python-sdk/blob/main/packages/evo-compute/src/evo/compute/tasks/common/source_target.py)
+::: evo.compute.tasks.common.source_target.attribute_spec
+ options:
+ show_labels: false
diff --git a/mkdocs/site/packages/evo-blockmodels/typed-objects/report/ReportCell.html b/mkdocs/site/packages/evo-blockmodels/typed-objects/report/ReportCell.html
new file mode 100644
index 000000000..f8c22d9cc
--- /dev/null
+++ b/mkdocs/site/packages/evo-blockmodels/typed-objects/report/ReportCell.html
@@ -0,0 +1,213 @@
+
+
+
+
+
+
+
+
+
+
+ ReportCell - Evo Python SDK
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
GitHub source
+
+
+
+
+
+
+
+
+ evo.blockmodels.typed.report.ReportCell
+
+
+
+
+
+
+
+
+
+
A single report/comparison cell: a numeric value plus a status.
+
The status explains why a value may be null (could not be aggregated/calculated).
+See ReportCellStatus for the possible reasons.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ value
+
+
+
+
value : Annotated [ StrictInt | StrictFloat | None , Field ( title = 'Value' , examples = [ 2.7 ])]
+
+
+
+
+
Value of the cell. This is null whenever status is not OK.
+
+
+
+
+
+
+
+
+
+
+ status
+
+
+
+
status : Annotated [ ReportCellStatus , Field ( examples = [ 'OK' ])] = OK
+
+
+
+
+
Status of the cell, describing how value should be interpreted.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Keys
+ Action
+
+
+
+
+ ?
+ Open this help
+
+
+ n
+ Next page
+
+
+ p
+ Previous page
+
+
+ s
+ Search
+
+
+
+
+
+
+
+
+
+
+
diff --git a/mkdocs/site/packages/evo-blockmodels/typed-objects/report/ReportCellStatus.html b/mkdocs/site/packages/evo-blockmodels/typed-objects/report/ReportCellStatus.html
new file mode 100644
index 000000000..7012f3ec8
--- /dev/null
+++ b/mkdocs/site/packages/evo-blockmodels/typed-objects/report/ReportCellStatus.html
@@ -0,0 +1,199 @@
+
+
+
+
+
+
+
+
+
+
+ ReportCellStatus - Evo Python SDK
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
GitHub source
+
+
+
+
+
+
+
+
+ evo.blockmodels.typed.report.ReportCellStatus
+
+
+
+
+
+
+
+
+
+
Status of a single report cell, describing how its value should be interpreted.
+
+OK: the value was calculated normally and can be used as-is.
+PERCENT_CHANGE_FROM_ZERO: the percentage change is undefined because the
+ from value was zero. Only used in comparisons.
+NO_DATA: no data was available to calculate the value.
+INVALID: the value could not be calculated because the underlying data
+ contained an invalid value.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ PERCENT_CHANGE_FROM_ZERO
+
+
+
+
PERCENT_CHANGE_FROM_ZERO = 'PERCENT_CHANGE_FROM_ZERO'
+
+
+
+
+
Only used in comparisons.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Keys
+ Action
+
+
+
+
+ ?
+ Open this help
+
+
+ n
+ Next page
+
+
+ p
+ Previous page
+
+
+ s
+ Search
+
+
+
+
+
+
+
+
+
+
+
diff --git a/mkdocs/site/packages/evo-compute/typed-objects/continuous-distribution/UpperTail.html b/mkdocs/site/packages/evo-compute/typed-objects/continuous-distribution/UpperTail.html
index 13f4e3ad3..8fcdcbacf 100644
--- a/mkdocs/site/packages/evo-compute/typed-objects/continuous-distribution/UpperTail.html
+++ b/mkdocs/site/packages/evo-compute/typed-objects/continuous-distribution/UpperTail.html
@@ -39,7 +39,7 @@
-
+
Next
diff --git a/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationEstimator.html b/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationEstimator.html
new file mode 100644
index 000000000..903442ebb
--- /dev/null
+++ b/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationEstimator.html
@@ -0,0 +1,147 @@
+
+
+
+
+
+
+
+
+
+
+ CrossValidationEstimator - Evo Python SDK
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
GitHub source
+
+
+
+
+
+
+
+
+ evo.compute.tasks.geostatistics.cross_validation.CrossValidationEstimator
+
+
+
+
CrossValidationEstimator : TypeAlias = Annotated [
+ KrigingEstimator | KNNEstimator | IDWEstimator , Field ( discriminator = "type" )
+]
+
+
+
+
+
Tagged union of supported cross-validation estimators.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Keys
+ Action
+
+
+
+
+ ?
+ Open this help
+
+
+ n
+ Next page
+
+
+ p
+ Previous page
+
+
+ s
+ Search
+
+
+
+
+
+
+
+
+
+
+
diff --git a/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationOutputs.html b/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationOutputs.html
new file mode 100644
index 000000000..20b0d448b
--- /dev/null
+++ b/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationOutputs.html
@@ -0,0 +1,228 @@
+
+
+
+
+
+
+
+
+
+
+ CrossValidationOutputs - Evo Python SDK
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
GitHub source
+
+
+
+
+
+
+
+
+ evo.compute.tasks.geostatistics.cross_validation.CrossValidationOutputs
+
+
+
+
+
+
+
+
+
+
Per-sample attributes written back onto the source object.
+
Both estimate and error accept:
+
+a str — create a new attribute with that name.
+a typed attribute from the source object — update it if it already exists
+ (must be a floating-point attribute), otherwise create it.
+a :class:~evo.compute.tasks.common.CreateAttribute or
+ :class:~evo.compute.tasks.common.UpdateAttribute for explicit control.
+
+
Samples that produced no valid estimate carry NaN in the written
+estimate and error attributes. The error attribute stores the
+signed error estimate - true, so a positive value is an overestimate.
+
Example::
+
>>> outputs = CrossValidationOutputs(
+... estimate="cv_estimate",
+... error="cv_error",
+... )
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ estimate
+
+
+
+
estimate : Annotated [ CreateAttribute | UpdateAttribute , Field ( discriminator = 'operation' )]
+
+
+
+
+
Attribute to create or update on the source object with each sample's cross-validated estimate.
+
+
+
+
+
+
+
+
+
+
+ error
+
+
+
+
error : Annotated [ CreateAttribute | UpdateAttribute , Field ( discriminator = 'operation' )] | None = None
+
+
+
+
+
Optional attribute to create or update with the signed error (estimate - true).
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Keys
+ Action
+
+
+
+
+ ?
+ Open this help
+
+
+ n
+ Next page
+
+
+ p
+ Previous page
+
+
+ s
+ Search
+
+
+
+
+
+
+
+
+
+
+
diff --git a/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationParameters.html b/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationParameters.html
new file mode 100644
index 000000000..5175c61c8
--- /dev/null
+++ b/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationParameters.html
@@ -0,0 +1,300 @@
+
+
+
+
+
+
+
+
+
+
+ CrossValidationParameters - Evo Python SDK
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
GitHub source
+
+
+
+
+
+
+
+
+ evo.compute.tasks.geostatistics.cross_validation.CrossValidationParameters
+
+
+
+
+
+
+
+
+
+
Parameters for the geostatistics/cross-validation compute task.
+
Example::
+
>>> from evo.compute.tasks import Filter, FilterCondition, KrigingDiagnostics, SearchNeighborhood, run
+>>> from evo.compute.tasks.geostatistics.cross_validation import (
+... CrossValidationOutputs,
+... CrossValidationParameters,
+... KrigingEstimator,
+... LeaveOneSampleOut,
+... )
+>>>
+>>> params = CrossValidationParameters(
+... source=pointset.attributes["Cu_pct"],
+... source_filter=Filter(
+... where=FilterCondition(
+... attribute=pointset.attributes["domain"],
+... operator="in",
+... values=["Early Diorite"],
+... ),
+... ),
+... validation=LeaveOneSampleOut(),
+... estimator=KrigingEstimator(
+... variogram=variogram,
+... neighborhood=SearchNeighborhood(ellipsoid=ellipsoid, max_samples=24),
+... diagnostics=KrigingDiagnostics(kriging_variance=True, slope_of_regression=True),
+... ),
+... outputs=CrossValidationOutputs(estimate="Cu_cv_est", error="Cu_cv_err"),
+... )
+>>> result = await run(manager, params, preview=True)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ source
+
+
+
+
source : Annotated [ CrossValidationSource , BeforeValidator ( _convert_cross_validation_source )]
+
+
+
+
+
Source object and attribute containing the known sample values to cross-validate.
+
+
+
+
+
+
+
+
+
+
+ validation
+
+
+
+
validation : ValidationStrategy
+
+
+
+
+
Hold-out strategy (:class:LeaveOneSampleOut or :class:LeaveOneDrillholeOut).
+
+
+
+
+
+
+
+
+
+
+ estimator
+
+
+
+
estimator : CrossValidationEstimator
+
+
+
+
+
Estimator configuration (:class:KrigingEstimator, :class:KNNEstimator, or :class:IDWEstimator).
+
+
+
+
+
+
+
+
+
+
+ outputs
+
+
+
+
outputs : CrossValidationOutputs
+
+
+
+
+
Per-sample output attributes to write back onto the source object.
+
+
+
+
+
+
+
+
+
+
+ source_filter
+
+
+
+
source_filter : Filter | None = Field ( None , exclude = True )
+
+
+
+
+
Optional filter restricting cross-validation to a subset of the source samples.
+
Excluded from top-level serialization and injected into source["filter"].
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Keys
+ Action
+
+
+
+
+ ?
+ Open this help
+
+
+ n
+ Next page
+
+
+ p
+ Previous page
+
+
+ s
+ Search
+
+
+
+
+
+
+
+
+
+
+
diff --git a/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationResult.html b/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationResult.html
new file mode 100644
index 000000000..d93b5397f
--- /dev/null
+++ b/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationResult.html
@@ -0,0 +1,461 @@
+
+
+
+
+
+
+
+
+
+
+ CrossValidationResult - Evo Python SDK
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
GitHub source
+
+
+
+
+
+
+
+
+ evo.compute.tasks.geostatistics.cross_validation.CrossValidationResult
+
+
+
+
+
+
+
+
+
+
Rich result object for the cross-validation task.
+
Provides typed access to the updated source object, output attributes,
+kriging diagnostics, common summary statistics, and kriging-only
+standardized error statistics.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ message
+
+
+
+
+
+
+
+
A message describing what happened in the task.
+
+
+
+
+
+
+
+
+
+
+ source
+
+
+
+
source : CrossValidationSourceResult
+
+
+
+
+
Metadata and written attribute references for the updated source object.
+
+
+
+
+
+
+
+
+
+
+ source_name
+
+
+
+
+
+
+
+
The name of the source object updated with cross-validation attributes.
+
+
+
+
+
+
+
+
+
+
+ source_reference
+
+
+
+
+
+
+
+
Reference URL to the updated source object.
+
+
+
+
+
+
+
+
+
+
+ estimate_attribute
+
+
+
+
estimate_attribute : TaskAttribute
+
+
+
+
+
The attribute containing each sample's cross-validated estimate.
+
+
+
+
+
+
+
+
+
+
+ estimate_name
+
+
+
+
+
+
+
+
The name of the attribute containing each sample's cross-validated estimate.
+
+
+
+
+
+
+
+
+
+
+ error_attribute
+
+
+
+
error_attribute : TaskAttribute | None
+
+
+
+
+
The attribute containing each sample's signed error, or None if not requested.
+
+
+
+
+
+
+
+
+
+
+ error_name
+
+
+
+
+
+
+
+
The name of the signed-error attribute, or None if not requested.
+
+
+
+
+
+
+
+
+
+
+ diagnostics
+
+
+
+
diagnostics : dict [ str , TaskAttribute ]
+
+
+
+
+
The kriging diagnostic attributes that were written, keyed by diagnostic name.
+
Empty when no diagnostics were requested or when the estimator is KNN or IDW.
+
+
+
+
+
+
+
+
+
+
+ statistics
+
+
+
+
statistics : CrossValidationStatistics
+
+
+
+
+
Summary statistics comparing held-out true values with their estimates.
+
+
+
+
+
+
+
+
+
+
+ kriging_statistics
+
+
+
+
kriging_statistics : KrigingCrossValidationStatistics | None
+
+
+
+
+
Kriging standardized error statistics, or None for KNN and IDW.
+
+
+
+
+
+
+
+
+
+
+ schema
+
+
+
+
+
+
+
+
The schema type of the source object (e.g., 'pointset' or 'downhole-intervals').
+
+
+
+
+
+
+
+
+
+
+
+
+ get_source_object
+
+
+
+
get_source_object () -> BaseObject
+
+
+
+
+
Load and return the updated source geoscience object.
+
+
+
+
+
+
+
+
+
+
+ to_dataframe
+
+
+
+
to_dataframe ( * columns : str ) -> pd . DataFrame
+
+
+
+
+
Load the updated source object and return its data as a DataFrame.
+
Args:
+ *columns: Optional column names to select. If omitted, returns all columns.
+
Returns:
+ A pandas DataFrame containing the source data and written cross-validation attributes.
+
Raises:
+ TypeError: If the source object type does not support DataFrame export.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Keys
+ Action
+
+
+
+
+ ?
+ Open this help
+
+
+ n
+ Next page
+
+
+ p
+ Previous page
+
+
+ s
+ Search
+
+
+
+
+
+
+
+
+
+
+
diff --git a/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationResultModel.html b/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationResultModel.html
new file mode 100644
index 000000000..645b8c397
--- /dev/null
+++ b/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationResultModel.html
@@ -0,0 +1,251 @@
+
+
+
+
+
+
+
+
+
+
+ CrossValidationResultModel - Evo Python SDK
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
GitHub source
+
+
+
+
+
+
+
+
+ evo.compute.tasks.geostatistics.cross_validation.CrossValidationResultModel
+
+
+
+
+
+
+
+
+
+
Pydantic model for the raw cross-validation task result payload.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ message
+
+
+
+
+
+
+
+
A message describing what happened in the task.
+
+
+
+
+
+
+
+
+
+
+ source
+
+
+
+
source : CrossValidationSourceResult
+
+
+
+
+
The source object updated with the cross-validation output attributes.
+
+
+
+
+
+
+
+
+
+
+ statistics
+
+
+
+
statistics : CrossValidationStatistics
+
+
+
+
+
Summary statistics comparing held-out true values with their estimates.
+
+
+
+
+
+
+
+
+
+
+ kriging_statistics
+
+
+
+
kriging_statistics : KrigingCrossValidationStatistics | None = None
+
+
+
+
+
Standardized kriging statistics (present for kriging only; None for KNN and IDW).
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Keys
+ Action
+
+
+
+
+ ?
+ Open this help
+
+
+ n
+ Next page
+
+
+ p
+ Previous page
+
+
+ s
+ Search
+
+
+
+
+
+
+
+
+
+
+
diff --git a/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationRunner.html b/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationRunner.html
new file mode 100644
index 000000000..c4052804f
--- /dev/null
+++ b/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationRunner.html
@@ -0,0 +1,175 @@
+
+
+
+
+
+
+
+
+
+
+ CrossValidationRunner - Evo Python SDK
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
GitHub source
+
+
+
+
+
+
+
+
+ evo.compute.tasks.geostatistics.cross_validation.CrossValidationRunner
+
+
+
+
+
+
+
+
+
+
Runner for cross-validation compute tasks.
+
Automatically registered — used by :func:~evo.compute.tasks.run for
+dispatch, or directly::
+
result = await CrossValidationRunner(context, params, preview=True)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Keys
+ Action
+
+
+
+
+ ?
+ Open this help
+
+
+ n
+ Next page
+
+
+ p
+ Previous page
+
+
+ s
+ Search
+
+
+
+
+
+
+
+
+
+
+
diff --git a/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationSource.html b/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationSource.html
new file mode 100644
index 000000000..d11b7d3f8
--- /dev/null
+++ b/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationSource.html
@@ -0,0 +1,194 @@
+
+
+
+
+
+
+
+
+
+
+ CrossValidationSource - Evo Python SDK
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
GitHub source
+
+
+
+
+
+
+
+
+ evo.compute.tasks.geostatistics.cross_validation.CrossValidationSource
+
+
+
+
+
+
+
+
+
+
The samples to cross-validate and the attribute holding their known values.
+
Can be constructed explicitly or converted automatically from a typed
+attribute such as pointset.attributes["grade"] or
+downhole_intervals.attributes["grade"].
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ filter
+
+
+
+
filter : Filter | None = None
+
+
+
+
+
Optional filter restricting which source locations are cross-validated and used as neighbours.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Keys
+ Action
+
+
+
+
+ ?
+ Open this help
+
+
+ n
+ Next page
+
+
+ p
+ Previous page
+
+
+ s
+ Search
+
+
+
+
+
+
+
+
+
+
+
diff --git a/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationSourceResult.html b/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationSourceResult.html
new file mode 100644
index 000000000..ac9b95c7b
--- /dev/null
+++ b/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationSourceResult.html
@@ -0,0 +1,311 @@
+
+
+
+
+
+
+
+
+
+
+ CrossValidationSourceResult - Evo Python SDK
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
GitHub source
+
+
+
+
+
+
+
+
+ evo.compute.tasks.geostatistics.cross_validation.CrossValidationSourceResult
+
+
+
+
+
+
+
+
+
+
The source object updated with the per-sample cross-validation attributes.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ reference
+
+
+
+
+
+
+
+
Reference URL to the updated source geoscience object.
+
+
+
+
+
+
+
+
+
+
+ name
+
+
+
+
+
+
+
+
Name of the source geoscience object.
+
+
+
+
+
+
+
+
+
+
+ description
+
+
+
+
description : str | None = None
+
+
+
+
+
Optional description of the source geoscience object.
+
+
+
+
+
+
+
+
+
+
+ schema_id
+
+
+
+
+
+
+
+
Schema identifier of the source geoscience object.
+
+
+
+
+
+
+
+
+
+
+ estimate
+
+
+
+
estimate : TaskAttribute
+
+
+
+
+
Attribute written with each sample's cross-validated estimate.
+
+
+
+
+
+
+
+
+
+
+ error
+
+
+
+
error : TaskAttribute | None = None
+
+
+
+
+
Attribute written with each sample's signed error, when requested.
+
+
+
+
+
+
+
+
+
+
+ diagnostics
+
+
+
+
diagnostics : KrigingDiagnosticsResult | None = None
+
+
+
+
+
Kriging diagnostic attributes written alongside the estimate, when requested.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Keys
+ Action
+
+
+
+
+ ?
+ Open this help
+
+
+ n
+ Next page
+
+
+ p
+ Previous page
+
+
+ s
+ Search
+
+
+
+
+
+
+
+
+
+
+
diff --git a/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationStatistics.html b/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationStatistics.html
new file mode 100644
index 000000000..53e636b28
--- /dev/null
+++ b/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/CrossValidationStatistics.html
@@ -0,0 +1,477 @@
+
+
+
+
+
+
+
+
+
+
+ CrossValidationStatistics - Evo Python SDK
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
GitHub source
+
+
+
+
+
+
+
+
+ evo.compute.tasks.geostatistics.cross_validation.CrossValidationStatistics
+
+
+
+
+
+
+
+
+
+
Summary statistics comparing held-out true values with their estimates.
+
Statistics are computed over samples that produced a valid estimate
+(valid_count). Samples without a valid estimate are counted in
+invalid_count, carry NaN in the written attributes, and are excluded
+from the summary statistics. Any statistic that is undefined for the
+available valid samples (such as correlation when fewer than two samples
+are valid or variance is zero) is None.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ evaluated_count
+
+
+
+
+
+
+
+
Number of samples cross-validated after applying any source filter.
+
+
+
+
+
+
+
+
+
+
+ valid_count
+
+
+
+
+
+
+
+
Number of cross-validated samples that produced a finite estimate.
+
+
+
+
+
+
+
+
+
+
+ invalid_count
+
+
+
+
+
+
+
+
Number of cross-validated samples that produced no estimate.
+
+
+
+
+
+
+
+
+
+
+ mean_true
+
+
+
+
mean_true : float | None
+
+
+
+
+
Mean of the held-out true values over the valid samples.
+
+
+
+
+
+
+
+
+
+
+ mean_estimate
+
+
+
+
mean_estimate : float | None
+
+
+
+
+
Mean of the cross-validated estimates over the valid samples.
+
+
+
+
+
+
+
+
+
+
+ variance_true
+
+
+
+
variance_true : float | None
+
+
+
+
+
Population variance of the held-out true values over the valid samples.
+
+
+
+
+
+
+
+
+
+
+ variance_estimate
+
+
+
+
variance_estimate : float | None
+
+
+
+
+
Population variance of the cross-validated estimates over the valid samples.
+
+
+
+
+
+
+
+
+
+
+ mean_error
+
+
+
+
mean_error : float | None
+
+
+
+
+
Mean of estimate - true. Positive values indicate overestimation bias.
+
+
+
+
+
+
+
+
+
+
+ mean_absolute_error
+
+
+
+
mean_absolute_error : float | None
+
+
+
+
+
Mean of |estimate - true|.
+
+
+
+
+
+
+
+
+
+
+ mean_squared_error
+
+
+
+
mean_squared_error : float | None
+
+
+
+
+
Mean of (estimate - true) ** 2.
+
+
+
+
+
+
+
+
+
+
+ root_mean_squared_error
+
+
+
+
root_mean_squared_error : float | None
+
+
+
+
+
Square root of mean_squared_error, in the units of the estimated attribute.
+
+
+
+
+
+
+
+
+
+
+ error_variance
+
+
+
+
error_variance : float | None
+
+
+
+
+
Population variance of estimate - true.
+
+
+
+
+
+
+
+
+
+
+ correlation
+
+
+
+
correlation : float | None
+
+
+
+
+
Pearson correlation coefficient between true values and estimates, or None when undefined.
+
+
+
+
+
+
+
+
+
+
+ regression_slope
+
+
+
+
regression_slope : float | None
+
+
+
+
+
Slope of true values regressed on estimates, or None when undefined.
+
+
+
+
+
+
+
+
+
+
+ regression_intercept
+
+
+
+
regression_intercept : float | None
+
+
+
+
+
Intercept of true values regressed on estimates, or None when regression_slope is None.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Keys
+ Action
+
+
+
+
+ ?
+ Open this help
+
+
+ n
+ Next page
+
+
+ p
+ Previous page
+
+
+ s
+ Search
+
+
+
+
+
+
+
+
+
+
+
diff --git a/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/IDWEstimator.html b/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/IDWEstimator.html
new file mode 100644
index 000000000..d92a1ae86
--- /dev/null
+++ b/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/IDWEstimator.html
@@ -0,0 +1,257 @@
+
+
+
+
+
+
+
+
+
+
+ IDWEstimator - Evo Python SDK
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
GitHub source
+
+
+
+
+
+
+
+
+ evo.compute.tasks.geostatistics.cross_validation.IDWEstimator
+
+
+
+
+
+
+
+
+
+
Re-estimate held-out locations using inverse-distance weighting.
+
Example::
+
>>> estimator = IDWEstimator(
+... neighborhood=SearchNeighborhood(ellipsoid=ellipsoid, max_samples=20),
+... power=2.0,
+... )
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ type
+
+
+
+
type : Literal [ 'idw' ] = 'idw'
+
+
+
+
+
Discriminator selecting the inverse-distance-weighting estimator.
+
+
+
+
+
+
+
+
+
+
+ neighborhood
+
+
+
+
neighborhood : _CrossValidationNeighborhood = Field ( validation_alias = AliasChoices ( 'neighborhood' , 'search' ))
+
+
+
+
+
Search neighborhood deciding which remaining samples estimate each held-out location.
+
+
+
+
+
+
+
+
+
+
+ power
+
+
+
+
power : float = Field ( gt = 0.0 , allow_inf_nan = False )
+
+
+
+
+
Distance-weighting exponent (must be strictly positive, e.g. 1.0 or 2.0).
+
+
+
+
+
+
+
+
+
+
+ search
+
+
+
+
search : SearchNeighborhood
+
+
+
+
+
Backwards-compatible alias for :attr:neighborhood.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Keys
+ Action
+
+
+
+
+ ?
+ Open this help
+
+
+ n
+ Next page
+
+
+ p
+ Previous page
+
+
+ s
+ Search
+
+
+
+
+
+
+
+
+
+
+
diff --git a/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/KNNEstimator.html b/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/KNNEstimator.html
new file mode 100644
index 000000000..3addcec54
--- /dev/null
+++ b/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/KNNEstimator.html
@@ -0,0 +1,236 @@
+
+
+
+
+
+
+
+
+
+
+ KNNEstimator - Evo Python SDK
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
GitHub source
+
+
+
+
+
+
+
+
+ evo.compute.tasks.geostatistics.cross_validation.KNNEstimator
+
+
+
+
+
+
+
+
+
+
Re-estimate held-out locations with the arithmetic mean of their nearest neighbours.
+
Example::
+
>>> estimator = KNNEstimator(
+... neighborhood=SearchNeighborhood(ellipsoid=ellipsoid, max_samples=12),
+... )
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ type
+
+
+
+
type : Literal [ 'knn' ] = 'knn'
+
+
+
+
+
Discriminator selecting the k-nearest-neighbour estimator.
+
+
+
+
+
+
+
+
+
+
+ neighborhood
+
+
+
+
neighborhood : _CrossValidationNeighborhood = Field ( validation_alias = AliasChoices ( 'neighborhood' , 'search' ))
+
+
+
+
+
Search neighborhood deciding which remaining samples estimate each held-out location.
+
+
+
+
+
+
+
+
+
+
+ search
+
+
+
+
search : SearchNeighborhood
+
+
+
+
+
Backwards-compatible alias for :attr:neighborhood.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Keys
+ Action
+
+
+
+
+ ?
+ Open this help
+
+
+ n
+ Next page
+
+
+ p
+ Previous page
+
+
+ s
+ Search
+
+
+
+
+
+
+
+
+
+
+
diff --git a/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/KrigingCrossValidationStatistics.html b/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/KrigingCrossValidationStatistics.html
new file mode 100644
index 000000000..dde158748
--- /dev/null
+++ b/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/KrigingCrossValidationStatistics.html
@@ -0,0 +1,253 @@
+
+
+
+
+
+
+
+
+
+
+ KrigingCrossValidationStatistics - Evo Python SDK
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
GitHub source
+
+
+
+
+
+
+
+
+ evo.compute.tasks.geostatistics.cross_validation.KrigingCrossValidationStatistics
+
+
+
+
+
+
+
+
+
+
Standardized error summary statistics returned for kriging cross-validation only.
+
Computed over valid samples that also have a positive kriging variance
+(standardized_count). Absent (None on the result) for KNN and IDW.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ standardized_count
+
+
+
+
standardized_count : int
+
+
+
+
+
Number of valid samples with a positive kriging variance.
+
+
+
+
+
+
+
+
+
+
+ mean_kriging_variance
+
+
+
+
mean_kriging_variance : float | None
+
+
+
+
+
Mean kriging variance over the standardized samples, or None when standardized_count == 0.
+
+
+
+
+
+
+
+
+
+
+ mean_standardized_error
+
+
+
+
mean_standardized_error : float | None
+
+
+
+
+
Mean of (estimate - true) / sqrt(kriging_variance), or None when standardized_count == 0.
+
+
+
+
+
+
+
+
+
+
+ standardized_error_variance
+
+
+
+
standardized_error_variance : float | None
+
+
+
+
+
Population variance of the standardized error, or None when standardized_count == 0.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Keys
+ Action
+
+
+
+
+ ?
+ Open this help
+
+
+ n
+ Next page
+
+
+ p
+ Previous page
+
+
+ s
+ Search
+
+
+
+
+
+
+
+
+
+
+
diff --git a/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/KrigingEstimator.html b/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/KrigingEstimator.html
new file mode 100644
index 000000000..e8836eb30
--- /dev/null
+++ b/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/KrigingEstimator.html
@@ -0,0 +1,327 @@
+
+
+
+
+
+
+
+
+
+
+ KrigingEstimator - Evo Python SDK
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
GitHub source
+
+
+
+
+
+
+
+
+ evo.compute.tasks.geostatistics.cross_validation.KrigingEstimator
+
+
+
+
+
+
+
+
+
+
Re-estimate held-out locations using simple or ordinary kriging.
+
Carries the variogram, kriging method, search neighborhood, and optional
+per-sample :class:~evo.compute.tasks.geostatistics.kriging.KrigingDiagnostics
+written onto the source object alongside the cross-validated estimate.
+
Example::
+
>>> from evo.compute.tasks import KrigingDiagnostics, SearchNeighborhood
+>>> from evo.compute.tasks.geostatistics.kriging import KrigingMethod
+>>>
+>>> estimator = KrigingEstimator(
+... variogram=variogram,
+... neighborhood=SearchNeighborhood(ellipsoid=ellipsoid, max_samples=20),
+... kriging_method=KrigingMethod.ORDINARY,
+... diagnostics=KrigingDiagnostics(kriging_variance=True, num_samples=True),
+... )
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ type
+
+
+
+
type : Literal [ 'kriging' ] = 'kriging'
+
+
+
+
+
Discriminator selecting the kriging estimator.
+
+
+
+
+
+
+
+
+
+
+ variogram
+
+
+
+
variogram : GeoscienceObjectReference
+
+
+
+
+
Model of the covariance within the domain (Variogram object or reference URL).
+
+
+
+
+
+
+
+
+
+
+ neighborhood
+
+
+
+
neighborhood : _CrossValidationNeighborhood = Field ( validation_alias = AliasChoices ( 'neighborhood' , 'search' ))
+
+
+
+
+
Search neighborhood deciding which remaining samples estimate each held-out location.
+
+
+
+
+
+
+
+
+
+
+ kriging_method
+
+
+
+
kriging_method : Annotated [ SimpleKriging | OrdinaryKriging , Field ( discriminator = "type" )] = Field (
+ default_factory = OrdinaryKriging , validation_alias = AliasChoices ( "kriging_method" , "method" )
+)
+
+
+
+
+
The kriging method to use. Defaults to ordinary kriging.
+
+
+
+
+
+
+
+
+
+
+ diagnostics
+
+
+
+
diagnostics : KrigingDiagnostics | None = None
+
+
+
+
+
Optional per-sample kriging diagnostic attributes to write onto the source object.
+
+
+
+
+
+
+
+
+
+
+ search
+
+
+
+
search : SearchNeighborhood
+
+
+
+
+
Backwards-compatible alias for :attr:neighborhood.
+
+
+
+
+
+
+
+
+
+
+ method
+
+
+
+
method : SimpleKriging | OrdinaryKriging
+
+
+
+
+
Backwards-compatible alias for :attr:kriging_method.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Keys
+ Action
+
+
+
+
+ ?
+ Open this help
+
+
+ n
+ Next page
+
+
+ p
+ Previous page
+
+
+ s
+ Search
+
+
+
+
+
+
+
+
+
+
+
diff --git a/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/LeaveOneDrillholeOut.html b/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/LeaveOneDrillholeOut.html
new file mode 100644
index 000000000..53ee2d979
--- /dev/null
+++ b/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/LeaveOneDrillholeOut.html
@@ -0,0 +1,198 @@
+
+
+
+
+
+
+
+
+
+
+ LeaveOneDrillholeOut - Evo Python SDK
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
GitHub source
+
+
+
+
+
+
+
+
+ evo.compute.tasks.geostatistics.cross_validation.LeaveOneDrillholeOut
+
+
+
+
+
+
+
+
+
+
Hold out one drillhole at a time, estimating its samples from the remaining holes.
+
Requires a :class:~evo.objects.typed.DownholeIntervals source object to
+supply drillhole IDs. Each query excludes every sample sharing its drillhole
+ID before neighbour quotas are applied, while keeping samples from other
+holes eligible.
+
Example::
+
>>> validation = LeaveOneDrillholeOut()
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ type
+
+
+
+
type : Literal [ 'drillhole' ] = 'drillhole'
+
+
+
+
+
Discriminator selecting leave-one-drillhole-out validation.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Keys
+ Action
+
+
+
+
+ ?
+ Open this help
+
+
+ n
+ Next page
+
+
+ p
+ Previous page
+
+
+ s
+ Search
+
+
+
+
+
+
+
+
+
+
+
diff --git a/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/LeaveOneSampleOut.html b/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/LeaveOneSampleOut.html
new file mode 100644
index 000000000..5622d6ace
--- /dev/null
+++ b/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/LeaveOneSampleOut.html
@@ -0,0 +1,197 @@
+
+
+
+
+
+
+
+
+
+
+ LeaveOneSampleOut - Evo Python SDK
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
GitHub source
+
+
+
+
+
+
+
+
+ evo.compute.tasks.geostatistics.cross_validation.LeaveOneSampleOut
+
+
+
+
+
+
+
+
+
+
Hold out each sample and any samples coincident with its location.
+
Estimates every selected sample in one pass, excluding the sample's own
+location (including coincident samples strictly closer than 1e-8 world
+units) before applying neighbour quotas.
+
Example::
+
>>> validation = LeaveOneSampleOut()
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ type
+
+
+
+
type : Literal [ 'sample' ] = 'sample'
+
+
+
+
+
Discriminator selecting leave-one-sample-out validation.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Keys
+ Action
+
+
+
+
+ ?
+ Open this help
+
+
+ n
+ Next page
+
+
+ p
+ Previous page
+
+
+ s
+ Search
+
+
+
+
+
+
+
+
+
+
+
diff --git a/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/ValidationStrategy.html b/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/ValidationStrategy.html
new file mode 100644
index 000000000..31792f497
--- /dev/null
+++ b/mkdocs/site/packages/evo-compute/typed-objects/cross-validation/ValidationStrategy.html
@@ -0,0 +1,145 @@
+
+
+
+
+
+
+
+
+
+
+ ValidationStrategy - Evo Python SDK
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
GitHub source
+
+
+
+
+
+
+
+
+ evo.compute.tasks.geostatistics.cross_validation.ValidationStrategy
+
+
+
+
ValidationStrategy : TypeAlias = Annotated [ LeaveOneSampleOut | LeaveOneDrillholeOut , Field ( discriminator = 'type' )]
+
+
+
+
+
Tagged union of supported cross-validation hold-out strategies.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Keys
+ Action
+
+
+
+
+ ?
+ Open this help
+
+
+ n
+ Next page
+
+
+ p
+ Previous page
+
+
+ s
+ Search
+
+
+
+
+
+
+
+
+
+
+
diff --git a/mkdocs/site/packages/evo-compute/typed-objects/declustering/DeclusteringParameters.html b/mkdocs/site/packages/evo-compute/typed-objects/declustering/DeclusteringParameters.html
index 151553591..a4de9dfde 100644
--- a/mkdocs/site/packages/evo-compute/typed-objects/declustering/DeclusteringParameters.html
+++ b/mkdocs/site/packages/evo-compute/typed-objects/declustering/DeclusteringParameters.html
@@ -34,7 +34,7 @@
-
+
Previous
diff --git a/mkdocs/site/packages/evo-compute/typed-objects/kriging/KrigingDiagnostics.html b/mkdocs/site/packages/evo-compute/typed-objects/kriging/KrigingDiagnostics.html
new file mode 100644
index 000000000..bf6a59160
--- /dev/null
+++ b/mkdocs/site/packages/evo-compute/typed-objects/kriging/KrigingDiagnostics.html
@@ -0,0 +1,518 @@
+
+
+
+
+
+
+
+
+
+
+ KrigingDiagnostics - Evo Python SDK
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
GitHub source
+
+
+
+
+
+
+
+
+ evo.compute.tasks.geostatistics.kriging.KrigingDiagnostics
+
+
+
+
+
+
+
+
+
+
Optional per-location diagnostics written alongside the kriging estimate.
+
Each field selects one diagnostic and says where to write it on the target object.
+Only the diagnostics you set are computed; the rest are left out entirely.
+
Every field accepts:
+
+True — create an attribute using the Leapfrog-aligned recommended name from
+ :data:RECOMMENDED_DIAGNOSTIC_NAMES (for example KV for kriging_variance).
+a str — create an attribute with that name.
+a typed attribute from the target object — update it if it already exists,
+ otherwise create it.
+a :class:~evo.compute.tasks.common.CreateAttribute or
+ :class:~evo.compute.tasks.common.UpdateAttribute for full control.
+
+
Every output of a kriging task writes to its own attribute, so each diagnostic name
+must differ from the estimate's attribute name and from every other diagnostic.
+
An existing attribute must be able to hold the diagnostic's values: boolean for valid,
+integer for the num_* counts, and floating-point for the rest.
+
Example::
+
>>> diagnostics = KrigingDiagnostics(
+... kriging_variance=True, # creates "KV"
+... num_samples="sample_count", # creates "sample_count"
+... slope_of_regression=block_model.attributes["SoR"], # updates if it exists
+... )
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ valid
+
+
+
+
valid : CreateAttribute | UpdateAttribute | None = None
+
+
+
+
+
Whether each target location's neighbourhood satisfied the search constraints.
+
+
+
+
+
+
+
+
+
+
+ kriging_variance
+
+
+
+
kriging_variance : CreateAttribute | UpdateAttribute | None = None
+
+
+
+
+
The kriging variance (estimation uncertainty).
+
+
+
+
+
+
+
+
+
+
+ slope_of_regression
+
+
+
+
slope_of_regression : CreateAttribute | UpdateAttribute | None = None
+
+
+
+
+
The slope of regression, a diagnostic for conditional bias.
+
+
+
+
+
+
+
+
+
+
+ kriging_efficiency
+
+
+
+
kriging_efficiency : CreateAttribute | UpdateAttribute | None = None
+
+
+
+
+
The proportion of point or intra-block variance explained by the kriging weights.
+
+
+
+
+
+
+
+
+
+
+ kriging_mean
+
+
+
+
kriging_mean : CreateAttribute | UpdateAttribute | None = None
+
+
+
+
+
The GLS mean for ordinary kriging, or the supplied constant mean for simple kriging.
+
+
+
+
+
+
+
+
+
+
+ num_samples
+
+
+
+
num_samples : CreateAttribute | UpdateAttribute | None = None
+
+
+
+
+
The number of data samples used in the estimate.
+
+
+
+
+
+
+
+
+
+
+ num_drillholes
+
+
+
+
num_drillholes : CreateAttribute | UpdateAttribute | None = None
+
+
+
+
+
The number of distinct drillholes contributing to the estimate.
+
Requires a downhole intervals source object.
+
+
+
+
+
+
+
+
+
+
+ num_duplicates
+
+
+
+
num_duplicates : CreateAttribute | UpdateAttribute | None = None
+
+
+
+
+
The number of duplicate sample locations used in the estimate.
+
+
+
+
+
+
+
+
+
+
+ num_equidistant
+
+
+
+
num_equidistant : CreateAttribute | UpdateAttribute | None = None
+
+
+
+
+
A hint of how many other samples could have replaced the last returned sample
+because they were the same distance from the target location. Counted after searching
+and before clipping to the maximum number of samples.
+
+
+
+
+
+
+
+
+
+
+ sum_weights
+
+
+
+
sum_weights : CreateAttribute | UpdateAttribute | None = None
+
+
+
+
+
The sum of kriging weights applied to data samples.
+
+
+
+
+
+
+
+
+
+
+ sum_positive_weights
+
+
+
+
sum_positive_weights : CreateAttribute | UpdateAttribute | None = None
+
+
+
+
+
The sum of positive kriging weights applied to data samples.
+
+
+
+
+
+
+
+
+
+
+ sum_negative_weights
+
+
+
+
sum_negative_weights : CreateAttribute | UpdateAttribute | None = None
+
+
+
+
+
The sum of negative kriging weights applied to data samples (zero when
+negative-weight removal is enabled).
+
+
+
+
+
+
+
+
+
+
+ min_distance
+
+
+
+
min_distance : CreateAttribute | UpdateAttribute | None = None
+
+
+
+
+
The minimum isotropic Euclidean distance from the target location to any neighbour.
+
+
+
+
+
+
+
+
+
+
+ mean_distance
+
+
+
+
mean_distance : CreateAttribute | UpdateAttribute | None = None
+
+
+
+
+
The mean isotropic Euclidean distance from the target location to all neighbours.
+
+
+
+
+
+
+
+
+
+
+ aniso_min_distance
+
+
+
+
aniso_min_distance : CreateAttribute | UpdateAttribute | None = None
+
+
+
+
+
The minimum anisotropic (ellipsoid-space) distance from the target location to any neighbour.
+
+
+
+
+
+
+
+
+
+
+ aniso_mean_distance
+
+
+
+
aniso_mean_distance : CreateAttribute | UpdateAttribute | None = None
+
+
+
+
+
The mean anisotropic (ellipsoid-space) distance from the target location to all neighbours.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Keys
+ Action
+
+
+
+
+ ?
+ Open this help
+
+
+ n
+ Next page
+
+
+ p
+ Previous page
+
+
+ s
+ Search
+
+
+
+
+
+
+
+
+
+
+
diff --git a/mkdocs/site/packages/evo-compute/typed-objects/kriging/KrigingDiagnosticsResult.html b/mkdocs/site/packages/evo-compute/typed-objects/kriging/KrigingDiagnosticsResult.html
new file mode 100644
index 000000000..db77c20d9
--- /dev/null
+++ b/mkdocs/site/packages/evo-compute/typed-objects/kriging/KrigingDiagnosticsResult.html
@@ -0,0 +1,172 @@
+
+
+
+
+
+
+
+
+
+
+ KrigingDiagnosticsResult - Evo Python SDK
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
GitHub source
+
+
+
+
+
+
+
+
+ evo.compute.tasks.geostatistics.kriging.KrigingDiagnosticsResult
+
+
+
+
+
+
+
+
+
+
The diagnostic attributes that were written alongside the kriging estimate.
+
Diagnostics that were not requested come back as None.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Keys
+ Action
+
+
+
+
+ ?
+ Open this help
+
+
+ n
+ Next page
+
+
+ p
+ Previous page
+
+
+ s
+ Search
+
+
+
+
+
+
+
+
+
+
+
diff --git a/mkdocs/site/packages/evo-compute/typed-objects/kriging/KrigingTargetResult.html b/mkdocs/site/packages/evo-compute/typed-objects/kriging/KrigingTargetResult.html
new file mode 100644
index 000000000..cdd4c6fd1
--- /dev/null
+++ b/mkdocs/site/packages/evo-compute/typed-objects/kriging/KrigingTargetResult.html
@@ -0,0 +1,191 @@
+
+
+
+
+
+
+
+
+
+
+ KrigingTargetResult - Evo Python SDK
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
GitHub source
+
+
+
+
+
+
+
+
+ evo.compute.tasks.geostatistics.kriging.KrigingTargetResult
+
+
+
+
+
+
+
+
+
+
Target information from a kriging task result.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ diagnostics
+
+
+
+
diagnostics : KrigingDiagnosticsResult | None = None
+
+
+
+
+
The diagnostic attributes that were written, when any were requested.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Keys
+ Action
+
+
+
+
+ ?
+ Open this help
+
+
+ n
+ Next page
+
+
+ p
+ Previous page
+
+
+ s
+ Search
+
+
+
+
+
+
+
+
+
+
+
diff --git a/mkdocs/site/packages/evo-compute/typed-objects/kriging/RECOMMENDED_DIAGNOSTIC_NAMES.html b/mkdocs/site/packages/evo-compute/typed-objects/kriging/RECOMMENDED_DIAGNOSTIC_NAMES.html
new file mode 100644
index 000000000..e45691cd0
--- /dev/null
+++ b/mkdocs/site/packages/evo-compute/typed-objects/kriging/RECOMMENDED_DIAGNOSTIC_NAMES.html
@@ -0,0 +1,162 @@
+
+
+
+
+
+
+
+
+
+
+ RECOMMENDED DIAGNOSTIC NAMES - Evo Python SDK
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
GitHub source
+
+
+
+
+
+
+
+
+ evo.compute.tasks.geostatistics.kriging.RECOMMENDED_DIAGNOSTIC_NAMES
+
+
+
+
RECOMMENDED_DIAGNOSTIC_NAMES : dict [ str , str ] = {
+ "valid" : "valid" ,
+ "kriging_variance" : "KV" ,
+ "slope_of_regression" : "SoR" ,
+ "kriging_efficiency" : "KE" ,
+ "kriging_mean" : "KM" ,
+ "num_samples" : "NS" ,
+ "num_drillholes" : "NDh" ,
+ "num_duplicates" : "ND" ,
+ "num_equidistant" : "NeD" ,
+ "sum_weights" : "Sum" ,
+ "sum_positive_weights" : "SumP" ,
+ "sum_negative_weights" : "SumN" ,
+ "min_distance" : "MinD" ,
+ "mean_distance" : "AvgD" ,
+ "aniso_min_distance" : "MinAD" ,
+ "aniso_mean_distance" : "AvgAD" ,
+}
+
+
+
+
+
Recommended attribute name for each diagnostic, matching Leapfrog's naming convention.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Keys
+ Action
+
+
+
+
+ ?
+ Open this help
+
+
+ n
+ Next page
+
+
+ p
+ Previous page
+
+
+ s
+ Search
+
+
+
+
+
+
+
+
+
+
+
diff --git a/mkdocs/site/packages/evo-compute/typed-objects/search/SearchNeighborhood.html b/mkdocs/site/packages/evo-compute/typed-objects/search/SearchNeighborhood.html
index 530011b4e..d2fb02723 100644
--- a/mkdocs/site/packages/evo-compute/typed-objects/search/SearchNeighborhood.html
+++ b/mkdocs/site/packages/evo-compute/typed-objects/search/SearchNeighborhood.html
@@ -94,11 +94,11 @@
+
+
+
+
+
+
+
+
+ Attribute spec - Evo Python SDK
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
GitHub source
+
+
+
+
+
+
+
+ evo.compute.tasks.common.source_target.attribute_spec
+
+
+
+
attribute_spec ( attr : Any ) -> Any
+
+
+
+
+
Convert a typed attribute object to a create or update specification.
+
Existing attributes become an update operation referencing the attribute;
+pending attributes become a create operation carrying the attribute name.
+Any other value is passed through untouched so that already-constructed
+specifications (or dicts) validate normally.
+
Args:
+ attr: A typed attribute object, or an already-constructed specification.
+
Returns:
+ A :class:CreateAttribute or :class:UpdateAttribute for typed attributes,
+ otherwise attr unchanged.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Keys
+ Action
+
+
+
+
+ ?
+ Open this help
+
+
+ n
+ Next page
+
+
+ p
+ Previous page
+
+
+ s
+ Search
+
+
+
+
+
+
+
+
+
+
+