SpatioTemporalVariogram class#

class skgstat.SpatioTemporalVariogram(coordinates, values, xdist_func='euclidean', x_lags=10, t_lags=10, maxlag_space=None, maxlag_time=None, xbins='even', tbins='even', estimator='matheron', use_nugget=False, model='product-sum', marginal_model='spherical')[source]#

Spatio-temporal Variogram

Added in version 1.1.

Estimates an experimental space-time variogram from observations that are located freely in space and time. Each observation is one row of the coordinates array: the last column holds the time, all preceding columns are spatial coordinates. In contrast to SpaceTimeVariogram, the observations do not need to form a complete location-by-time grid. A complete grid can be converted using from_grid.

All observation pairs are used. Thus, pairs at the same location and pairs observed at the same time contribute to the experimental variogram and form the two marginal variograms.

Parameters:

  • coordinates (numpy.ndarray, pandas.DataFrame) – Array of shape (n, d + 1). The first d columns are the spatial coordinates, the last column is time. Time can be numeric or any datetime-like type (datetime, numpy.datetime64, pandas.Timestamp).

  • values (numpy.ndarray) – Array of shape (n, ) holding one observation per coordinate row.

  • xdist_func (str) – Any metric supported by scipy.spatial.distance.pdist(). The metric is only applied to the spatial coordinates.

  • x_lags (int) – Number of space lag classes.

  • t_lags (int) – Number of time lag classes.

  • maxlag_space (float, str) – Maximum space lag. Follows the rules of Variogram.maxlag: a number 0 < maxlag < 1 is relative to the maximum separating distance, larger numbers are absolute. 'mean' and 'median' use the mean or median distance. If None, all pairs are used.

  • maxlag_time (float, str) – Maximum time lag. Same rules as for maxlag_space. Absolute values are given in the internal time unit, which is seconds for datetime-like input.

  • xbins (str, Iterable, Callable) – Binning of the space axis. Can be 'even', 'uniform', 'kmeans', 'ward' or any method supported by numpy.histogram_bin_edges(). Alternatively, a function of signature func(distances, n, maxlag) or the upper bin edges can be passed.

  • tbins (str, Iterable, Callable) – Binning of the time axis. Same options as for xbins.

  • estimator (str, Callable) – Semi-variance estimator. Can be one of 'matheron', 'cressie', 'dowd', 'genton', 'minmax', 'percentile', 'entropy' or a function.

  • use_nugget (bool) – If True, the marginal models are fitted with a nugget.

  • model (str) – Space-time model. Has to be one of 'sum', 'product' or 'product-sum'.

  • marginal_model (str) – Theoretical model fitted to both marginal variograms. Has to be one of 'spherical', 'exponential', 'gaussian', 'cubic', 'stable' or 'matern'.

Notes

Datetime-like time is anchored at the oldest timestamp and stored as elapsed seconds. All lags, bins and fitted models use seconds; only the plots convert the time axis into the unit implied by the data resolution. Numeric time is used as it is.

__init__(coordinates, values, xdist_func='euclidean', x_lags=10, t_lags=10, maxlag_space=None, maxlag_time=None, xbins='even', tbins='even', estimator='matheron', use_nugget=False, model='product-sum', marginal_model='spherical')[source]#
__init__(coordinates, values, xdist_func='euclidean', x_lags=10, t_lags=10, maxlag_space=None, maxlag_time=None, xbins='even', tbins='even', estimator='matheron', use_nugget=False, model='product-sum', marginal_model='spherical')[source]#
classmethod from_grid(coordinates, values, times=None, **kwargs)[source]#

Create from a location-by-time grid

Convert a complete location-by-time grid, as used by SpaceTimeVariogram, into one observation per grid cell. Non-finite grid cells are treated as missing observations and dropped.

Parameters:

  • coordinates (numpy.ndarray) – Array of shape (m, d) holding the spatial coordinates of the m locations.

  • values (numpy.ndarray) – Array of shape (m, n) holding a time series of length n for each location.

  • times (Iterable) – The n observation times. Can be numeric or datetime-like. If None, 0, 1, ..., n - 1 will be used.

  • kwargs (dict) – All other keyword arguments are passed to SpatioTemporalVariogram.

Returns:

variogram

Return type:

SpatioTemporalVariogram

Notes

The resulting experimental variogram is not equal to the one of SpaceTimeVariogram, as the latter does not use pairs at the same location, pairs at the same time and only one direction of each location-time pair.

get_marginal(axis)[source]#

Marginal experimental variogram

Calculates the experimental marginal variogram along the given axis. The space marginal only uses pairs observed at the same time, the time marginal only uses pairs observed at the same location.

Parameters:

axis (str) – Either 'space' or 'time'.

Returns:

marginal – Semi-variances for each lag class of the given axis.

Return type:

numpy.ndarray

:raises ValueError : in case there are no pairs at zero lag on the other: axis, which is common for irregularly sampled data.

fit(force=False)[source]#

Fit the space-time model

Fits the marginal model to both marginal variograms first. The sum and product models are then fully defined, the product-sum model fits its three parameters k1, k2 and k3 to the experimental variogram.

Parameters:

force (bool) – If True, an existing fit will be replaced.

property fitted_model#

Fitted space-time model

Returns:

model – Function that takes an array of shape (n, 2) holding space and time lag pairs and returns the modeled semi-variances.

Return type:

Callable

transform(lags)[source]#

Apply the fitted model

Parameters:

lags (numpy.ndarray) – Array of shape (n, 2) holding space and time lag pairs. Time lags are given in the internal time unit, which is seconds for datetime-like input.

Returns:

semivariance

Return type:

numpy.ndarray

property coordinates#

Spatial coordinates of all observations

property time#

Observation times, as seconds since time_origin for datetime input

property time_origin#

Oldest timestamp for datetime input, None for numeric time

property time_unit#

Plotting unit inferred from datetime input, None for numeric time

property values#
property estimator#
property xdistance#

Pairwise space lags

property tdistance#

Pairwise time lags

property xbins#

Upper bin edges of the space lag classes

property tbins#

Upper bin edges of the time lag classes

property x_lags#
property t_lags#
property meshbins#

Space and time bin edges as meshgrid of shape (x_lags, t_lags)

property experimental#

Experimental variogram

Returns:

variogram – Array of shape (x_lags, t_lags) holding the semi-variances.

Return type:

numpy.ndarray

property bin_count#

Number of point pairs in each lag class, shape (x_lags, t_lags)

plot(kind='scatter', ax=None, **kwargs)[source]#

Plot the variogram

Plots the experimental variogram and, once fitted, the space-time model. The time axis is shown in the unit implied by the data resolution.

Parameters:

  • kind (str) –

    Has to be one of:

    • scatter: 3D scatter of the experimental variogram

    • surface: 3D surface of the experimental variogram

    • contour: contour lines

    • contourf: filled contours

    • matrix: the experimental lag classes as image

  • ax (matplotlib.Axes, plotly.graph_objects.Figure, None) – If None, a new figure is created. Else, the plot is added to the given object, which has to match the plotting backend.

  • kwargs (dict) – Passed down to the plotting function. Set show_model=True to fit the model on demand, show_model=False to only plot the experimental variogram.

Returns:

fig

Return type:

matplotlib.Figure, plotly.graph_objects.Figure