gstools.covmodel.Intersection

class gstools.covmodel.Intersection(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: gstools.covmodel.base.CovModel

The Intersection covariance model.

This model is derived from the relative intersection area of two d-dimensional spheres, where the middle points have a distance of r and the diameters are given by \ell.

In 1D this is the Linear model, in 2D this is the Circular model and in 3D this is the Spherical model.

Notes

This model is given by the following correlation functions.

In 1D:

\rho(r) =
\begin{cases}
1-\frac{r}{\ell}
& r<\ell\\
0 & r\geq\ell
\end{cases}

In 2D:

\rho(r) =
\begin{cases}
\frac{2}{\pi}\cdot\left(
\cos^{-1}\left(\frac{r}{\ell}\right) -
\frac{r}{\ell}\cdot\sqrt{1-\left(\frac{r}{\ell}\right)^{2}}
\right)
& r<\ell\\
0 & r\geq\ell
\end{cases}

In 3D:

\rho(r) =
\begin{cases}
1-\frac{3}{2}\cdot\frac{r}{\ell} +
\frac{1}{2}\cdot\left(\frac{r}{\ell}\right)^{3}
& r<\ell\\
0 & r\geq\ell
\end{cases}

.

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. If only two values are given in 3D, the latter one will be used for both transversal directions. Default: 1.0
  • nugget (float, optional) – nugget of the model. Default: 0.0
  • anis (float or list, optional) –

    anisotropy ratios in the transversal directions [e_y, e_z].

    • e_y = l_y / l_x
    • e_z = l_z / l_x

    If only one value is given in 3D, e_y will be set to 1. This value will be ignored, if multiple len_scales are given. Default: 1.0

  • angles (float or list, optional) –

    angles of rotation (given in rad):

    • 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}.
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.

is_isotropic

bool: State if a model is isotropic.

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

Calculate the integral scale of the isotrope model.

check_arg_bounds(self)

Check arguments to be within the given bounds.

check_opt_arg(self)

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(self, h)

Normalziled correlation function taking a normalized range.

Given by: \mathrm{cor}\left(r/\ell\right) = \rho(r)

cor_spatial(self, pos)

Spatial correlation respecting anisotropy and rotation.

correlation(self, r)[source]
cov_nugget(self, r)

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

Given by: C\left(r\right)=
\sigma^2\cdot\rho\left(r\right)

Where \rho(r) is the correlation function.

cov_spatial(self, pos)

Spatial covariance respecting anisotropy and rotation.

covariance(self, r)

Covariance of the model.

Given by: C\left(r\right)=
\sigma^2\cdot\rho\left(r\right)

Where \rho(r) is the correlation function.

default_arg_bounds(self)

Provide default boundaries for arguments.

Given as a dictionary.

default_opt_arg(self)

Provide default optional arguments by the user.

Should be given as a dictionary.

default_opt_arg_bounds(self)

Provide default boundaries for optional arguments.

fit_variogram(self, x_data, y_data, maxfev=1000, **para_deselect)

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:

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(self)

Set a fix dimension for the model.

ln_spectral_rad_pdf(self, r)

Log radial spectral density of the model.

percentile_scale(self, per=0.9)

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(self, func='variogram', **kwargs)

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.
pykrige_vario(self, args=None, r=0)

Isotropic variogram of the model for pykrige.

Given by: \gamma\left(r\right)=
\sigma^2\cdot\left(1-\rho\left(r\right)\right)+n

Where \rho(r) is the correlation function.

set_arg_bounds(self, **kwargs)

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(self, 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(self, r)

Radial spectral density of the model.

spectrum(self, k)

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(self)

Factor for the variance.

vario_nugget(self, r)

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

Given by: \gamma\left(r\right)=
\sigma^2\cdot\left(1-\rho\left(r\right)\right)+n

Where \rho(r) is the correlation function.

vario_spatial(self, pos)

Spatial variogram respecting anisotropy and rotation.

variogram(self, r)

Isotropic variogram of the model.

Given by: \gamma\left(r\right)=
\sigma^2\cdot\left(1-\rho\left(r\right)\right)+n

Where \rho(r) is the correlation function.

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
is_isotropic

State if a model is isotropic.

Type:bool
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