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.

+ +
+ +
+ + + + + + +
+ +
+ +
+
+
+ + + + + + 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.

+ +
+ +
+ + + + + + +
+ +
+ +
+
+
+ + + + + + 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 @@ 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.

+ +
+ +
+
+
+ + + + + + 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).

+ +
+ +
+ + + + + + +
+ +
+ +
+
+
+ + + + + + 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"].

+ +
+ +
+ + + + + + +
+ +
+ +
+
+
+ + + + + + 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 + + +

+
message: str
+
+ +
+ +

A message describing what happened in the task.

+ +
+ +
+ +
+ + + +

+ source + + +

+
source: CrossValidationSourceResult
+
+ +
+ +

Metadata and written attribute references for the updated source object.

+ +
+ +
+ +
+ + + +

+ source_name + + +

+
source_name: str
+
+ +
+ +

The name of the source object updated with cross-validation attributes.

+ +
+ +
+ +
+ + + +

+ source_reference + + +

+
source_reference: str
+
+ +
+ +

Reference URL to the updated source object.

+ +
+ +
+ +
+ + + +

+ estimate_attribute + + +

+
estimate_attribute: TaskAttribute
+
+ +
+ +

The attribute containing each sample's cross-validated estimate.

+ +
+ +
+ +
+ + + +

+ estimate_name + + +

+
estimate_name: str
+
+ +
+ +

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 + + +

+
error_name: str | None
+
+ +
+ +

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 + + +

+
schema: ObjectSchema
+
+ +
+ +

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.

+ + +
+ +
+ + + +
+ +
+ +
+
+
+ + + + + + 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 + + +

+
message: str
+
+ +
+ +

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).

+ +
+ +
+ + + + + + +
+ +
+ +
+
+
+ + + + + + 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)
+
+ + + + + + + + + + + +
+ + + + + + + + + + + + +
+ +
+ +
+
+
+ + + + + + 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.

+ +
+ +
+ + + + + + +
+ +
+ +
+
+
+ + + + + + 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: str
+
+ +
+ +

Reference URL to the updated source geoscience object.

+ +
+ +
+ +
+ + + +

+ name + + +

+
name: str
+
+ +
+ +

Name of the source geoscience object.

+ +
+ +
+ +
+ + + +

+ description + + +

+
description: str | None = None
+
+ +
+ +

Optional description of the source geoscience object.

+ +
+ +
+ +
+ + + +

+ schema_id + + +

+
schema_id: str
+
+ +
+ +

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.

+ +
+ +
+ + + + + + +
+ +
+ +
+
+
+ + + + + + 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 + + +

+
evaluated_count: int
+
+ +
+ +

Number of samples cross-validated after applying any source filter.

+ +
+ +
+ +
+ + + +

+ valid_count + + +

+
valid_count: int
+
+ +
+ +

Number of cross-validated samples that produced a finite estimate.

+ +
+ +
+ +
+ + + +

+ invalid_count + + +

+
invalid_count: int
+
+ +
+ +

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.

+ +
+ +
+ + + + + + +
+ +
+ +
+
+
+ + + + + + 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.

+ +
+ +
+ + + + + + +
+ +
+ +
+
+
+ + + + + + 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.

+ +
+ +
+ + + + + + +
+ +
+ +
+
+
+ + + + + + 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.

+ +
+ +
+ + + + + + +
+ +
+ +
+
+
+ + + + + + 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.

+ +
+ +
+ + + + + + +
+ +
+ +
+
+
+ + + + + + 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.

+ +
+ +
+ + + + + + +
+ +
+ +
+
+
+ + + + + + 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.

+ +
+ +
+ + + + + + +
+ +
+ +
+
+
+ + + + + + 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.

+ +
+ +
+
+
+ + + + + + 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 @@