mixle.analysis.kriging module

Geostatistics: variograms and kriging (best linear unbiased spatial prediction).

Kriging predicts a spatially correlated field at unobserved locations and – unlike a black-box regressor – returns a prediction variance that grows with distance from data. The spatial correlation is encoded by a variogram gamma(h) (how fast values decorrelate with separation h):

  • empirical_variogram() / fit_variogram() – estimate and fit a variogram model (spherical / exponential / gaussian / matern; the Gaussian model is also reachable as "squared_exponential" / "rbf", its covariance being the squared-exponential kernel) with nugget (measurement error / micro-scale variance), sill (total variance), and range (correlation length), plus geometric anisotropy (direction-dependent range).

  • ordinary_kriging() – BLUP with an unknown constant mean; exact interpolation with no nugget, smoothing with one, and heteroscedastic (per-observation) noise.

  • universal_kriging() – kriging with a polynomial trend / external drift.

  • calibrate_variance() – rescale kriging variances so their predictive intervals hit a target coverage on held-out data (generic GP/kriging recalibration).

Coordinates are (n, d) arrays (typically d = 2); values are the measured field.

class Variogram(model, nugget, psill, rng, nu=1.5, anisotropy=None)[source]

Bases: object

A fitted variogram model gamma(h) = nugget + psill * shape(h).

Parameters:
model

"spherical", "exponential", "gaussian" (aka "squared_exponential" / "rbf" – covariance psill * exp(-(h/rng)**2)), or "matern".

Type:

str

nugget

discontinuity at h=0 (measurement error / micro-scale variance).

Type:

float

psill

partial sill (correlated variance); nugget + psill is the total sill.

Type:

float

rng

range (correlation length).

Type:

float

nu

Matern smoothness (ignored by other models).

Type:

float

anisotropy

optional (angle_rad, ratio) geometric anisotropy – coordinates are rotated by angle and the minor axis scaled by 1/ratio before distances are taken.

Type:

tuple[float, float] | None

model: str
nugget: float
psill: float
rng: float
nu: float = 1.5
anisotropy: tuple[float, float] | None = None
gamma(h)[source]
Parameters:

h (ndarray)

Return type:

ndarray

cov_field(h)[source]

Covariance of the correlated field part (excludes the nugget): psill (1 - shape).

Parameters:

h (ndarray)

Return type:

ndarray

empirical_variogram(coords, values, *, n_bins=15, max_dist=None)[source]

Binned empirical (semi-)variogram: mean 0.5 (z_i - z_j)^2 by separation distance.

Returns:

{'lag', 'semivariance', 'count'} for each non-empty distance bin.

Parameters:
Return type:

dict[str, ndarray]

fit_variogram(coords, values, *, model='spherical', n_bins=15, nu=1.5)[source]

Fit a variogram model to data by least squares on the empirical variogram.

Returns:

A fitted Variogram (nugget, partial sill, range).

Parameters:
Return type:

Variogram

ordinary_kriging(coords, values, variogram, query, *, noise=None)[source]

Ordinary kriging: BLUP of the field at query under an unknown constant mean.

Parameters:

  • coords (ndarray) – (n, d) data locations.

  • values (ndarray) – (n,) measured field.

  • variogram (Variogram) – a fitted Variogram.

  • query (ndarray) – (q, d) prediction locations.

  • noise (ndarray | None) – optional (n,) per-observation measurement variance (heteroscedastic nugget); if None the homoscedastic variogram.nugget is used on the diagonal.

Returns:

{'prediction', 'variance'} arrays of length q.

Return type:

dict[str, ndarray]

universal_kriging(coords, values, variogram, query, *, degree=1, noise=None)[source]

Universal kriging: kriging with a polynomial spatial trend (drift) of the given degree.

degree=1 removes a linear trend, degree=2 a quadratic one. Use when the field has a large-scale drift on top of the stationary residual the variogram describes.

Returns:

{'prediction', 'variance'}.

Parameters:
Return type:

dict[str, ndarray]

calibrate_variance(predicted_var, residuals, *, target=0.9)[source]

Scale factor that makes kriging predictive intervals hit a target coverage.

Finds c so that standardised residuals residual / sqrt(c * predicted_var) achieve the target central coverage under a Gaussian predictive. Returns the variance multiplier c; multiply predicted_var by it to recalibrate (generic GP/kriging variance recalibration).

Parameters:

  • predicted_var (ndarray) – (m,) held-out kriging variances.

  • residuals (ndarray) – (m,) held-out actual - predicted.

  • target (float) – desired central coverage (e.g. 0.9).

Returns:

The variance multiplier c (> 0).

Return type:

float