Add kriging diagnostic outputs to the task SDK client

code-samples/geoscience-objects/running-kriging-compute/README.md

@@ -38,6 +38,7 @@ The variogram uses two nested spherical structures aligned with the dominant ori
 The notebook includes work-in-progress sections demonstrating:
 - Creating a target `BlockModel` for estimation
 - Configuring `KrigingParameters` with search neighborhoods
+- Requesting `KrigingDiagnostics` (kriging variance, slope of regression, sample counts, ...) alongside the estimate
 - Running kriging tasks with `evo.compute`
 - Running multiple scenarios in parallel for sensitivity analysis
 

code-samples/geoscience-objects/running-kriging-compute/running-kriging-compute.ipynb

@@ -621,7 +621,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from evo.compute.tasks import SearchNeighborhood\n",
+    "from evo.compute.tasks import KrigingDiagnostics, SearchNeighborhood\n",
     "from evo.compute.tasks.geostatistics.kriging import KrigingParameters\n",
     "\n",
     "# Use the search ellipsoid we created earlier (2x variogram range)\n",
@@ -634,12 +634,62 @@
     "        max_samples=16,  # Maximum samples per estimate\n",
     "        min_samples=4,  # Minimum samples required\n",
     "    ),\n",
+    "    # Write diagnostics next to the estimate, using the recommended names\n",
+    "    diagnostics=KrigingDiagnostics(\n",
+    "        kriging_variance=True,  # -> \"KV\"\n",
+    "        slope_of_regression=True,  # -> \"SoR\"\n",
+    "        num_samples=True,  # -> \"NS\"\n",
+    "    ),\n",
     ")\n",
     "\n",
     "print(\"Kriging source: CU_pct from pointset\")\n",
     "print(f\"Search ellipsoid: major={search_ellipsoid.ranges.major}m\")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Optional: request kriging diagnostics\n",
+    "\n",
+    "Kriging can write per-location **diagnostics** onto the target object alongside the estimate. Only the diagnostics you ask for are computed, and each one gets its own attribute — so every name must differ from the estimate's attribute name and from the other diagnostics.\n",
+    "\n",
+    "Each field of `KrigingDiagnostics` accepts:\n",
+    "\n",
+    "- `True` — create an attribute using the recommended name (these match Leapfrog's conventions, so results are familiar once imported).\n",
+    "- a string — create an attribute with that name instead.\n",
+    "- an attribute from the target object — update it if it already exists, otherwise create it.\n",
+    "\n",
+    "```python\n",
+    "from evo.compute.tasks import KrigingDiagnostics\n",
+    "\n",
+    "diagnostics = KrigingDiagnostics(\n",
+    "    kriging_variance=True,  # creates \"KV\"\n",
+    "    kriging_efficiency=\"CU_efficiency\",  # creates \"CU_efficiency\"\n",
+    "    num_samples=block_model.attributes[\"NS\"],  # updates \"NS\" if it already exists\n",
+    ")\n",
+    "```\n",
+    "\n",
+    "| Diagnostic | Recommended name | Description |\n",
+    "| --- | --- | --- |\n",
+    "| `valid` | `valid` | Whether the location's neighbourhood satisfied the search constraints and produced an estimate. |\n",
+    "| `kriging_variance` | `KV` | Kriging variance (estimation uncertainty). |\n",
+    "| `slope_of_regression` | `SoR` | Slope of regression, a diagnostic for conditional bias. |\n",
+    "| `kriging_efficiency` | `KE` | Proportion of point or intra-block variance explained by the kriging weights. |\n",
+    "| `kriging_mean` | `KM` | GLS mean for ordinary kriging, or the supplied constant mean for simple kriging. |\n",
+    "| `num_samples` | `NS` | Number of data samples used in the estimate. |\n",
+    "| `num_drillholes` | `NDh` | Number of distinct drillholes contributing to the estimate. Requires a downhole-intervals source. |\n",
+    "| `num_duplicates` | `ND` | Number of duplicate sample locations used in the estimate. |\n",
+    "| `num_equidistant` | `NeD` | Hint of how many other samples could have replaced the last returned sample because they were the same distance away. |\n",
+    "| `sum_weights` | `Sum` | Sum of the kriging weights applied to data samples. |\n",
+    "| `sum_positive_weights` | `SumP` | Sum of the positive kriging weights. |\n",
+    "| `sum_negative_weights` | `SumN` | Sum of the negative kriging weights. |\n",
+    "| `min_distance` | `MinD` | Minimum isotropic Euclidean distance from the location to any neighbour. |\n",
+    "| `mean_distance` | `AvgD` | Mean isotropic Euclidean distance from the location to all neighbours. |\n",
+    "| `aniso_min_distance` | `MinAD` | Minimum anisotropic (ellipsoid-space) distance from the location to any neighbour. |\n",
+    "| `aniso_mean_distance` | `AvgAD` | Mean anisotropic (ellipsoid-space) distance from the location to all neighbours. |\n"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -692,7 +742,12 @@
     "result = await run(manager, params, preview=True)\n",
     "\n",
     "print(\"Kriging complete!\")\n",
-    "print(f\"Result: {result.message}\")"
+    "print(f\"Result: {result.message}\")\n",
+    "print(f\"Estimate attribute: {result.attribute_name}\")\n",
+    "\n",
+    "# The result reports the definitive name of every diagnostic attribute that was written\n",
+    "for diagnostic, attribute in result.diagnostics.items():\n",
+    "    print(f\"  {diagnostic}: {attribute.name}\")"
    ]
   },
   {
@@ -743,12 +798,16 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Get the kriged values as a DataFrame\n",
-    "results_df = await block_model.to_dataframe(columns=[\"CU_estimate\"])\n",
+    "# Get the kriged values and their diagnostics as a DataFrame\n",
+    "diagnostic_columns = [attribute.name for attribute in result.diagnostics.values()]\n",
+    "results_df = await block_model.to_dataframe(columns=[\"CU_estimate\", *diagnostic_columns])\n",
     "\n",
     "print(f\"Estimated {len(results_df)} blocks\")\n",
     "print(\"\\nStatistics for CU_estimate:\")\n",
-    "print(results_df[\"CU_estimate\"].describe())"
+    "print(results_df[\"CU_estimate\"].describe())\n",
+    "\n",
+    "print(\"\\nDiagnostics:\")\n",
+    "print(results_df[diagnostic_columns].describe())"
    ]
   },
   {

mkdocs/site/packages/evo-compute/typed-objects/kriging/KrigingMethod.html

@@ -34,7 +34,7 @@
 
                     <ul class="nav navbar-nav ms-md-auto">
                             <li class="nav-item">
-                                <a rel="prev" href="Filter.html" class="nav-link">
+                                <a rel="prev" href="KrigingDiagnosticsResult.html" class="nav-link">
                                     <i class="fa fa-arrow-left"></i> Previous
                                 </a>
                             </li>

mkdocs/site/packages/evo-compute/typed-objects/kriging/KrigingParameters.html

@@ -120,6 +120,15 @@ <h2 id="evo.compute.tasks.geostatistics.kriging.KrigingParameters" class="doc do
     ...             values=["LMS1", "LMS2"],
     ...         ),
     ...     ),
+    ... )
+    &gt;&gt;&gt;
+    &gt;&gt;&gt; # With diagnostics written alongside the estimate:
+    &gt;&gt;&gt; params_with_diagnostics = KrigingParameters(
+    ...     source=pointset.attributes["grade"],
+    ...     target=block_model.attributes["kriged_grade"],
+    ...     variogram=variogram,
+    ...     search=SearchNeighborhood(...),
+    ...     diagnostics=KrigingDiagnostics(kriging_variance=True, num_samples=True),
     ... )</p>
 
 
@@ -304,6 +313,28 @@ <h3 id="evo.compute.tasks.geostatistics.kriging.KrigingParameters.block_discreti
 
 </div>
 
+<div class="doc doc-object doc-attribute">
+
+
+
+<h3 id="evo.compute.tasks.geostatistics.kriging.KrigingParameters.diagnostics" class="doc doc-heading">
+            <span class="doc doc-object-name doc-attribute-name">diagnostics</span>
+
+
+</h3>
+<div class="doc-signature highlight"><pre><span></span><code><span class="n">diagnostics</span><span class="p">:</span> <span class="n">KrigingDiagnostics</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="n">Field</span><span class="p">(</span><span class="kc">None</span><span class="p">,</span> <span class="n">exclude</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
+</code></pre></div>
+
+    <div class="doc doc-contents ">
+
+        <p>Optional diagnostics to write onto the target object alongside the estimate.</p>
+<p>Only the diagnostics you select are computed. See :class:<code>KrigingDiagnostics</code>
+for the available outputs and the shorthands each of them accepts.</p>
+
+    </div>
+
+</div>
+
 
 
 

mkdocs/site/packages/evo-compute/typed-objects/kriging/KrigingResult.html

@@ -191,6 +191,32 @@ <h3 id="evo.compute.tasks.geostatistics.kriging.KrigingResult.attribute_name" cl
 
 
 
+<h3 id="evo.compute.tasks.geostatistics.kriging.KrigingResult.diagnostics" class="doc doc-heading">
+            <span class="doc doc-object-name doc-attribute-name">diagnostics</span>
+
+
+</h3>
+<div class="doc-signature highlight"><pre><span></span><code><span class="n">diagnostics</span><span class="p">:</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">TaskAttribute</span><span class="p">]</span>
+</code></pre></div>
+
+    <div class="doc doc-contents ">
+
+        <p>The diagnostic attributes that were written, keyed by diagnostic name.</p>
+<p>Only the diagnostics requested through
+:attr:<code>KrigingParameters.diagnostics</code> are present.</p>
+<p>Example:
+    &gt;&gt;&gt; result = await run(manager, params, preview=True)
+    &gt;&gt;&gt; result.diagnostics["kriging_variance"].name
+    'KV'</p>
+
+    </div>
+
+</div>
+
+<div class="doc doc-object doc-attribute">
+
+
+
 <h3 id="evo.compute.tasks.geostatistics.kriging.KrigingResult.schema" class="doc doc-heading">
             <span class="doc doc-object-name doc-attribute-name">schema</span>
 

mkdocs/site/packages/evo-compute/typed-objects/kriging/KrigingResultModel.html

@@ -142,7 +142,7 @@ <h3 id="evo.compute.tasks.geostatistics.kriging.KrigingResultModel.target" class
 
 
 </h3>
-<div class="doc-signature highlight"><pre><span></span><code><span class="n">target</span><span class="p">:</span> <span class="n">TaskTarget</span>
+<div class="doc-signature highlight"><pre><span></span><code><span class="n">target</span><span class="p">:</span> <span class="n">KrigingTargetResult</span>
 </code></pre></div>
 
     <div class="doc doc-contents ">

mkdocs/site/packages/evo-compute/typed-objects/kriging/KrigingRunner.html

@@ -39,7 +39,7 @@
                                 </a>
                             </li>
                             <li class="nav-item">
-                                <a rel="next" href="OrdinaryKriging.html" class="nav-link">
+                                <a rel="next" href="KrigingTargetResult.html" class="nav-link">
                                     Next <i class="fa fa-arrow-right"></i>
                                 </a>
                             </li>

mkdocs/site/packages/evo-compute/typed-objects/kriging/OrdinaryKriging.html

@@ -34,12 +34,12 @@
 
                     <ul class="nav navbar-nav ms-md-auto">
                             <li class="nav-item">
-                                <a rel="prev" href="KrigingRunner.html" class="nav-link">
+                                <a rel="prev" href="KrigingTargetResult.html" class="nav-link">
                                     <i class="fa fa-arrow-left"></i> Previous
                                 </a>
                             </li>
                             <li class="nav-item">
-                                <a rel="next" href="SimpleKriging.html" class="nav-link">
+                                <a rel="next" href="RECOMMENDED_DIAGNOSTIC_NAMES.html" class="nav-link">
                                     Next <i class="fa fa-arrow-right"></i>
                                 </a>
                             </li>

mkdocs/site/packages/evo-compute/typed-objects/kriging/SimpleKriging.html

@@ -34,7 +34,7 @@
 
                     <ul class="nav navbar-nav ms-md-auto">
                             <li class="nav-item">
-                                <a rel="prev" href="OrdinaryKriging.html" class="nav-link">
+                                <a rel="prev" href="RECOMMENDED_DIAGNOSTIC_NAMES.html" class="nav-link">
                                     <i class="fa fa-arrow-left"></i> Previous
                                 </a>
                             </li>

mkdocs/site/packages/evo-compute/typed-objects/source-target/UpdateAttribute.html

@@ -39,7 +39,7 @@
                                 </a>
                             </li>
                             <li class="nav-item">
-                                <a rel="next" href="../../../evo-files/index.html" class="nav-link">
+                                <a rel="next" href="attribute_spec.html" class="nav-link">
                                     Next <i class="fa fa-arrow-right"></i>
                                 </a>
                             </li>

mkdocs/site/packages/evo-files/index.html

@@ -34,7 +34,7 @@
 
                     <ul class="nav navbar-nav ms-md-auto">
                             <li class="nav-item">
-                                <a rel="prev" href="../evo-compute/typed-objects/source-target/UpdateAttribute.html" class="nav-link">
+                                <a rel="prev" href="../evo-compute/typed-objects/source-target/attribute_spec.html" class="nav-link">
                                     <i class="fa fa-arrow-left"></i> Previous
                                 </a>
                             </li>