apbase.cokriging

High-level cokriging API.

Estimates a primary variable using one or more spatially correlated secondary variables. Run apbase.cross_variogram. screen_secondary_variables() first to select admissible secondaries.

class apbase.cokriging.CoKriging(*, method='collocated', radius=None, max_neighbors=40, min_neighbors=3, n_structures=2, model_values=None, max_colocation_dist=None, max_secondary_neighbors=None)

Bases: object

Fit a coregionalization model and interpolate values with cokriging.

Estimates a primary variable using one or more spatially correlated secondary variables (e.g. NDVI/elevation/soil EC alongside a sparse yield sample). Run screen_secondary_variables() first to pick admissible secondaries – CoKriging does not screen its inputs itself.

Parameters:

  • method (str) – "collocated", "icm" (Intrinsic Coregionalization Model), or "lmc" (full Linear Model of Coregionalization).

  • radius (float | None) – Local search radius for the primary neighborhood. If None, uses range from the primary’s variogram (range / 3 with 10 000 or more points). With fewer than min_neighbors primary sources within it, a target uses the max_neighbors nearest ones. For method="collocated", a secondary with no value within this radius of a target is left out of that target’s system (none left: ordinary kriging of the primary); "icm"/"lmc" search each variable’s neighborhood independently.

  • max_neighbors (int) – Primary neighbor bounds, same meaning as Kriging.

  • min_neighbors (int) – Primary neighbor bounds, same meaning as Kriging.

  • n_structures (int) – method="lmc" only: number of nested coregionalization structures, including the nugget. Default 2.

  • model_values (ArrayLike | None) – Optional pre-fitted coregionalization model vector, "collocated" only. If provided, fit() skips fitting the primary variogram and per-secondary cross-variograms.

  • max_colocation_dist (float | None) – Distance within which a primary sample is paired with its nearest secondary point to estimate the cross-covariances. None pairs only exactly coincident locations; heterotopic secondaries, such as rasters, need a distance (e.g. half the cell diagonal).

  • max_secondary_neighbors (int | None) – "icm"/"lmc" only: maximum neighbors of each secondary per target. None uses max_neighbors. Dense secondaries need far fewer than the primary, since the nearest ones screen the rest.

property method: str

Cokriging method used by the fitted interpolator.

Returns:

One of "collocated", "icm", or "lmc".

Return type:

str

property radius: float | None

Local search radius for primary neighborhoods.

Returns:

Explicit radius, or None when the radius is derived from the primary variogram range during interpolation.

Return type:

float or None

property max_neighbors: int

Maximum primary neighbors used per target coordinate.

Returns:

Upper bound on local primary neighbors.

Return type:

int

property min_neighbors: int

Minimum primary sources within radius before the nearest-sources fallback.

Returns:

Lower bound on local primary neighbors.

Return type:

int

property n_structures: int

Number of nested LMC structures.

Returns:

Structure count used only when method="lmc".

Return type:

int

property max_colocation_dist: float | None

Pairing distance between primary samples and secondary points.

Returns:

Distance used to estimate the cross-covariances, or None for exactly coincident locations only.

Return type:

float or None

property max_secondary_neighbors: int | None

Maximum neighbors of each secondary per target (ICM and LMC).

Returns:

Explicit limit, or None to use max_neighbors.

Return type:

int or None

property n_threads: int

OpenMP thread count used by native cokriging kernels.

Returns:

Current value resolved from apbase.config.

Return type:

int

classmethod from_data(x0, y0, z0, secondaries, **kwargs)

Create and fit a cokriging interpolator.

Parameters:

  • x0 (array_like) – Primary variable source coordinates and values.

  • y0 (array_like) – Primary variable source coordinates and values.

  • z0 (array_like) – Primary variable source coordinates and values.

  • secondaries (mapping or sequence) – Secondary variables accepted by fit().

  • **kwargs – Keyword arguments forwarded to CoKriging.

Returns:

Fitted cokriging interpolator.

Return type:

CoKriging

property is_fitted: bool

Whether a coregionalization model has been fitted.

Returns:

True after fit() succeeds.

Return type:

bool

property model_values: ndarray

Native coregionalization model vector.

"collocated": [model_id, nugget, partial_sill, range, sse, rho_1..rho_K]. "icm": [model_id, range, nugget_matrix.ravel(), sill_matrix.ravel()]. "lmc": [model_id, structure_ranges, coefficient_matrices.ravel()]. Flattened for a single-vector view in every case – see model_params for the actual matrices.

Returns:

Flattened native model vector for the fitted method.

Return type:

numpy.ndarray

property model_params: dict[str, Any]

Readable fitted parameters – shape differs by method.

"collocated": {"primary": {...}, "rho": {name: rho, ...}}. "icm": {"primary": {...}, "model_id", "model_name", "range", "secondary_names", "nugget_matrix", "sill_matrix"}. "lmc": {"primary": {...}, "model_id", "model_name", "structure_ranges", "secondary_names", "coefficient_matrices"} (coefficient_matrices has shape (n_structures, K+1, K+1), index 0 = nugget structure). Variable 0 of every matrix is the primary, 1..K follow secondary_names order.

Returns:

Method-specific fitted parameters. Matrix-valued entries are returned as numpy.ndarray without copying.

Return type:

dict

fit(x0, y0, z0, secondaries)

Fit the coregionalization model from source data.

Parameters:

  • x0 (array_like) – Primary variable source coordinates and values.

  • y0 (array_like) – Primary variable source coordinates and values.

  • z0 (array_like) – Primary variable source coordinates and values.

  • secondaries (mapping or sequence) – Mapping of name to (x, y, z) source arrays, or a sequence of (x, y, z) tuples. Sequence inputs are named "secondary_1", "secondary_2", and so on.

Returns:

Fitted interpolator. Rows where any primary or secondary coordinate/value is NaN or infinite are ignored within that variable.

Return type:

CoKriging

Raises:

  • ValueError – If inputs have inconsistent sizes, too few finite primary points, no usable secondary variables, invalid neighbor bounds, or zero-variance variables.

  • NativeExecutionError – If the native cokriging fit reports a failure status.

interpolate(targets)

Estimate primary values at target coordinates.

Parameters:

targets (Grid | ArrayLike) – Target coordinates, same accepted forms as interpolate().

Returns:

One estimate per target. A target with fewer than min_neighbors primary sources within radius uses the max_neighbors nearest ones; for method="collocated", a secondary with no source point within radius of it is left out (see the class docstring).

Return type:

numpy.ndarray

predict(targets)

Estimate primary values at target coordinates.

Parameters:

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

Returns:

One cokriging estimate per target coordinate.

Return type:

numpy.ndarray

fit_interpolate(x0, y0, z0, secondaries, targets)

Fit the interpolator and immediately estimate target values.

Parameters:

  • x0 (array_like) – Primary variable source coordinates and values.

  • y0 (array_like) – Primary variable source coordinates and values.

  • z0 (array_like) – Primary variable source coordinates and values.

  • secondaries (mapping or sequence) – Secondary variables accepted by fit().

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

Returns:

One cokriging estimate per target coordinate.

Return type:

numpy.ndarray

apbase.cokriging.co_kriging(x0, y0, z0, secondaries, targets, *, method='collocated', model_values=None, radius=None, max_neighbors=40, min_neighbors=3, max_colocation_dist=None, max_secondary_neighbors=None)

Fit cokriging and estimate targets values in one call.

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

Parameters:

  • x0 (array_like) – Primary variable source coordinates and values.

  • y0 (array_like) – Primary variable source coordinates and values.

  • z0 (array_like) – Primary variable source coordinates and values.

  • secondaries (mapping or sequence) – Secondary variables accepted by apbase.cokriging.CoKriging.fit().

  • targets (array_like) – Target coordinates accepted by apbase.cokriging.CoKriging.interpolate().

  • method ({"collocated", "icm", "lmc"}, default "collocated") – Cokriging method.

  • model_values (array_like or None, default None) – Optional pre-fitted coregionalization model vector, currently supported only for method="collocated".

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

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

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

  • max_colocation_dist (float or None, default None) – Distance within which a primary sample is paired with its nearest secondary point to estimate the cross-covariances; None pairs only exactly coincident locations. Heterotopic secondaries, such as rasters, need a distance (e.g. half the cell diagonal).

  • max_secondary_neighbors (int or None, default None) – "icm"/"lmc" only: maximum neighbors of each secondary per target; None uses max_neighbors.

Returns:

One cokriging estimate per target coordinate.

Return type:

numpy.ndarray