apbase.kriging

High-level kriging API.

This package exports the public classes used to fit variogram models and run local ordinary kriging. Target-grid generation lives in apbase.grid.

class apbase.kriging.Kriging(*, radius=None, max_neighbors=40, min_neighbors=3, model_values=None)

Bases: object

Fit a variogram model and interpolate values with local ordinary kriging.

Stores finite source samples, fits or accepts a variogram model, and estimates target values with a local ordinary kriging kernel. Coordinates are not projected internally; pass projected/metric coordinates when radius is metric.

Parameters:

  • radius (float | None) – Local search radius. If None, kriging uses range from the selected variogram (range / 3 with 10 000 or more points).

  • max_neighbors (int) – Maximum source points used per target coordinate. Capped at apbase.config["max_neighbors_ceiling"] (default 500).

  • min_neighbors (int) – Minimum sources within radius; below it the max_neighbors nearest sources are used regardless of distance.

  • model_values (ArrayLike | None) – Optional native variogram model vector with five values. If provided, fit uses it instead of fitting a variogram from x, y, and z.

Examples

>>> import numpy as np
>>> from apbase.kriging import Kriging
>>> x = np.ascontiguousarray([0.0, 10.0, 0.0, 10.0])
>>> y = np.ascontiguousarray([0.0, 0.0, 10.0, 10.0])
>>> z = np.ascontiguousarray([5.0, 7.0, 8.0, 10.0])
>>> targets = np.ascontiguousarray([[5.0, 5.0]])
>>> values = Kriging(radius=20.0, min_neighbors=3).fit(x, y, z).interpolate(targets)
property radius: float | None

Local search radius.

Returns:

Explicit radius, or None to derive it from the variogram range during interpolation.

Return type:

float or None

property max_neighbors: int

Maximum source points used per target coordinate.

Returns:

Upper bound on local neighbors.

Return type:

int

property min_neighbors: int

Minimum sources within radius before the nearest-sources fallback.

Returns:

Lower bound on local neighbors.

Return type:

int

property n_threads: int

OpenMP thread count passed to native routines.

Resolved live from apbase.config["n_threads"] (see the class docstring) on every access – not cached at construction time.

Returns:

Current OpenMP thread count.

Return type:

int

classmethod from_data(x, y, z, **kwargs)

Create and fit a kriging interpolator.

Parameters:

  • x (array_like) – Source coordinates and values.

  • y (array_like) – Source coordinates and values.

  • z (array_like) – Source coordinates and values.

  • **kwargs – Keyword arguments forwarded to Kriging.

Returns:

Fitted kriging interpolator.

Return type:

Kriging

property is_fitted: bool

Whether source data and a variogram model are available.

Returns:

True after fit() succeeds.

Return type:

bool

property model_values: ndarray

Best fitted variogram model values.

Returns:

Native model vector used by the kriging kernel.

Return type:

numpy.ndarray

property model_params: dict[str, float | int | str]

Readable parameters for the selected variogram model.

Returns:

Model id/name, nugget, partial sill, sill, range, and SSE.

Return type:

dict

fit(x, y, z)

Store finite source data and fit or attach a variogram model.

Parameters:

  • x (ArrayLike) – One-dimensional source x coordinates.

  • y (ArrayLike) – One-dimensional source y coordinates. Must have the same length as x.

  • z (ArrayLike) – One-dimensional source values. Must have the same length as x and y.

Returns:

The fitted kriging interpolator. Rows where x, y, or z are NaN or infinite are ignored.

Return type:

Kriging

Raises:

ValueError – If input arrays have inconsistent size or fewer than min_neighbors finite rows.

Examples

>>> kriging = Kriging(radius=30.0, min_neighbors=3)
>>> kriging.fit(x, y, z)
>>> kriging.model_params["range"] > 0.0
True
>>> kriging = Kriging(model_values=model_values, radius=30.0).fit(x, y, z)
interpolate(targets)

Estimate values at target coordinates.

Parameters:

targets (Grid | ArrayLike) – Target coordinates as an (n_targets, 2) array, where column 0 is x and column 1 is y. A fitted Grid, GeoDataFrame/GeoSeries, or list of Point-like objects is also accepted; these are parsed by the shared extract_target_xy helper.

Returns:

One-dimensional float64 array with one kriging estimate per target coordinate. Targets with fewer than min_neighbors sources within radius use the max_neighbors nearest ones.

Return type:

numpy.ndarray

Examples

>>> targets = np.ascontiguousarray([[5.0, 5.0], [20.0, 20.0]])
>>> values = kriging.interpolate(targets)
predict(targets)

Estimate values at target coordinates.

Parameters:

targets (Grid or array_like) – Target coordinates accepted by interpolate().

Returns:

One kriging estimate per target coordinate.

Return type:

numpy.ndarray

fit_interpolate(x, y, z, targets)

Fit the interpolator and immediately estimate target values.

Parameters:

  • x (array_like) – Source coordinates and values.

  • y (array_like) – Source coordinates and values.

  • z (array_like) – Source coordinates and values.

  • targets (Grid or array_like) – Target coordinates accepted by interpolate().

Returns:

One kriging estimate per target coordinate.

Return type:

numpy.ndarray

apbase.kriging.ordinary_kriging(x, y, z, targets, *, model_values=None, radius=None, max_neighbors=40, min_neighbors=3, return_diagnostics=False)

Fit local ordinary kriging and estimate targets values.

This is a one-shot convenience wrapper around Kriging for callers who just want a single fit-and-interpolate call. Prefer instantiating Kriging directly when reusing the same fitted variogram across multiple interpolate calls, since this function always fits from scratch.

Parameters:

  • x (array_like) – Source coordinates and values.

  • y (array_like) – Source coordinates and values.

  • z (array_like) – Source coordinates and values.

  • targets (array_like) – Target coordinates accepted by apbase.kriging.Kriging.interpolate().

  • model_values (array_like or None, default None) – Optional native variogram model vector. If omitted, a variogram is fitted from x, y, and z.

  • radius (float or None, default None) – Local search radius. If None, derive range from the selected variogram (range / 3 with 10 000 or more points).

  • max_neighbors (int) – Neighbor bounds used by the local search.

  • min_neighbors (int) – Neighbor bounds used by the local search.

  • return_diagnostics (bool, default False) – If True, return interpolation diagnostics with the estimates.

Returns:

Estimates only, or (estimates, diagnostics) when return_diagnostics=True.

Return type:

numpy.ndarray or tuple[numpy.ndarray, dict]

apbase.kriging also re-exports apbase.variogram.Variogram; see apbase.variogram for its documentation.