DirectionalVariogram Class¶

class skgstat.DirectionalVariogram(coordinates=None, values=None, estimator='matheron', model='spherical', dist_func='euclidean', bin_func='even', normalize=False, fit_method='trf', fit_sigma=None, directional_model='triangle', azimuth=0, tolerance=45.0, bandwidth='q33', use_nugget=False, maxlag=None, n_lags=10, verbose=False, **kwargs)[source]¶

DirectionalVariogram Class

Calculates a variogram of the separating distances in the given coordinates and relates them to one of the semi-variance measures of the given dependent values.

The direcitonal version of a Variogram will only form paris of points that share a specified spatial relationship.

__init__(coordinates=None, values=None, estimator='matheron', model='spherical', dist_func='euclidean', bin_func='even', normalize=False, fit_method='trf', fit_sigma=None, directional_model='triangle', azimuth=0, tolerance=45.0, bandwidth='q33', use_nugget=False, maxlag=None, n_lags=10, verbose=False, **kwargs)[source]¶

Variogram Class

Directional Variogram. The calculation is not performant and not tested yet.

Parameters

coordinates (numpy.ndarray) – Array of shape (m, n). Will be used as m observation points of n-dimensions. This variogram can be calculated on 1 - n dimensional coordinates. In case a 1-dimensional array is passed, a second array of same length containing only zeros will be stacked to the passed one.
values (numpy.ndarray) – Array of values observed at the given coordinates. The length of the values array has to match the m dimension of the coordinates array. Will be used to calculate the dependent variable of the variogram.
estimator (str, callable) –
String identifying the semi-variance estimator to be used. Defaults to the Matheron estimator. Possible values are:
- matheron [Matheron, default]
- cressie [Cressie-Hawkins]
- dowd [Dowd-Estimator]
- genton [Genton]
- minmax [MinMax Scaler]
- entropy [Shannon Entropy]
If a callable is passed, it has to accept an array of absoulte differences, aligned to the 1D distance matrix (flattened upper triangle) and return a scalar, that converges towards small values for similarity (high covariance).
model (str) –
String identifying the theoretical variogram function to be used to describe the experimental variogram. Can be one of:
- spherical [Spherical, default]
- exponential [Exponential]
- gaussian [Gaussian]
- cubic [Cubic]
- stable [Stable model]
- matern [Matérn model]
- nugget [nugget effect variogram]
dist_func (str) – String identifying the distance function. Defaults to ‘euclidean’. Can be any metric accepted by scipy.spatial.distance.pdist. Additional parameters are not (yet) passed through to pdist. These are accepted by pdist for some of the metrics. In these cases the default values are used.
bin_func (str) –

Changed in version 0.3.8: added ‘fd’, ‘sturges’, ‘scott’, ‘sqrt’, ‘doane’

String identifying the binning function used to find lag class edges. All methods calculate bin edges on the interval [0, maxlag[. Possible values are:
- ’even’ (default) finds n_lags same width bins
- ’uniform’ forms n_lags bins of same data count
- ’fd’ applies Freedman-Diaconis estimator to find n_lags
- ’sturges’ applies Sturge’s rule to find n_lags.
- ’scott’ applies Scott’s rule to find n_lags
- ’doane’ applies Doane’s extension to Sturge’s rule to find n_lags
- ’sqrt’ uses the square-root of distance. as n_lags.
More details are given in the documentation for set_bin_func.
normalize (bool) – Defaults to False. If True, the independent and dependent variable will be normalized to the range [0,1].
fit_method (str) –
String identifying the method to be used for fitting the theoretical variogram function to the experimental. More info is given in the Variogram.fit docs. Can be one of:
- ’lm’: Levenberg-Marquardt algorithm for unconstrained problems. This is the faster algorithm, yet is the fitting of a variogram not unconstrianed.
- ’trf’: Trust Region Reflective function for non-linear constrained problems. The class will set the boundaries itself. This is the default function.
fit_sigma (numpy.ndarray, str) –
Defaults to None. The sigma is used as measure of uncertainty during variogram fit. If fit_sigma is an array, it has to hold n_lags elements, giving the uncertainty for all lags classes. If fit_sigma is None (default), it will give no weight to any lag. Higher values indicate higher uncertainty and will lower the influcence of the corresponding lag class for the fit. If fit_sigma is a string, a pre-defined function of separating distance will be used to fill the array. Can be one of:
- ’linear’: Linear loss with distance. Small bins will have higher impact.
- ’exp’: The weights decrease by a e-function of distance
- ’sqrt’: The weights decrease by the squareroot of distance
- ’sq’: The weights decrease by the squared distance.
More info is given in the Variogram.fit_sigma documentation.
directional_model (string, function) –
The model used for selecting all points fulfilling the directional constraint of the Variogram. A predefined model can be selected by passing the model name as string. Optionally a callable accepting the difference vectors between points in polar form as angles and distances and returning a mask array can be passed. In this case, the azimuth, tolerance and bandwidth has to be incorporated by hand into the model.
- ’compass’: includes points in the direction of the azimuth at given tolerance. The bandwidth parameter will be ignored.
- ’triangle’: constructs a triangle with an angle of tolerance at the point of interest and union an rectangle parallel to azimuth, once the hypotenuse length reaches bandwidth.
- ’circle’: constructs a half circle touching the point of interest, dislocating the center at the distance of bandwidth in the direction of azimuth. The half circle is union with an rectangle parallel to azimuth.
Visual representations, usage hints and implementation specifics are given in the documentation.
azimuth (float) – The azimuth of the directional dependence for this Variogram, given as an angle in degree. The East of the coordinate plane is set to be at 0° and is counted clockwise to 180° and counter-clockwise to -180°. Only Points lying in the azimuth of a specific point will be used for forming point pairs.
tolerance (float) – The tolerance is given as an angle in degree- Points being dislocated from the exact azimuth by half the tolerance will be accepted as well. It’s half the tolerance as the point may be dislocated in the positive and negative direction from the azimuth.
bandwidth (float) – Maximum tolerance acceptable in coordinate units, which is usually meter. Points at higher distances may be far dislocated from the azimuth in terms of coordinate distance, as the tolerance is defined as an angle. THe bandwidth defines a maximum width for the search window. It will be perpendicular to and bisected by the azimuth.
use_nugget (bool) – Defaults to False. If True, a nugget effet will be added to all Variogram.models as a third (or fourth) fitting parameter. A nugget is essentially the y-axis interception of the theoretical variogram function.
maxlag (float, str) – Can specify the maximum lag distance directly by giving a value larger than 1. The binning function will not find any lag class with an edge larger than maxlag. If 0 < maxlag < 1, then maxlag is relative and maxlag * max(Variogram.distance) will be used. In case maxlag is a string it has to be one of ‘median’, ‘mean’. Then the median or mean of all Variogram.distance will be used. Note maxlag=0.5 will use half the maximum separating distance, this is not the same as ‘median’, which is the median of all separating distances
n_lags (int) – Specify the number of lag classes to be defined by the binning function.
verbose (bool) – Set the Verbosity of the class. Not Implemented yet.

Keyword Arguments

entropy_bins (int, str) –

New in version 0.3.7.

If the estimator <skgstat.Variogram.estimator> is set to ‘entropy’ this argument sets the number of bins, that should be used for histogram calculation.
percentile (int) –

New in version 0.3.7.

If the estimator <skgstat.Variogram.estimator> is set to ‘entropy’ this argument sets the percentile to be used.

_calc_direction_mask_data(force=False)[source]¶

Calculate directional mask data. For this, the angle between the vector between the two points, and east (see comment about self.azimuth) is calculated. The result is stored in self._angles and contains the angle of each point pair vector to the x-axis in radians.

Parameters: force (bool) – If True, a new calculation of all angles is forced, even if they are already in the cache.

Notes

The masked data is in radias, while azimuth is given in degrees. For the Vector between a point pair A,B \(\overrightarrow{AB}=u\) and the x-axis, represented by vector \(\overrightarrow{e} = [1,0]\), the angle \(\Theta\) is calculated like:

\[cos(\Theta) = \frac{u \circ e}{|e| \cdot |[1,0]|}\]

See also

azimuth

_triangle(angles, dists)[source]¶

Triangular Search Area

Construct a triangular bounded search area for building directional dependent point pairs. The Search Area will be located onto the current point of interest and the local x-axis is rotated onto the azimuth angle.

Parameters: dists (angles,) – Vectors between point pairs in polar form (angle relative to east in radians, length in coordinate space units)
Returns: mask – Point pair mask, indexed as the results of scipy.spatial.distance.pdist are.
Return type: numpy.array(bool)

Notes

    C
   /|\
a / | \ a
 /__|h_\
A   c   B

The point of interest is C and c is the bandwidth. The angle at C (gamma) is the tolerance. From this, a and then h can be calculated. When rotated into the local coordinate system, the two points needed to build the search area A,B are A := (h, 1/2 c) and B:= (h, -1/2 c)

a can be calculated like:

\[a = \frac{c}{2 * sin\left(\frac{\gamma}{2}\right)}\]

See also

DirectionalVariogram._compass(), DirectionalVariogram._circle()

_compass(angles, dists)[source]¶

Compass direction direction mask

Construct a search area for building directional dependent point pairs. The compass search area will not be bounded by the bandwidth. It will include all point pairs at the azimuth direction with a given tolerance. The Search Area will be located onto the current point of interest and the local x-axis is rotated onto the azimuth angle.

Parameters: dists (angles,) – Vectors between point pairs in polar form (angle relative to east in radians, length in coordinate space units)
Returns: mask – Point pair mask, indexed as the results of scipy.spatial.distance.pdist are.
Return type: numpy.array(bool)

See also

DirectionalVariogram._triangle(), DirectionalVariogram._circle()

_direction_mask(force=False)[source]¶

Directional Mask

Array aligned to self.distance masking all point pairs which shall be ignored for binning and grouping. The one dimensional array contains all row-wise point pair combinations from the upper or lower triangle of the distance matrix in case either of both is directional.

Returns: mask – Array aligned to self.distance giving for each point pair combination a boolean value whether the point are directional or not.
Return type: numpy.array

azimuth¶

Direction azimuth

Main direction for te selection of points in the formation of point pairs. East of the coordinate plane is defined to be 0° and then the azimuth is set clockwise up to 180°and count-clockwise to -180°.

Parameters: angle (float) – New azimuth angle in degree.
Raises: ValueError : in case angle < -180° or angle > 180

bandwidth¶

Tolerance bandwidth

New bandwidth parameter. As the tolerance from azimuth is given as an angle, point pairs at high distances can be far off the azimuth in coordinate distance. The bandwidth limits this distance and has the unnit of the coordinate system.

Parameters: width (float) – Positive coordinate distance.
Raises: ValueError : in case width is negative

bins¶

Distance lag bins

Independent variable of the the experimental variogram sample. The bins are the upper edges of all calculated distance lag classes. If you need bin centers, use get_empirical.

Returns: bins – 1D array of the distance lag classes.
Return type: numpy.ndarray

See also

Variogram.get_empirical

pair_field(ax=None, cmap='gist_rainbow', points='all', add_points=True, alpha=0.3, **kwargs)[source]¶

Plot a pair field.

Plot a network graph for all point pairs that fulfill the direction filter and lie within each others search area.

Parameters

ax (matplotlib.Subplot) – A matplotlib Axes object to plot the pair field onto. If None, a new new matplotlib figure will be created.
cmap (string) – Any color-map name that is supported by matplotlib
points ('all', int, list) – If not 'all', only the given coordinate (int) or list of coordinates (list) will be plotted. Recommended, if the input data is quite large.
add_points (bool) – If True (default) The coordinates will be added as black points.
alpha (float) – Alpha value for the colors to make overlapping vertices visualize better. Defaults to 0.3.

preprocessing(force=False)[source]¶

Preprocessing function

Prepares all input data for the fit and transform functions. Namely, the distances are calculated and the value differences. Then the binning is set up and bin edges are calculated. If any of the listed subsets are already prepared, their processing is skipped. This behaviour can be changed by the force parameter. This will cause a clean preprocessing.

Parameters: force (bool) – If set to True, all preprocessing data sets will be deleted. Use it in case you need a clean preprocessing.
Returns
Return type: void

set_directional_model(model_name)[source]¶

Set new directional model

The model used for selecting all points fulfilling the directional constraint of the Variogram. A predefined model can be selected by passing the model name as string. Optionally a callable accepting the difference vectors between points in polar form as angles and distances and returning a mask array can be passed. In this case, the azimuth, tolerance and bandwidth has to be incorporated by hand into the model. The predefined options are:

‘compass’: includes points in the direction of the azimuth at given tolerance. The bandwidth parameter will be ignored.
‘triangle’: constructs a triangle with an angle of tolerance at the point of interest and union an rectangle parallel to azimuth, once the hypotenuse length reaches bandwidth.
‘circle’: constructs a half circle touching the point of interest, dislocating the center at the distance of bandwidth in the direction of azimuth. The half circle is union with an rectangle parallel to azimuth.

Visual representations, usage hints and implementation specifics are given in the documentation.

Parameters: model_name (string, callable) – The name of the predefined model (string) or a function that accepts angle and distance arrays and returns a mask array.

to_gstools(*args, **kwargs)[source]¶

Instantiate a corresponding GSTools CovModel.

By default, this will be an isotropic model.

Parameters

**kwargs – Keyword arguments forwarded to the instantiated GSTools CovModel. The default parameters ‘dim’, ‘var’, ‘len_scale’, ‘nugget’, ‘rescale’ and optional shape parameters will be extracted from the given Variogram but they can be overwritten here.

Raises

ImportError – When GSTools is not installed.
ValueError – When GSTools version is not v1.3 or greater.
ValueError – When given Variogram model is not supported (‘harmonize’).

Returns

Corresponding GSTools covmodel.

Return type

CovModel

Note

In case you intend to use the coordinates in a GSTools workflow, you need to transpose the coordinate array like:

>> cond_pos Variogram.coordinates.T

tolerance¶

Azimuth tolerance

Tolerance angle of how far a point can be off the azimuth for being still counted as directional. A tolerance angle will be applied to the azimuth angle symmetrically.

Parameters: angle (float) – New tolerance angle in degree. Has to meet 0 <= angle <= 360.
Raises: ValueError : in case angle < 0 or angle > 360

Variogram Class

SpaceTimeVariogram class