krigekit.variogram_st#

Composed space-time variogram model and coupling fit workflows.

Classes#

SpaceTimeVariogramModel

Joint model composed from spatial and temporal marginal models.

Module Contents#

class krigekit.variogram_st.SpaceTimeVariogramModel(spatial=None, temporal=None)#

Bases: krigekit.variogram_base._VariogramModelBase

Joint model composed from spatial and temporal marginal models.

This mirrors the Fortran vgm_struct_st layout: spatial corresponds to cs, temporal corresponds to ct, and this object owns only full space-time observations, coupling parameters, and transfer metadata.

Create a space-time model from optional marginal models.

set_vgm(*args, **kwargs)#: Add a structure to the spatial marginal and return self.

set_vgm_temporal(vtype, nugget=0.0, sill=1.0, at_k=1.0, product=False, **kwargs)#: Add a structure to the temporal marginal and return self.

experimental(store=True, **kwargs)#: Calculate the full space-time cloud with stored spatial anisotropy.

calc_spacetime_variogram(spatial_lag, temporal_lag, params=None)#

Evaluate the fitted product-sum space-time semivariogram.

Parameters:

spatial_lag (array-like) – Broadcastable spatial and temporal lag arrays.
temporal_lag (array-like) – Broadcastable spatial and temporal lag arrays.
params (array-like, optional) – (a, b, p, spatial_range, temporal_range). If omitted, use spacetime_params_ from fit_spacetime_product_sum() or set_spacetime_params().

calc_spacetime_variogram_between(coord0, coord1, time0, time1, *, pairwise=False, params=None)#

Evaluate the space-time variogram between coordinates.

Spatial lag vectors are rotated and scaled using the anisotropy stored by set_spacetime_anisotropy(). The resulting distance is the equivalent lag along the major axis, in the original coordinate units.

set_spacetime_anisotropy(*, anis1=1.0, anis2=1.0, azimuth=0.0, dip=0.0, plunge=0.0)#

Set spatial anisotropy for product-sum fitting and evaluation.

anis1 and anis2 are minor/major range ratios, matching the Fortran engine. Angles use the engine convention: azimuth clockwise from north and dip positive downward.

set_spacetime_params(params, *, spatial_vtype=None, temporal_vtype=None)#

Manually set product-sum space-time parameters.

params is (a, b, p, spatial_range, temporal_range). Valid covariance conversion requires p <= 0, a + p > 0 and b + p > 0.

fit_spacetime_product_sum(avgvgm=None, *, spatial_vtype='sph', temporal_vtype='gau', starts=None, bounds=None, spatial_col=None, temporal_col=('time_lag', 'mean'), variogram_col=('variogram', 'mean'), count_col=('variogram', 'count'), weight_cap_quantile=0.9, min_marginal_sill=0.0001, options=None, avg_kwargs=None)#

Fit a constrained product-sum model to averaged space-time bins.

The fitted form is

a*g_s(h_s) + b*g_t(h_t) + p*g_s(h_s)*g_t(h_t),

where both marginal variograms have unit sill. Multiple starting points are fitted with SLSQP; the successful result with the smallest weighted objective is stored.

Returns:: VariogramModel – self with spacetime_params_, spacetime_fit_result_ and spacetime_fit_results_ populated.

calc_spacetime_sum_metric_variogram(spatial_lag, temporal_lag, params=None)#

Evaluate a fitted sum-metric space-time semivariogram.

params contains spatial_scale, temporal_scale, one joint sill per spatial structure, and the joint temporal scale at.

fit_spacetime_sum_metric(spatial_model=None, temporal_model=None, avgvgm=None, *, transform='lin', time_nugget=0.0, time_sill=1.0, p0=None, bounds=None, spatial_col=('distance', 'mean'), temporal_col=('time_lag', 'mean'), variogram_col=('variogram', 'mean'), count_col=('variogram', 'count'), weight_cap_quantile=0.9, max_nfev=20000, avg_kwargs=None)#

Fit sum-metric coupling while retaining fitted marginal shapes.

The fit estimates a spatial marginal scale, temporal marginal scale, one non-negative joint sill per spatial structure, and the joint temporal scale at. Allowing the two marginal scales to adjust avoids forcing separately fitted boundary marginals to explain the entire interior space-time lag surface.

fit(avgvgm=None, *, model='product_sum', **kwargs)#

Fit a space-time coupling model, returning a FitResult.

model selects the coupling form:

"product_sum" fits the constrained a*g_s(h_s) + b*g_t(h_t) + p*g_s(h_s)*g_t(h_t) model; its parameters are (a, b, p, spatial_range, temporal_range).
"sum_metric" fits a spatial marginal scale, a temporal marginal scale, one joint sill per spatial structure, and the joint temporal scale at.

Remaining keyword arguments are forwarded to the underlying fitter, and the fitted parameters are stored on the model for to_spacetime_kriging_specs() / to_sum_metric_kriging_specs(). FitResult.summary() reports the labelled parameter table; variance and p-values are not estimated for these constrained/weighted joint fits, so those columns are NaN.

to_sum_metric_kriging_specs()#: Return fitted sum-metric marginal, coupling, and search parameters.

to_spacetime_kriging_specs(*, z_scale=None, spatial_nugget=0.0, temporal_nugget=0.0)#: Convert fitted product-sum parameters to engine-ready dictionaries.