krigekit.variogram_system_indicator#

Indicator variogram system: categorical encoding, closure-aware LMC fitting.

An IndicatorVariogramSystem is a VariogramSystem specialised for mutually exclusive, exhaustive categorical indicators I_1 + ... + I_K = 1. It owns the construction of indicator variograms in Python – encoding raw categories into K binary variables, building the K x K coregionalization from category proportions, and fitting a coregionalization that is both positive semidefinite and closed (rows summing to zero). The Fortran IndicatorKriging wrapper still executes the kriging and post-processes probabilities; this system configures it via apply().

Classes#

IndicatorVariogramSystem

Variogram system for K mutually exclusive categorical indicators.

Functions#

encode_indicator_matrix(values, categories)

Return the (nobs, K) one-hot indicator matrix for raw values.

indicator_covariance(proportions)

Return the closed zero-lag indicator covariance diag(p) - p p^T.

contrast_basis(ncat)

Return an orthonormal (K, K-1) basis Q of the contrast space.

Module Contents#

krigekit.variogram_system_indicator.encode_indicator_matrix(values, categories)#

Return the (nobs, K) one-hot indicator matrix for raw values.

categories is the ordered list of K labels; column k is the binary indicator values == categories[k] as floats.

krigekit.variogram_system_indicator.indicator_covariance(proportions)#

Return the closed zero-lag indicator covariance diag(p) - p p^T.

For a probability vector p summing to one this is positive semidefinite with row sums of zero, giving auto variances p_k (1 - p_k) and cross covariances -p_k p_l.

krigekit.variogram_system_indicator.contrast_basis(ncat)#

Return an orthonormal (K, K-1) basis Q of the contrast space.

Columns of Q are orthonormal and orthogonal to the all-ones vector, so B = Q L L^T Q^T is positive semidefinite and closed (B 1 = 0) for any lower-triangular L.

class krigekit.variogram_system_indicator.IndicatorVariogramSystem(categories=None, ncat=None)#

Bases: krigekit.variogram_system.VariogramSystem

Variogram system for K mutually exclusive categorical indicators.

Create an indicator system from category labels or a count.

Provide categories (an ordered label list) or ncat. The system has exactly K variables (ivar = 1..K); secondary co-variates are out of scope here – configure those on the kriging object directly.

property ncat#

Number of categories K (always the system’s variable count).

encode_indicators(categories)#

Return the one-hot indicator matrix for categories using labels.

set_categorical_obs(coord, categories, *, category_labels=None, variance=None)#

Encode raw categories into K indicator datasets and store them.

category_labels (or the constructor categories) fixes the label order; otherwise sorted unique values are used. Proportions are computed from the encoded indicators.

calc_proportions()#

Compute and store category proportions from configured indicators.

initial_indicator_covariance()#

Return the closed zero-lag covariance diag(p) - p p^T.

set_indicator_vgm(vtype='sph', nugget=0.0, sill=1.0, a_major=1.0, a_minor1=None, a_minor2=None, azimuth=0.0, dip=0.0, plunge=0.0, sill_strategy='theoretical', cross_strategy='closure', proportions=None)#

Configure all K^2 indicator pairs with one shared model shape.

sill_strategy sets the auto (diagonal) partial sills:

  • "theoretical" – p_k (1 - p_k) from category proportions;

  • "uniform" – the given sill for every category.

cross_strategy sets the off-diagonal partial sills:

  • "closure" (recommended) – -p_k p_l, the closed indicator covariance off-diagonal;

  • "independent" – zero (no co-kriging);

  • "proportional" – sqrt(s_k s_l) from the auto sills;

  • "uniform" – the given sill.

Legacy configurations map directly: old cross="same" is sill_strategy="uniform", cross_strategy="uniform"; old cross="independent"/"proportional" pair with sill_strategy="theoretical".

fit_indicator_lmc(pairs=None, shared_ranges=True, x_col=('distance', 'mean'), y_col=('variogram', 'mean'), sigma_col=None, weight_col=None, fit_nugget=True, inplace=False, raw_kwargs=None, avg_kwargs=None, max_nfev=20000, **kwargs)#

Fit a closed, PSD linear model of coregionalization for indicators.

Each nested coregionalization matrix is parameterized as B = Q L L^T Q^T with Q the contrast basis, guaranteeing positive semidefiniteness and closure (B 1 = 0) at every fitted lag. Ranges are shared across pairs when shared_ranges=True. Returns a FitResult whose target is the fitted indicator system.

validate_closure(tol=1e-06, include_nugget=True)#

Check that every fitted coregionalization matrix is closed.

Raises if any matrix (sill structures, plus the nugget when include_nugget) has a row sum exceeding tol in magnitude.

fit(*, method='closure', **kwargs)#

Fit the indicator system; method="closure" is the default.

"closure" runs fit_indicator_lmc(); "lmc" and "pair" fall through to the unconstrained VariogramSystem facade.

apply(kriging, observations=True, variograms=True, replace=True, pairs=None)#

Transfer indicators and structures, checking ncat agreement.