Theoretical#

build_theoretical_variogram(experimental_variogram, model_name, sill, rang, nugget=0.0, direction=None)[source]

Function is a wrapper into TheoreticalVariogram class and its fit() method.

Parameters:

experimental_variogramExperimentalVariogram

model_namestr

Available types:

‘circular’,
‘cubic’,
‘exponential’,
‘gaussian’,
‘linear’,
‘power’,
‘spherical’.

sillfloat

The value at which dissimilarity is close to its maximum if model is bounded. Otherwise, it is usually close to observations variance.

rangfloat

The semivariogram range is a distance at which spatial correlation exists. It shouldn’t be set at a distance larger than a half of a study extent.

nuggetfloat, default=0.

The nugget parameter (bias at a zero distance).

directionfloat, in range [0, 360], default=None

The direction of a semivariogram. If None given then semivariogram is isotropic.

Returns:

theoTheoreticalVariogram: Fitted theoretical semivariogram model.

class TheoreticalVariogram(model_params=None)[source]

Theoretical model of a spatial dissimilarity.

Parameters:

model_paramsDict, default=None: Dictionary with 'nugget', 'sill', 'range' and 'name' of the model.

See also

ExperimentalVariogram: class to calculate experimental variogram and more.

Examples

>>> import numpy
>>> REFERENCE_INPUT = numpy.array([
...    [0, 0, 1],
...    [1, 0, 2],
...    [2, 0, 3],
...    [3, 0, 4],
...    [4, 0, 5],
...    [5, 0, 6],
...    [6, 0, 7],
...    [7, 0, 5],
...    [8, 0, 3],
...    [9, 0, 1],
...    [10, 0, 4],
...    [11, 0, 6],
...    [12, 0, 8]
...    ])
>>> STEP_SIZE = 1
>>> MAX_RANGE = 4
>>> empirical_smv = ExperimentalVariogram(REFERENCE_INPUT, step_size=STEP_SIZE, max_range=MAX_RANGE)
>>> theoretical_smv = TheoreticalVariogram()
>>> _ = theoretical_smv.autofit(experimental_variogram=empirical_smv, model_name='gaussian')
>>> print(theoretical_smv.rmse)
1.5275214898546217

Attributes:

experimental_variogramEmpiricalVariogram, default=None

Empirical Variogram class and its attributes.

experimental_arraynumpy array, default=None

Empirical variogram in a form of numpy array.

variogram_modelsDict

A dictionary with keys representing theoretical variogram models and values that are pointing into a modeling functions. Available models:

‘circular’,
‘cubic’,
‘exponential’,
‘gaussian’,
‘linear’,
‘power’,
‘spherical’.

fitted_modelnumpy array or None

Trained theoretical model values. Array of [lag, variances].

namestr or None, default=None

The name of the chosen model. Available names are the same as keys in variogram_models attribute.

nuggetfloat, default=0

The nugget parameter (bias at a zero distance).

sillfloat, default=0

A value at which dissimilarity is close to its maximum if model is bounded. Otherwise, it is usually close to observations variance.

rangfloat, default=0

The semivariogram range is a distance at which spatial correlation exists. It shouldn’t be set at a distance larger than a half of a study extent.

directionfloat, in range [0, 360], default=None

The direction of a semivariogram. If None given then semivariogram is isotropic.

rmsefloat, default=0

Root mean squared error of the difference between the empirical observations and the modeled curve.

maebool, default=True

Mean Absolute Error of a model.

biasfloat, default=0

Forecast Bias of the modeled variogram vs experimental points. Large positive value means that the estimated model underestimates values. A large negative value means that model overestimates predictions.

smapefloat, default=0

Symmetric Mean Absolute Percentage Error of the prediction - values from 0 to 100%.

spatial_dependency_ratiofloat, default = None

The ratio of nugget vs sill multiplied by 100. Levels from 0 to 25 indicate strong spatial dependency, from 25 to 75 moderate spatial dependency, from 75 to 95 weak spatial dependency, and above process is considered to be not spatially-depended.

spatial_dependency_strengthstr, default = “Unknown”

Descriptive indicator of spatial dependency strength based on the spatial_dependency_level. It could be:

unknown if ratio is None,
strong if ratio is below 25,
moderate if ratio is between 25 and 75,
weak if ratio is between 75 and 95,
no spatial dependency if ratio is greater than 95.

are_paramsbool

Check if model parameters were given during initialization.

Methods

fit()	Fits experimental variogram data into theoretical model.
autofit()	The same as fit but tests multiple nuggets, ranges, sills and models.
calculate_model_error()	Evaluates the model performance against experimental values.
to_dict()	Store model parameters in a dict.
from_dict()	Read model parameters from a dict.
to_json()	Save model parameteres in a JSON file.
from_json()	Read model parameters from a JSON file.
plot()	Shows theoretical model.

autofit(experimental_variogram, model_name='safe', model_types=None, nugget=None, min_nugget=0, max_nugget=0.5, number_of_nuggets=16, rang=None, min_range=0.1, max_range=0.5, number_of_ranges=16, sill=None, min_sill=0.0, max_sill=1, number_of_sills=16, direction=None, error_estimator='rmse', deviation_weighting='equal', auto_update_attributes=True, warn_about_set_params=True, verbose=False, return_params=True)[source]

Method tries to find the optimal range, sill and model (function) of the theoretical semivariogram.

Parameters:

experimental_variogramExperimentalVariogram

Prepared Empirical Variogram or array.

model_namestr, default=’safe’

The name of the model to check or special command for multiple models. Available models:

‘all’ - the same as list with all models,
‘safe’ - [‘linear’, ‘power’, ‘spherical’],
‘circular’,
‘cubic’,
‘exponential’,
‘gaussian’,
‘linear’,
‘power’,
‘spherical’.

model_typesList, default = None

The list with model names to check excluding ‘all’ and ‘safe’ names.

nuggetfloat, optional

Nugget (bias) of a variogram. If given then it is fixed to this value.

min_nuggetfloat, default = 0

The minimum nugget as the ratio of the parameter to the first lag variance.

max_nuggetfloat, default = 0.5

The maximum nugget as the ratio of the parameter to the first lag variance.

number_of_nuggetsint, default = 16

How many equally spaced nuggets tested between min_nugget and max_nugget.

rangfloat, optional

If given, then range is fixed to this value.

min_rangefloat, default = 0.1

The minimal fraction of a variogram range, 0 < min_range <= max_range.

max_rangefloat, default = 0.5

The maximum fraction of a variogram range, min_range <= max_range <= 1. Parameter max_range greater than 0.5 raises warning.

number_of_rangesint, default = 16

How many equally spaced ranges are tested between min_range and max_range.

sillfloat, default = None

If given, then sill is fixed to this value.

min_sillfloat, default = 0

The minimal fraction of the variogram variance at lag 0 to find a sill, 0 <= min_sill <= max_sill.

max_sillfloat, default = 1

The maximum fraction of the variogram variance at lag 0 to find a sill. It should be lower or equal to 1. It is possible to set it above 1, but then warning is printed.

number_of_sillsint, default = 16

How many equally spaced sill values are tested between min_sill and max_sill.

directionfloat, in range [0, 360], default=None

The direction of a semivariogram. If None given then semivariogram is isotropic. This parameter is required if passed experimental variogram is stored in a numpy array.

error_estimatorstr, default = ‘rmse’

A model error estimation method. Available options are:

‘rmse’: Root Mean Squared Error,
‘mae’: Mean Absolute Error,
‘bias’: Forecast Bias,
‘smape’: Symmetric Mean Absolute Percentage Error.

deviation_weightingstr, default = “equal”

The name of a method used to weight error at a given lags. Works only with RMSE. Available methods:

equal: no weighting,
closest: lags at a close range have bigger weights,
distant: lags that are further away have bigger weights,
dense: error is weighted by the number of point pairs within a lag.

auto_update_attributesbool, default = True

Update sill, range, model type and nugget based on the best model.

warn_about_set_params: bool, default=True

Should class invoke warning if model parameters has been set during initialization?

verbosebool, default = False

Show iteration results.

return_paramsbool, default = True

Return model parameters.

Returns:

model_attributesDict

Attributes dict:

>>> {
...     'model_name': model_name,
...     'sill': model_sill,
...     'range': model_range,
...     'nugget': model_nugget,
...     'error_type': type_of_error_metrics,
...     'error value': error_value
... }

Raises:

ValueError: Raised when sill < 0 or range < 0 or range > 1.
KeyError: Raised when wrong model name(s) are provided by the users.
KeyError: Raised when wrong error type is provided by the users.

Warns:

SillOutsideSafeRangeWarning: Warning printed when max_sill > 1.
RangeOutsideSafeDistanceWarning: Warning printed when max_range > 0.5.
Warning: Model parameters were given during initilization but program is forced to fit the new set of parameters.
Warning: Passed experimental_variogram is a numpy array and direction parameter is None.

calculate_model_error(fitted_values, rmse=True, bias=True, mae=True, smape=True, deviation_weighting='equal')[source]

Method calculates error associated with a difference between the theoretical model and the experimental semivariogram.

Parameters:

fitted_valuesnumpy array

[lag, fitted value]

rmsebool, default=True

Root Mean Squared Error of a model.

biasbool, default=True

Forecast Bias of a model.

maebool, default=True

Mean Absolute Error of a model.

smapebool, default=True

Symmetric Mean Absolute Percentage Error of a model.

deviation_weightingstr, default = “equal”

The name of a method used to weight errors at a given lags. Works only with RMSE. Available methods:

equal: no weighting,
closest: lags at a close range have bigger weights,
distant: lags that are further away have bigger weights,
dense: error is weighted by the number of point pairs within a lag.

Returns:

model_errorsDict: Dict with error values per model: rmse, bias, mae, smape.

Raises:

MetricsTypeSelectionError: User has set all error types to False.

fit(experimental_variogram, model_name, sill, rang, nugget=0.0, direction=None, update_attrs=True, warn_about_set_params=True)[source]

Parameters:

experimental_variogramExperimentalVariogram

Prepared Empirical Variogram.

model_namestr

The name of the model to check. Available models:

‘circular’,
‘cubic’,
‘exponential’,
‘gaussian’,
‘linear’,
‘power’,
‘spherical’.

sillfloat, default=0

A value at which dissimilarity is close to its maximum if model is bounded. Otherwise, it is usually close to observations variance.

rangfloat, default=0

The semivariogram range is a distance at which spatial correlation exists. It shouldn’t be set at a distance larger than a half of a study extent.

nuggetfloat, default=0.

Nugget parameter (bias at a zero distance).

directionfloat, in range [0, 360], default=None

The direction of a semivariogram. If None given then semivariogram is isotropic. This parameter is required if passed experimental variogram is stored in a numpy array.

update_attrsbool, default=True

Should class attributes be updated?

warn_about_set_params: bool, default=True

Should class invoke warning if model parameters has been set during initialization?

Returns:

_theoretical_values, _error: Tuple[ numpy array, dict ]: [ theoretical semivariances, {'rmse bias smape mae'}]

Raises:

KeyError: Model type (function) not implemented.

Warns:

Warning: Model parameters were given during initialization but program is forced to fit the new set of parameters.
Warning: Passed experimental_variogram is a numpy array and direction parameter is None.

from_dict(parameters)[source]

Method updates model with a given set of parameters.

Parameters:

parametersDict: Dictionary with model’s: 'name', 'nugget', 'sill', 'range', 'direction'.

from_json(fname)[source]

Method reads data from a JSON file.

Parameters:

fnamestr

plot(experimental=True)[source]

Method plots theoretical curve and (optionally) experimental scatter plot.

Parameters:

experimentalbool: Plot experimental observations.

Raises:

AttributeError: Model is not fitted yet, nothing to plot.

predict(distances)[source]

Method returns a semivariance per distance.

Parameters:

distancesnp.ndarray

Returns:

predictednp.ndarray

to_dict()[source]

Method exports the theoretical variogram parameters to a dictionary.

Returns:

model_parametersDict: Dictionary with model’s 'name', 'nugget', 'sill', 'range' and 'direction'.

Raises:

AttributeError: The model parameters have not been derived yet.

to_json(fname)[source]

Method stores variogram parameters into a JSON file.

Parameters:

fnamestr