krigekit.variogram_system#

Multivariable variogram systems and LMC fitting.

Classes#

VariogramSystem

Multivariable variogram system for cokriging workflows.

Module Contents#

class krigekit.variogram_system.VariogramSystem(nvar=None)#

Multivariable variogram system for cokriging workflows.

The system stores observations and variogram structures by 1-based variable pair (ivar, jvar). Each pair is a VgmStructure, while fit_lmc() fits all requested pairs together with positive-semidefinite coregionalization matrices.

Create an empty multivariable variogram system.

nvar=None selects dynamic mode: the variable count grows to the largest referenced 1-based index. An explicit nvar is a strict upper bound and access beyond it raises.

set_obs(ivar, coord, value, times=None, variance=None, sk_mean=None, drift=None)#

Store observations for variable ivar (ergonomic wrapper).

Delegates to self.obs[ivar].set(...) and invalidates cached empirical variograms for any pair containing ivar.

set_search(ivar, *, nmax=None, maxdist=None, anis1=1.0, anis2=1.0, azimuth=0.0, dip=0.0, plunge=0.0, sector_search=False, time_at=None)#

Configure per-variable neighbour search, transferred by apply().

Search settings are stored on the variable’s ObservationSet; the Fortran engine performs the actual neighbour selection.

set_vgm(ivar, jvar, vtype, **kwargs)#: Add one nested structure to the model for (ivar, jvar).

set_raw_vgm(ivar, jvar, rawvgm)#: Store an externally computed raw variogram cloud for a pair.

set_avg_vgm(ivar, jvar, avgvgm)#: Store an externally computed averaged variogram for a pair.

calc_experimental(ivar=None, jvar=None, cross='auto', store=True, **kwargs)#

Compute a raw empirical variogram cloud for one or all pairs.

With ivar=None (and no jvar), the cloud is computed for every pair that has a variogram model configured via set_vgm() (vgm.configured_pairs()), returning a {(ivar, jvar): cloud} dict. Otherwise a single pair is computed and returned.

Direct pairs use raw_vgm(). Cross pairs use the LMC cross-variogram estimator raw_cross_vgm() when the observations are collocated. Set cross="pseudo" to force cross_vgm(), or cross="lmc" to require collocated observations.

calc_empirical(*args, **kwargs)#: Alias for calc_experimental().

calc_average(ivar=None, jvar=None, rawvgm=None, store=True, raw_kwargs=None, **kwargs)#: Average one pair, or all cached raw variograms when no pair is given.

fit_pair(ivar, jvar=None, avgvgm=None, inplace=True, **kwargs)#

Fit one variable-pair model independently.

This is convenient for direct variograms, but fit_lmc() is the safer choice for cokriging because it constrains cross-pair sills.

fit(*, method='lmc', ivar=None, jvar=None, pairs=None, **kwargs)#

Fit the system, returning a FitResult (method facade).

method="lmc" (default) fits a joint linear model of coregionalization via fit_lmc(); method="pair" fits one variable pair independently via fit_pair() and requires ivar (with optional jvar). Subclasses extend this facade – IndicatorVariogramSystem adds method="closure".

fit_aniso_angle(ivar=1, jvar=None, pairs=None, n_struct=None, set_ranges=True, raw_kwargs=None, **kwargs)#

Fit the anisotropy orientation from one pair and apply it system-wide.

Run this before fit_lmc() / fit_pair(): the orientation is estimated from the (ivar, jvar) pair’s empirical cloud (the primary auto-variogram by default) with the model-based profile fit (krigekit.fit_aniso_angle(), 3-D) or the PCA azimuth (estimate_aniso_angle(), 2-D), then written into the structures selected by pairs (all configured pairs by default, since an LMC shares one orientation). set_ranges=True also seeds the minor ranges from the fitted ratios. Returns self.

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

Fit an additive linear model of coregionalization.

The sill matrix for each nested structure is parameterized as L @ L.T during optimization, so every fitted coregionalization matrix is positive semidefinite. Ranges are shared across all pairs. Use sigma_col for uncertainty-style residual scaling or weight_col for weighted least squares.

get_lmc_matrices(include_nugget=True)#: Return fitted/coregionalization matrices from current pair models.

set_markov_cross(primary, secondary, corr=None, structure='secondary', cross_nugget=0.0)#

Build the (primary, secondary) cross variogram by the Markov Model 1 (MM1) collocated-cokriging assumption.

For a sparsely sampled primary and a densely sampled secondary the cross-covariance cannot be fit from the primary’s (often nugget-dominated) structure – a joint fit_lmc() would drive it to zero. MM1 instead transfers it through the collocated correlation: the cross adopts the nested structure of one variable (structure="secondary" by default – the dense covariate that carries the spatial continuity), and each cross partial sill is

\[b_{ps}^{(k)} = \rho \, \sqrt{b_{pp}^{(k)} \, b_{ss}^{(k)}}\]

which is positive-semidefinite per structure for |rho| <= 1, so the coregionalization is valid by construction (no clamping needed). This is the appropriate model for sparse-hard + dense-soft cokriging (Almeida & Journel, 1994; Goovaerts, 1997). Markov Model 2 is not yet implemented.

Parameters:

primary (int) – 1-based indices; both auto-models must already be set via set_vgm() and share the same nested-structure count.
secondary (int) – 1-based indices; both auto-models must already be set via set_vgm() and share the same nested-structure count.
corr (float, optional) – Collocated cross-correlation in [-1, 1]. If None it is estimated from the collocated observations of the two variables (which must share coordinates; otherwise pass corr explicitly).
structure ({"secondary", "primary"}) – Which variable’s structure shapes/ranges the cross adopts.
cross_nugget (float) – Cross nugget partial sill (default 0).

validate_for(kriging, observations=True, variograms=True, pairs=None)#: Check that this system can be applied to kriging without leaving it partially configured. Raises on the first problem and mutates nothing; this is the validate-first half of apply().

apply_observations(kriging)#: Transfer configured observations (and drift) in ascending order.

apply_variograms(kriging, replace=True, pairs=None)#: Transfer configured pair structures in canonical upper-triangle order.

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

Validate, then transfer observations and/or variograms to kriging.

Validation (validate_for()) completes before any mutation, so a failure leaves kriging unchanged. Observations are applied in ascending variable order (drift immediately after each base observation), then configured variograms in canonical upper-triangle order.