gstools.covmodel.base¶

GStools subpackage providing the base class for covariance models.

The following classes are provided

CovModel([dim, var, len_scale, nugget, …]) Base class for the GSTools covariance models.

class gstools.covmodel.base.CovModel(dim=3, var=1.0, len_scale=1.0, nugget=0.0, anis=1.0, angles=0.0, integral_scale=None, var_raw=None, hankel_kw=None, **opt_arg)[source]¶

Bases: object

Base class for the GSTools covariance models.

Parameters:

dim (int, optional) – dimension of the model. Default: 3
var (float, optional) – variance of the model (the nugget is not included in “this” variance) Default: 1.0
len_scale (float or list, optional) – length scale of the model. If a single value is given, the same length-scale will be used for every direction. If multiple values (for main and transversal directions) are given, anis will be recalculated accordingly. Default: 1.0
nugget (float, optional) – nugget of the model. Default: 0.0
anis (float or list, optional) – anisotropy ratios in the transversal directions [y, z]. Default: 1.0
angles (float or list, optional) –
angles of rotation:
in 2D: given as rotation around z-axis

in 3D: given by yaw, pitch, and roll (known as Tait–Bryan angles)
Default: 0.0
integral_scale (float or list or None, optional) – If given, len_scale will be ignored and recalculated, so that the integral scale of the model matches the given one. Default: None
var_raw (float or None, optional) – raw variance of the model which will be multiplied with CovModel.var_factor to result in the actual variance. If given, var will be ignored. (This is just for models that override CovModel.var_factor) Default: None
hankel_kw (dict or None, optional) – Modify the init-arguments of hankel.SymmetricFourierTransform used for the spectrum calculation. Use with caution (Better: Don’t!). None is equivalent to {"a": -1, "b": 1, "N": 1000, "h": 0.001}. Default: None

Examples

>>> from gstools import CovModel
>>> import numpy as np
>>> class Gau(CovModel):
...     def cor(self, h):
...         return np.exp(-h**2)
...
>>> model = Gau()
>>> model.spectrum(2)
0.00825830126008459

Attributes:

angles: numpy.ndarray: Rotation angles (in rad) of the model.
anis: numpy.ndarray: The anisotropy factors of the model.
arg: list of str: Names of all arguments.
arg_bounds: dict: Bounds for all parameters.
dim: int: The dimension of the model.
dist_func: tuple of callable: pdf, cdf and ppf.
do_rotation: bool: State if a rotation is performed.
hankel_kw: dict: hankel.SymmetricFourierTransform kwargs.
has_cdf: bool: State if a cdf is defined by the user.
has_ppf: bool: State if a ppf is defined by the user.
integral_scale: float: The main integral scale of the model.
integral_scale_vec: numpy.ndarray: The integral scales in each direction.
len_scale: float: The main length scale of the model.
len_scale_bounds: list: Bounds for the lenght scale.
len_scale_vec: numpy.ndarray: The length scales in each direction.
name: str: The name of the CovModel class.
nugget: float: The nugget of the model.
nugget_bounds: list: Bounds for the nugget.
opt_arg: list of str: Names of the optional arguments.
opt_arg_bounds: dict: Bounds for the optional arguments.
pykrige_angle: 2D rotation angle for pykrige.
pykrige_angle_x: 3D rotation angle around x for pykrige.
pykrige_angle_y: 3D rotation angle around y for pykrige.
pykrige_angle_z: 3D rotation angle around z for pykrige.
pykrige_anis: 2D anisotropy ratio for pykrige.
pykrige_anis_y: 3D anisotropy ratio in y direction for pykrige.
pykrige_anis_z: 3D anisotropy ratio in z direction for pykrige.
pykrige_kwargs: Keyword arguments for pykrige routines.
sill: float: The sill of the variogram.
var: float: The variance of the model.
var_bounds: list: Bounds for the variance.
var_raw: float: The raw variance of the model without factor.

Methods

`calc_integral_scale`()	Calculate the integral scale of the isotrope model.
`check_arg_bounds`()	Check arguments to be within the given bounds.
`check_opt_arg`()	Run checks for the optional arguments.
`cor_spatial`(pos)	Spatial correlation respecting anisotropy and rotation.
`cov_nugget`(r)	Covariance of the model respecting the nugget at r=0.
`cov_spatial`(pos)	Spatial covariance respecting anisotropy and rotation.
`default_arg_bounds`()	Provide default boundaries for arguments.
`default_opt_arg`()	Provide default optional arguments by the user.
`default_opt_arg_bounds`()	Provide default boundaries for optional arguments.
`fit_variogram`(x_data, y_data[, maxfev])	Fiting the isotropic variogram-model to given data.
`fix_dim`()	Set a fix dimension for the model.
`ln_spectral_rad_pdf`(r)	Log radial spectral density of the model.
`percentile_scale`([per])	Calculate the percentile scale of the isotrope model.
`plot`([func])	Plot a function of a the CovModel.
`pykrige_vario`([args, r])	Isotropic variogram of the model for pykrige.
`set_arg_bounds`(**kwargs)	Set bounds for the parameters of the model.
`spectral_density`(k)	Spectral density of the covariance model.
`spectral_rad_pdf`(r)	Radial spectral density of the model.
`spectrum`(k)	Spectrum of the covariance model.
`var_factor`()	Factor for the variance.
`vario_nugget`(r)	Isotropic variogram of the model respecting the nugget at r=0.
`vario_spatial`(pos)	Spatial variogram respecting anisotropy and rotation.

calc_integral_scale()[source]¶: Calculate the integral scale of the isotrope model.

check_arg_bounds()[source]¶: Check arguments to be within the given bounds.

check_opt_arg()[source]¶

Run checks for the optional arguments.

This is in addition to the bound-checks

Notes

You can use this to raise a ValueError/warning
Any return value will be ignored
This method will only be run once, when the class is initialized

cor_spatial(pos)[source]¶: Spatial correlation respecting anisotropy and rotation.

cov_nugget(r)[source]¶

Covariance of the model respecting the nugget at r=0.

Given by: $C\left(r\right)= \sigma^2\cdot\mathrm{cor}\left(r\right)$

Where $\mathrm{cor}(r)$ is the correlation function.

cov_spatial(pos)[source]¶: Spatial covariance respecting anisotropy and rotation.

default_arg_bounds()[source]¶

Provide default boundaries for arguments.

Given as a dictionary.

default_opt_arg()[source]¶

Provide default optional arguments by the user.

Should be given as a dictionary.

default_opt_arg_bounds()[source]¶: Provide default boundaries for optional arguments.

fit_variogram(x_data, y_data, maxfev=1000, **para_deselect)[source]¶

Fiting the isotropic variogram-model to given data.

Parameters:

x_data (numpy.ndarray) – The radii of the meassured variogram.
y_data (numpy.ndarray) – The messured variogram
maxfev (int, optional) – The maximum number of calls to the function in scipy curvefit. Default: 1000
**para_deselect – You can deselect the parameters to be fitted, by setting them “False” as keywords. By default, all parameters are fitted.

Returns:

fit_para (dict) – Dictonary with the fitted parameter values
pcov (numpy.ndarray) – The estimated covariance of popt from scipy.optimize.curve_fit

Notes

You can set the bounds for each parameter by accessing CovModel.set_arg_bounds.

The fitted parameters will be instantly set in the model.

fix_dim()[source]¶: Set a fix dimension for the model.

ln_spectral_rad_pdf(r)[source]¶: Log radial spectral density of the model.

percentile_scale(per=0.9)[source]¶

Calculate the percentile scale of the isotrope model.

This is the distance, where the given percentile of the variance is reached by the variogram

plot(func='variogram', **kwargs)[source]¶

Plot a function of a the CovModel.

Parameters:	func (`str`, optional) – Function to be plotted. Could be one of: ”variogram” ”covariance” ”correlation” ”vario_spatial” ”cov_spatial” ”cor_spatial” ”spectrum” ”spectral_density” ”spectral_rad_pdf” **kwargs – Keyword arguments forwarded to the plotting function “plot_” + func in `gstools.covmodel.plot`.

See also

gstools.covmodel.plot()

pykrige_vario(args=None, r=0)[source]¶

Isotropic variogram of the model for pykrige.

Given by: $\gamma\left(r\right)= \sigma^2\cdot\left(1-\mathrm{cor}\left(r\right)\right)+n$

Where $\mathrm{cor}(r)$ is the correlation function.

set_arg_bounds(**kwargs)[source]¶

Set bounds for the parameters of the model.

Parameters:

**kwargs –

Parameter name as keyword (“var”, “len_scale”, “nugget”, <opt_arg>) and a list of 2 or 3 values as value:

[a, b] or

[a, b, <type>]

<type> is one of "oo", "cc", "oc" or "co" to define if the bounds are open (“o”) or closed (“c”).

spectral_density(k)[source]¶

Spectral density of the covariance model.

This is given by:

$\tilde{S}(k) = \frac{S(k)}{\sigma^2}$

Where $S(k)$ is the spectrum of the covariance model.

Parameters:	k (`float`) – Radius of the phase: $k=\left\Vert\mathbf{k}\right\Vert$

spectral_rad_pdf(r)[source]¶: Radial spectral density of the model.

spectrum(k)[source]¶

Spectrum of the covariance model.

This is given by:

$S(k) = \left(\frac{1}{2\pi}\right)^n \int C(r) e^{i b\mathbf{k}\cdot\mathbf{r}} d^n\mathbf{r}$

Internally, this is calculated by the hankel transformation:

$S(k) = \left(\frac{1}{2\pi}\right)^n \cdot \frac{(2\pi)^{n/2}}{k^{n/2-1}} \int_0^\infty r^{n/2} C(r) J_{n/2-1}(kr) dr$

Where $C(r)$ is the covariance function of the model.

Parameters:	k (`float`) – Radius of the phase: $k=\left\Vert\mathbf{k}\right\Vert$

var_factor()[source]¶: Factor for the variance.

vario_nugget(r)[source]¶

Isotropic variogram of the model respecting the nugget at r=0.

Given by: $\gamma\left(r\right)= \sigma^2\cdot\left(1-\mathrm{cor}\left(r\right)\right)+n$

Where $\mathrm{cor}(r)$ is the correlation function.

vario_spatial(pos)[source]¶: Spatial variogram respecting anisotropy and rotation.

angles¶

Rotation angles (in rad) of the model.

Type:	`numpy.ndarray`

anis¶

The anisotropy factors of the model.

Type:	`numpy.ndarray`

arg¶

Names of all arguments.

Type:	`list` of `str`

arg_bounds¶

Bounds for all parameters.

Notes

Keys are the opt-arg names and values are lists of 2 or 3 values:

[a, b] or

[a, b, <type>]

<type> is one of "oo", "cc", "oc" or "co" to define if the bounds are open (“o”) or closed (“c”).

Type:	`dict`

dim¶

The dimension of the model.

Type:	`int`

dist_func¶

pdf, cdf and ppf.

Spectral distribution info from the model.

Type:	`tuple` of `callable`

do_rotation¶

State if a rotation is performed.

Type:	`bool`

hankel_kw¶

hankel.SymmetricFourierTransform kwargs.

Type:	`dict`

has_cdf¶

State if a cdf is defined by the user.

Type:	`bool`

has_ppf¶

State if a ppf is defined by the user.

Type:	`bool`

integral_scale¶

The main integral scale of the model.

Raises:	`ValueError` – If integral scale is not setable.
Type:	`float`

integral_scale_vec¶

The integral scales in each direction.

Notes

This is calculated by:

integral_scale_vec[0] = integral_scale
integral_scale_vec[1] = integral_scale*anis[0]
integral_scale_vec[2] = integral_scale*anis[1]

Type:	`numpy.ndarray`

len_scale¶

The main length scale of the model.

Type:	`float`

len_scale_bounds¶

Bounds for the lenght scale.

Notes

Is a list of 2 or 3 values:

[a, b] or

[a, b, <type>]

<type> is one of "oo", "cc", "oc" or "co" to define if the bounds are open (“o”) or closed (“c”).

Type:	`list`

len_scale_vec¶

The length scales in each direction.

Notes

This is calculated by:

len_scale_vec[0] = len_scale
len_scale_vec[1] = len_scale*anis[0]
len_scale_vec[2] = len_scale*anis[1]

Type:	`numpy.ndarray`

name¶

The name of the CovModel class.

Type:	`str`

nugget¶

The nugget of the model.

Type:	`float`

nugget_bounds¶

Bounds for the nugget.

Notes

Is a list of 2 or 3 values:

[a, b] or

[a, b, <type>]

<type> is one of "oo", "cc", "oc" or "co" to define if the bounds are open (“o”) or closed (“c”).

Type:	`list`

opt_arg¶

Names of the optional arguments.

Type:	`list` of `str`

opt_arg_bounds¶

Bounds for the optional arguments.

Notes

Keys are the opt-arg names and values are lists of 2 or 3 values:

[a, b] or

[a, b, <type>]

<type> is one of "oo", "cc", "oc" or "co" to define if the bounds are open (“o”) or closed (“c”).

Type:	`dict`

pykrige_angle¶: 2D rotation angle for pykrige.

pykrige_angle_x¶: 3D rotation angle around x for pykrige.

pykrige_angle_y¶: 3D rotation angle around y for pykrige.

pykrige_angle_z¶: 3D rotation angle around z for pykrige.

pykrige_anis¶: 2D anisotropy ratio for pykrige.

pykrige_anis_y¶: 3D anisotropy ratio in y direction for pykrige.

pykrige_anis_z¶: 3D anisotropy ratio in z direction for pykrige.

pykrige_kwargs¶: Keyword arguments for pykrige routines.

sill¶

The sill of the variogram.

Notes

This is calculated by:

sill = variance + nugget

Type:	`float`

var¶

The variance of the model.

Type:	`float`

var_bounds¶

Bounds for the variance.

Notes

Is a list of 2 or 3 values:

[a, b] or

[a, b, <type>]

<type> is one of "oo", "cc", "oc" or "co" to define if the bounds are open (“o”) or closed (“c”).

Type:	`list`

var_raw¶

The raw variance of the model without factor.

(See. CovModel.var_factor)

Type:	`float`