Kriging

Kriging is a geostatistical interpolation method that estimates values at unknown locations on a variogram weighted average of the nearby data values. This compute task can be parameterized to perform simple or ordinary kriging.

Parameters

source (object)
- object (geoscience object reference)
  - Reference to a geoscience object containing the spatial locations of known values. Must be a pointset, downhole-intervals, regular-3d-grid, regular-masked-3d-grid, or tensor-3d-grid with schema version 1.2.0 or 1.3.0; or a block-model with schema version 1.0.0.
- attribute (geoscience object attribute reference)
  - Reference to a one-dimensional continuous attribute inside source_object that contains the known values to be interpolated.
- ```
{
  "object": "https://{hub}.api.seequent.com/geoscience-object/orgs/{org_id}/workspaces/{workspace_id}/objects/path/my-pointset.json",
  "attribute": "locations.attributes[?name=='my-attribute']",
}
```

target (object)

object (geoscience object reference)
- Reference to the geoscience object where kriging results will be stored. A new attribute containing the interpolated values will be created on this object. Must be a pointset, downhole-intervals, regular-3d-grid, regular-masked-3d-grid, tensor-3d-grid with schema version 1.2.0 or 1.3.0; or a block-model with schema version 1.0.0.
attribute (geoscience object attribute target)
- Reference that points to an attribute inside target_object where the kriging results will be saved.
update_mode (string, optional, one of auto, merge, replace; defaults to auto)
- Controls what happens to target locations this run did not estimate. See Estimating one domain at a time.

{
  "object": "https://{hub}.api.seequent.com/geoscience-object/orgs/{org_id}/workspaces/{workspace_id}/objects/path/my-pointset.json",
  "attribute": {
      "operation": "create",
      "name": "my-kriging-result"
  },
}

diagnostics (object, optional)

Per-location diagnostics to compute and write alongside the estimate. Each entry is a geoscience object attribute target, and only the diagnostics you name are computed. Every diagnostic writes to its own attribute, so each one must use a name that is not already used by another output of the same request.

The recommended names below match the Leapfrog conventions, so results imported into Leapfrog are familiar. They are suggestions only: any valid attribute name is accepted.

Diagnostic	Recommended name	Description
`valid`	`valid`	Whether the location's neighbourhood satisfied the search constraints and produced an estimate.
`kriging_variance`	`KV`	Kriging variance (estimation uncertainty).
`slope_of_regression`	`SoR`	Slope of regression, a diagnostic for conditional bias.
`kriging_efficiency`	`KE`	Proportion of point or intra-block variance explained by the kriging weights.
`kriging_mean`	`KM`	GLS mean for ordinary kriging, or the supplied constant mean for simple kriging.
`num_samples`	`NS`	Number of data samples used in the estimate.
`num_drillholes`	`NDh`	Number of distinct drillholes contributing to the estimate. Requires a downhole-intervals source.
`num_duplicates`	`ND`	Number of duplicate sample locations used in the estimate.
`num_equidistant`	`NeD`	Hint of how many other samples could have replaced the last returned sample because they were the same distance from the location. Counted after searching and before clipping to `max_samples`.
`sum_weights`	`Sum`	Sum of the kriging weights applied to data samples.
`sum_positive_weights`	`SumP`	Sum of the positive kriging weights.
`sum_negative_weights`	`SumN`	Sum of the negative kriging weights (zero when negative-weight removal is enabled).
`min_distance`	`MinD`	Minimum isotropic Euclidean distance from the location to any neighbour.
`mean_distance`	`AvgD`	Mean isotropic Euclidean distance from the location to all neighbours.
`aniso_min_distance`	`MinAD`	Minimum anisotropic (ellipsoid-space) distance from the location to any neighbour.
`aniso_mean_distance`	`AvgAD`	Mean anisotropic (ellipsoid-space) distance from the location to all neighbours.

{
  "diagnostics": {
    "kriging_variance": {
      "operation": "create",
      "name": "KV"
    },
    "num_samples": {
      "operation": "create",
      "name": "NS"
    }
  }
}

kriging_method (object)

The kriging method to use for interpolation. There are two supported methods.

Simple kriging:

{
  "type": "simple",
  "mean": 5.2  // The constant mean value assumed across the domain
}

Ordinary kriging:

{
  "type": "ordinary"  // Variable mean value estimated from the data
}

variogram (geoscience object reference)
- Reference to a variogram geoscience object that describes the spatial covariance structure within the domain. Must use schema version 1.1.0.

neighborhood (object)

Search parameters that determine which nearby points to use for each evaluation point during kriging interpolation.

{
  "ellipsoid": {
    "ellipsoid_ranges": {
      "major": 100.0,      // Major axis length of the search ellipsoid
      "semi_major": 75.0,  // Semi-major axis length
      "minor": 50.0        // Minor axis length
    },
    "rotation": {
      "dip_azimuth": 45.0, // First rotation about z-axis (0-360 degrees)
      "dip": 30.0,         // Second rotation about x-axis (0-180 degrees)
      "pitch": 0.0         // Third rotation about z-axis (0-360 degrees)
    }
  },
  "max_samples": 15        // Maximum number of nearby samples to use
}

block_discretization (object, optional)
- Sub-block discretization for block kriging. When provided, each target block is subdivided into x × y × z sub-cells and the kriged value is averaged across these sub-cells. When omitted, point kriging is performed at the block centroids.
- Note: This parameter is only applicable when the target is a 3D grid (regular-3d-grid, regular-masked-3d-grid, tensor-3d-grid) or block-model. An error will be raised if used with pointset or downhole-intervals targets.
- ```
{
  "nx": 2,  // Number of sub-cells in the x-direction (1-9)
  "ny": 2,  // Number of sub-cells in the y-direction (1-9)
  "nz": 2   // Number of sub-cells in the z-direction (1-9)
}
```

Estimating one domain at a time

A common workflow is to run kriging once per domain, each run using target.filter to select that domain's locations, and write every run into the same attribute. target.update_mode controls what happens to the locations a run did not estimate.

auto (default) — merge when target.filter is set, replace otherwise. This is what you want for the workflow above: each run leaves the other domains' results untouched, and the final version holds every domain.
merge — always leave locations this run did not estimate at their previous values.
replace — always clear them, so the attribute only ever holds the results of the latest run.

After the first run, point target.attribute at the attribute the previous run wrote ("operation": "update"). Merging preserves what is already stored in that attribute, so a run that creates a new one has nothing to merge with.

Block model targets merge in BlockSync. Every other target type is written as a whole document, so the task reads the attribute's current values back and merges them itself, which costs one extra download per attribute.

"Did not estimate" covers both locations the filter excluded and locations inside the filter where the neighbourhood search found no samples. The boolean and integer diagnostics (valid_attribute, sample_count_attribute, num_*_attribute) are the exception: they have no way to represent "not estimated", so inside the filter they are always written as produced.

Run the domains sequentially. Each run builds on the version the previous one produced, so concurrent runs can overwrite each other.

Example

For more information, see the kriging API reference.

Request

requests.post(
    "https://{hub}.api.seequent.com/compute/orgs/{org_id}/geostatistics/kriging",
    headers={"Authorization": "Bearer {token}"},
    json={
        "source": {
          "object": "https://{hub}.api.seequent.com/geoscience-object/orgs/{org_id}/workspaces/{workspace_id}/objects/path/my-pointset.json",
          "attribute": "locations.attributes[?name=='my-attribute']",
        },
        "target": {
          "object": "https://{hub}.api.seequent.com/geoscience-object/orgs/{org_id}/workspaces/{workspace_id}/objects/path/my-pointset.json",
          "attribute": {
              "operation": "create",
              "name": "my-kriging-result"
          },
        },
        "kriging_method": {
            "type": "simple",
            "mean": 10.5
        },
        "variogram": "https://{hub}.api.seequent.com/geoscience-object/orgs/{org_id}/workspaces/{workspace_id}/objects/path/my-variogram.json",
        "neighborhood": {
            "ellipsoid": {
                "ellipsoid_ranges": {
                    "major": 100.0,
                    "semi_major": 50.0,
                    "minor": 20.0
                },
                "rotation": {
                    "dip_azimuth": 45.0,
                    "dip": 30.0,
                    "pitch": 10.0
                }
            },
            "max_samples": 50,
            "min_samples": 10,
            "max_empty_octants": 0,
        },
    },
)

Result

{
    "message": "Kriging completed.",
    "target": {
       "reference": "https://{hub}.api.seequent.com/geoscience-object/orgs/{org_id}/workspaces/{workspace_id}/objects/path/my-pointset.json"
       "name": "My Pointset",
       "description": "A new description for my pointset.",
       "schema_id": "/objects/pointset/1.3.0",
       "attribute": {
         "reference": "locations.attributes[?key=='3cc3aa58-c928-4e79-b8ca-550174bff59e']",
         "name": "my-kriging-result"
      }
    }
}

Block Kriging Example

When the target is a 3D grid or block model, you can use block_discretization to perform block kriging instead of point kriging:

requests.post(
    "https://{hub}.api.seequent.com/compute/orgs/{org_id}/geostatistics/kriging",
    headers={"Authorization": "Bearer {token}"},
    json={
        "source": {
          "object": "https://{hub}.api.seequent.com/geoscience-object/orgs/{org_id}/workspaces/{workspace_id}/objects/path/my-pointset.json",
          "attribute": "locations.attributes[?name=='my-attribute']",
        },
        "target": {
          "object": "https://{hub}.api.seequent.com/geoscience-object/orgs/{org_id}/workspaces/{workspace_id}/objects/path/my-grid.json",
          "attribute": {
              "operation": "create",
              "name": "my-block-kriging-result"
          },
        },
        "kriging_method": {
            "type": "ordinary"
        },
        "variogram": "https://{hub}.api.seequent.com/geoscience-object/orgs/{org_id}/workspaces/{workspace_id}/objects/path/my-variogram.json",
        "neighborhood": {
            "ellipsoid": {
                "ellipsoid_ranges": {
                    "major": 100.0,
                    "semi_major": 50.0,
                    "minor": 20.0
                },
                "rotation": {
                    "dip_azimuth": 45.0,
                    "dip": 30.0,
                    "pitch": 10.0
                }
            },
            "max_samples": 50,
            "min_samples": 10,
        },
        "block_discretization": {
            "nx": 3,
            "ny": 3,
            "nz": 2
        },
    },
)

Diagnostics Example

Request the diagnostics you need by naming an attribute target for each one. The response reports the definitive name and reference of every attribute that was written, including the diagnostics:

requests.post(
    "https://{hub}.api.seequent.com/compute/orgs/{org_id}/geostatistics/kriging",
    headers={"Authorization": "Bearer {token}"},
    json={
        # ... source, kriging_method, variogram and neighborhood as above
        "target": {
          "object": "https://{hub}.api.seequent.com/geoscience-object/orgs/{org_id}/workspaces/{workspace_id}/objects/path/my-pointset.json",
          "attribute": {
              "operation": "create",
              "name": "my-kriging-result"
          },
          "diagnostics": {
              "kriging_variance": {"operation": "create", "name": "KV"},
              "num_samples": {"operation": "create", "name": "NS"},
          },
        },
    },
)

{
    "message": "Kriging completed.",
    "target": {
       "reference": "https://{hub}.api.seequent.com/geoscience-object/orgs/{org_id}/workspaces/{workspace_id}/objects/path/my-pointset.json",
       "name": "My Pointset",
       "schema_id": "/objects/pointset/1.3.0",
       "attribute": {
         "reference": "locations.attributes[?key=='3cc3aa58-c928-4e79-b8ca-550174bff59e']",
         "name": "my-kriging-result"
       },
       "diagnostics": {
         "kriging_variance": {
           "reference": "locations.attributes[?key=='0f0f4d7e-6e6a-4f0b-9a2f-8b2f2f1c1a11']",
           "name": "KV"
         },
         "num_samples": {
           "reference": "locations.attributes[?key=='5a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9']",
           "name": "NS"
         },
         "slope_of_regression": null
         // ... every diagnostic that was not requested is null
       }
    }
}

Parameters​

Estimating one domain at a time​

Example​

Request​

Result​

Block Kriging Example​

Diagnostics Example​