Ctrl+K

Experimental#

build_experimental_variogram(input_array, step_size, max_range, weights=None, direction=None, tolerance=1, method='t')[source]
Function prepares:

  • experimental semivariogram,

  • experimental covariogram,

  • variance.

Parameters:
input_arraynumpy array

Spatial coordinates and their values: [pt x, pt y, value] or [shapely.Point(), value].

step_sizefloat

The distance between lags within each points are included in the calculations.

max_rangefloat

The maximum range of analysis.

weightsnumpy array or None, optional, default=None

Weights assigned to points, index of weight must be the same as index of point.

directionfloat (in range [0, 360]), optional

Direction of semivariogram, values from 0 to 360 degrees:

  • 0 or 180: is E-W,

  • 90 or 270 is N-S,

  • 45 or 225 is NE-SW,

  • 135 or 315 is NW-SE.

tolerancefloat (in range [0, 1]), default = 1

If tolerance is 0 then points must be placed at a single line with the beginning in the origin of the coordinate system and the direction given by y axis and direction parameter. If tolerance is > 0 then the bin is selected as an elliptical area with major axis pointed in the same direction as the line for 0 tolerance:

  • the major axis size == step_size,

  • the minor axis size is tolerance * step_size,

  • the baseline point is at a center of the ellipse,

  • the tolerance == 1 creates an omnidirectional semivariogram.

methodstr, default = triangular

The method used for neighbors selection. Available methods:

  • “triangle” or “t”, default method where a point neighbors are selected from a triangular area,

  • “ellipse” or “e”, the most accurate method but also the slowest one.

Returns:
semivariogram_statsEmpiricalSemivariogram

The class with empirical semivariogram, empirical covariogram and a variance.

See also

calculate_covariance

function to calculate experimental covariance and variance of a given set of points.

calculate_semivariance

function to calculate experimental semivariance from a given set of points.

EmpiricalSemivariogram

class that calculates and stores experimental semivariance, covariance and variance.

Notes

Function is an alias for EmpiricalSemivariogram class and it forces calculations of all spatial statistics from a given dataset.

Examples

>>> import numpy as np
>>> REFERENCE_INPUT = np.array([
...    [0, 0, 8],
...    [1, 0, 6],
...    [2, 0, 4],
...    [3, 0, 3],
...    [4, 0, 6],
...    [5, 0, 5],
...    [6, 0, 7],
...    [7, 0, 2],
...    [8, 0, 8],
...    [9, 0, 9],
...    [10, 0, 5],
...    [11, 0, 6],
...    [12, 0, 3]
...    ])
>>> STEP_SIZE = 1
>>> MAX_RANGE = 4
>>> empirical_smv = build_experimental_variogram(REFERENCE_INPUT, step_size=STEP_SIZE, max_range=MAX_RANGE)
>>> print(empirical_smv)
+-----+--------------------+---------------------+--------------------+
| lag |    semivariance    |      covariance     |    var_cov_diff    |
+-----+--------------------+---------------------+--------------------+
| 1.0 |       4.625        |       -0.543        |       4.792        |
| 2.0 |       5.227        |       -0.795        |       5.043        |
| 3.0 |        6.0         |       -1.26         |       5.509        |
+-----+--------------------+---------------------+--------------------+
build_variogram_point_cloud(input_array, step_size, max_range, direction=None, tolerance=1.0)[source]
Function calculates lagged variogram point cloud. Variogram is calculated as a squared difference of each point

against other point within range specified by step_size parameter.

Parameters:
input_arraynumpy array

Spatial coordinates and their values: [pt x, pt y, value] or [shapely.Point(), value].

step_sizefloat

The distance between lags within each points are included in the calculations.

max_rangefloat

The maximum range of analysis.

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

Direction of semivariogram, values from 0 to 360 degrees: - 0 or 180: is E-W, - 90 or 270 is N-S, - 45 or 225 is NE-SW, - 135 or 315 is NW-SE.

tolerancefloat (in range [0, 1]), optional, default=1

If tolerance is 0 then points must be placed at a single line with the beginning in the origin of the coordinate system and the direction given by y axis and direction parameter. If tolerance is > 0 then the bin is selected as an elliptical area with major axis pointed in the same direction as the line for 0 tolerance.

  • The major axis size == step_size.

  • The minor axis size is tolerance * step_size

  • The baseline point is at a center of the ellipse.

  • The tolerance == 1 creates an omnidirectional semivariogram.

Returns:
variogram_cloudDict

{Lag: array of semivariances within a given lag}

class ExperimentalVariogram(input_array, step_size, max_range, weights=None, direction=None, tolerance=1.0, method='t', is_semivariance=True, is_covariance=True)[source]

Class calculates Experimental Semivariogram and Experimental Covariogram of a given dataset.

Parameters:
input_arraynumpy array, list, tuple

  • As a list and numpy array: coordinates and their values: (pt x, pt y, value),

  • as a dict: polyset = {'points': numpy array with coordinates and their values},

  • as a Blocks: Blocks.polyset['points'].

step_sizefloat

The distance between lags within each points are included in the calculations.

max_rangefloat

The maximum range of analysis.

weightsnumpy array, default=None

Weights assigned to points, index of weight must be the same as index of point.

directionfloat (in range [0, 360]), optional

Direction of semivariogram, values from 0 to 360 degrees:

  • 0 or 180: is E-W,

  • 90 or 270 is N-S,

  • 45 or 225 is NE-SW,

  • 135 or 315 is NW-SE.

tolerancefloat (in range [0, 1]), default = 1

If tolerance is 0 then points must be placed at a single line with the beginning in the origin of the coordinate system and the direction given by y axis and direction parameter. If tolerance is > 0 then the bin is selected as an elliptical area with major axis pointed in the same direction as the line for 0 tolerance.

  • The major axis size == step_size.

  • The minor axis size is tolerance * step_size

  • The baseline point is at a center of the ellipse.

  • The tolerance == 1 creates an omnidirectional semivariogram.

methodstr, default = triangular

The method used for neighbors selection. Available methods:

  • “triangle” or “t”, default method where a point neighbors are selected from a triangular area,

  • “ellipse” or “e”, the most accurate method but also the slowest one.

is_semivariancebool, optional, default=True

Should semivariance be calculated?

is_covariancebool, optional, default=True

Should covariance be calculated?

See also

calculate_covariance

function to calculate experimental covariance and variance of a given set of points.

calculate_semivariance

function to calculate experimental semivariance from a given set of points.

Examples

>>> import numpy as np
>>> REFERENCE_INPUT = np.array([
...    [0, 0, 8],
...    [1, 0, 6],
...    [2, 0, 4],
...    [3, 0, 3],
...    [4, 0, 6],
...    [5, 0, 5],
...    [6, 0, 7],
...    [7, 0, 2],
...    [8, 0, 8],
...    [9, 0, 9],
...    [10, 0, 5],
...    [11, 0, 6],
...    [12, 0, 3]
...    ])
>>> STEP_SIZE = 1
>>> MAX_RANGE = 4
>>> empirical_smv = ExperimentalVariogram(REFERENCE_INPUT, step_size=STEP_SIZE, max_range=MAX_RANGE)
>>> print(empirical_smv)
+-----+--------------------+---------------------+--------------------+
| lag |    semivariance    |      covariance     |    var_cov_diff    |
+-----+--------------------+---------------------+--------------------+
| 1.0 |       4.625        | -0.5434027777777798 | 4.791923487836951  |
| 2.0 | 5.2272727272727275 | -0.7954545454545454 | 5.0439752555137165 |
| 3.0 |        6.0         | -1.2599999999999958 | 5.508520710059168  |
+-----+--------------------+---------------------+--------------------+
Attributes:
input_arraynumpy array

The array with coordinates and observed values.

experimental_semivariance_arraynumpy array or None, optional, default=None

The array of semivariance per lag in the form: (lag, semivariance, number of points within lag).

experimental_covariance_arraynumpy array or None, optional, default=None

The array of covariance per lag in the form: (lag, covariance, number of points within lag).

experimental_semivariancesnumpy array or None, optional, default=None

The array of semivariances.

experimental_covariancesnumpy array or None, optional, default=None

The array of covariances.

variance_covariances_diffnumpy array or None, optional, default=None

The array of differences $c(0) - c(h)$.

lagsnumpy array or None, default=None

The array of lags (upper bound for each lag).

points_per_lagnumpy array or None, default=None

A number of points in each lag-bin.

variancefloat or None, optional, default=None

The variance of a dataset, if data is second-order stationary then we are able to retrieve a semivariance s a difference between the variance and the experimental covariance:

\[g(h) = c(0) - c(h)\]

where:

  • \(g(h)\): semivariance at a given lag h,

  • \(c(0)\): variance of a dataset,

  • \(c(h)\): covariance of a dataset.

Important! Have in mind that it works only if process is second-order stationary (variance is the same for each distance bin) and if the semivariogram has the upper bound.

stepfloat

Derived from the step_size parameter.

mx_rngfloat

Derived from the max_range parameter.

weightsnumpy array or None

Derived from the weights parameter.

direct: float

Derived from the direction parameter.

tolfloat

Derived from the tolerance parameter.

methodstr

See the method parameter.

Methods

plot()

Shows experimental variances.
plot(plot_semivariance=True, plot_covariance=True, plot_variance=True)[source]
Parameters:
plot_semivariancebool, default=True

Show semivariance on a plot. If class attribute is_semivariance is set to False then semivariance is not plotted and warning is printed.

plot_covariancebool, default=True

Show covariance on a plot. If class attribute is_covariance is set to False then covariance is not plotted and warning is printed.

plot_variancebool, default=True

Show variance level on a plot.

Warns:
AttributeSetToFalseWarning

Warning invoked when plotting parameter for semivariance, covariance or variance is set to True but class attributes to calculate those indices are set to False.

class VariogramCloud(input_array, step_size, max_range, direction=0, tolerance=1, calculate_on_creation=True)[source]

Class calculates Variogram Point Cloud and presents it in a scatterplot, boxplot and violinplot.

Parameters:
input_arraynumpy array

Spatial coordinates and their values: [pt x, pt y, value] or [shapely.Point(), value].

step_sizefloat

The distance between lags within each points are included in the calculations.

max_rangefloat

The maximum range of analysis.

directionfloat (in range [0, 360]), optional, default=None

Direction of semivariogram, values from 0 to 360 degrees:

  • 0 or 180: is E-W,

  • 90 or 270 is N-S,

  • 45 or 225 is NE-SW,

  • 135 or 315 is NW-SE.

tolerancefloat (in range [0, 1]), optional, default=1

If tolerance is 0 then points must be placed at a single line with the beginning in the origin of the coordinate system and the direction given by y axis and direction parameter. If tolerance is > 0 then the bin is selected as an elliptical area with major axis pointed in the same direction as the line for 0 tolerance.

  • The major axis size == step_size.

  • The minor axis size is tolerance * step_size

  • The baseline point is at a center of the ellipse.

  • The tolerance == 1 creates an omnidirectional semivariogram.

See also

get_variogram_point_cloud

function to calculate variogram point cloud, class VariogramCloud is a wrapper around it.

ExperimentalVariogram

class that calculates experimental semivariogram, experimental covariogram and data variance.

Examples

>>> import numpy as np
>>> REFERENCE_INPUT = np.array([
...    [0, 0, 8],
...    [1, 0, 6],
...    [2, 0, 4],
...    [3, 0, 3],
...    [4, 0, 6],
...    [5, 0, 5],
...    [6, 0, 7],
...    [7, 0, 2],
...    [8, 0, 8],
...    [9, 0, 9],
...    [10, 0, 5],
...    [11, 0, 6],
...    [12, 0, 3]
...    ])
>>> STEP_SIZE = 1
>>> MAX_RANGE = 4
>>> point_cloud = VariogramCloud(REFERENCE_INPUT, step_size=STEP_SIZE, max_range=MAX_RANGE)
# >>> print(point_cloud)
# +-----+--------------------+---------------------+--------------------+
# | lag |    count    |      avg semivariance    |    std  | min | 25% | median | 75% | max | skewness | kurtosis |
# +-----+--------------------+---------------------+--------------------+
# | 1.0 |       4.625        | -0.5434027777777798 | 4.791923487836951  |
# | 2.0 | 5.22727272727272 | -0.7954545454545454 | 5.0439752555137165 |
# | 3.0 |        6.0         | -1.2599999999999958 | 5.508520710059168  |
# +-----+--------------------+---------------------+--------------------+
Attributes:
input_arraynumpy array

The array with coordinates and observed values.

experimental_point_clouddict or None, default=None

Dict {lag: [variances]}.

lagsnumpy array or None, default=None

The array of lags (upper bound for each lag).

points_per_lagint or None, default=None

A number of points in each lag-bin.

stepfloat

Derived from the step_size parameter.

mx_rngfloat

Derived from the max_range parameter.

direct: float

Derived from the direction parameter.

tolfloat

Derived from the tolerance parameter.

calculate_on_creationbool, default=True

Perform calculations of semivariogram point cloud when object is initialized.

Methods

calculate_experimental_variogram()

Method calculates experimental variogram from a point cloud.

describe()

calculates statistics for point clouds. It is invoked by default by class __str__() method.

plot(kind=’scatter’)

plots scatterplot, boxplot or violinplot of a point cloud.

remove_outliers()

Removes outliers from a semivariance scatterplots.
calculate_experimental_variogram()[source]

Method transforms the experimental point cloud into the experimental variogram.

Raises:
RunetimeError

The attribute experimental_point_cloud is not calculated.

describe()[source]

Method calculates basic statistcs of a data: count (point pairs number), average semivariance, standard deviation, minimum, 1st quartile, median, 3rd quartile, maximum, skewness, kurtosis.

Returns:
statisticsDict
>>> statistics = {
...      lag_number:
...      {
...          'count': point pairs count,
...          'avg semivariance': mean semivariance,
...          'std': standard deviation,
...          'min': minimal variance,
...          '25%': first quartile of variances,
...          'median': second quartile of variances,
...          '75%': third quartile of variances,
...          'max': max variance,
...          'skewness': skewness,
...          'kurtosis': kurtosis
...      }
...  }
plot(kind='scatter')[source]

Method plots variogram point cloud.

Parameters:
kindstring, default=’scatter’

available plot types: ‘scatter’, ‘box’, ‘violin’

Returns:
: bool

True if Figure was plotted.

remove_outliers(method='zscore', z_lower_limit=-3, z_upper_limit=3, iqr_lower_limit=1.5, iqr_upper_limit=1.5, inplace=False)[source]
Parameters:
methodstr, default=’zscore’

Method used to detect outliers. Can be ‘zscore’ or ‘iqr’.

z_lower_limitfloat

Number of standard deviations from the mean to the left side of a distribution. Must be lower than 0.

z_upper_limitfloat

Number of standard deviations from the mean to the right side of a distribution. Must be greater than 0.

iqr_lower_limitfloat

Number of standard deviations from the 1st quartile into the lowest values. Must be greater or equal to zero.

iqr_upper_limitfloat

Number of standard deviations from the 3rd quartile into the largest values. Must be greater or equal to zero.

inplacebool, default=False

If set to True then method updates experimental_point_cloud attribute of the existing object and returns nothing. Else new VariogramCloud object is returned.

Returns:
cleanedVariogramCloud

VariogramCloud object with removed outliers from the experimental_point_cloud attribute.

Raises:
RunetimeError

The attribute experimental_point_cloud is not calculated.

Show Source