Block

class AggregatedVariogram(aggregated_data, agg_step_size, agg_max_range, point_support, agg_direction=0, agg_tolerance=1, agg_nugget=0, variogram_weighting_method='closest', verbose=False, log_process=False)

Class calculates semivariance of aggregated counts.

Parameters:

aggregated_dataUnion[Blocks, gpd.GeoDataFrame, pd.DataFrame, np.ndarray]

Blocks with aggregated data.

• Blocks: Blocks() class object.

• GeoDataFrame and DataFrame must have columns: centroid.x, centroid.y, ds, index. Geometry column with polygons is not used.

• numpy array: [[block index, centroid x, centroid y, value]].

agg_step_sizefloat

Step size between lags.

agg_max_rangefloat

Maximal distance of analysis.

point_supportUnion[Dict, np.ndarray, gpd.GeoDataFrame, pd.DataFrame, PointSupport]

• Dict: {block id: [[point x, point y, value]]}

• numpy array: [[block id, x, y, value]]

• DataFrame and GeoDataFrame: columns = {x, y, ds, index}

• PointSupport

agg_directionfloat (in range [0, 360]), default=0

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.

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

If agg_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 agg_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 == agg_step_size.

• The minor axis size is agg_tolerance * agg_step_size

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

• agg_tolerance == 1 creates an omnidirectional semivariogram.

agg_nuggetfloat, default = 0

The nugget of blocks data.

variogram_weighting_methodstr, default = “closest”

Method used to weight error at a given lags. 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 - more pairs, lesser weight.

verbosebool, default = False

Print steps performed by the algorithm.

log_processbool, default = False

Log process info (Level DEBUG).

References

[1] Goovaerts P., Kriging and Semivariogram Deconvolution in the Presence of Irregular Geographical Units, Mathematical Geology 40(1), 101-128, 2008

Attributes:

aggregated_dataUnion[Blocks, Dict, gpd.GeoDataFrame, pd.DataFrame, np.ndarray]

See aggregared_data parameter.

agg_step_sizefloat

See agg_step_size parameter.

agg_max_rangefloat

See agg_max_range parameter.

agg_lagsnumpy array

Lags calculated as a set of equidistant points from agg_step_size to agg_max_range with a step of size agg_step_size.

agg_tolerancefloat, default = 1

See agg_tolerance parameter.

agg_directionfloat, default = 0

See agg_direction parameter.

agg_nuggetfloat, default = 0

See agg_nugget parameter.

point_supportUnion[Dict, np.ndarray, gpd.GeoDataFrame, pd.DataFrame, PointSupport]

See the point_support parameter.

weighting_methodstr, default = ‘closest’

See the variogram_weighting_method parameter.

verbosebool, default = False

See verbose parameter.

log_processbool, default = False

See the log_process parameter.

experimental_variogramExperimentalVariogram

The experimental variogram calculated from blocks (their centroids).

theoretical_modelTheoreticalVariogram

The theoretical model derived from blocks’ centroids.

inblock_semivarianceDict

{area id: the average inblock semivariance}

avg_inblock_semivariancenumpy array

[lag, average inblocks semivariances, number of blocks within a lag]

block_to_block_semivarianceDict

{(block i, block j): [distance, semivariance, number of point pairs between blocks]}

avg_block_to_block_semivariancenumpy array

[lag, semivariance, number of point pairs between blocks].

regularized_variogramnumpy array

[lag, semivariance]

distances_between_blocksDict

Weighted distances between all blocks: {block id : [distances to other blocks]}.

Methods

regularize()	Method performs semivariogram regularization.
show_semivariograms()	Shows experimental variogram, theoretical model, average inblock semivariance, average block to block semivariance and regularized variogram.

calculate_avg_inblock_semivariance()

Method calculates the average semivariance within blocks \(\gamma_h(v, v)\). The average inblock semivariance is calculated as:

\[\gamma_h(v, v) = \frac{1}{(2*N(h))} \sum_{a=1}^{N(h)} [\gamma(v_{a}, v_{a}) + \gamma(v_{a+h}, v_{a+h})]\]

where:

• \(\gamma(v_{a}, v_{a})\) is a semivariance within a block \(a\),

• \(\gamma(v_{a+h}, v_{a+h})\) is samivariance within a block at a distance \(h\) from the block \(a\).

Returns:

avg_inblock_semivariancenumpy array

[lag, semivariance, number of block pairs]

calculate_avg_semivariance_between_blocks()

Function calculates semivariance between areas based on their division into smaller blocks. It is \(\gamma(v, v_h)\) - semivariogram value between any two blocks separated by the distance h.

Returns:

avg_block_to_block_semivariancenumpy array

The average semivariance between neighboring blocks point-supports: [lag, semivariance, number of block pairs within a range].

Notes

Block-to-block semivariance is calculated as:

\[\gamma(v_{a}, v_{a+h})=\frac{1}{P_{a}P_{a+h}}\sum_{s=1}^{P_{a}}\sum_{s'=1}^{P_{a+h}}\gamma(u_{s}, u_{s'})\]

where:

• \(\gamma(v_{a}, v_{a+h})\) - block-to-block semivariance of block \(a\) and paired block \(a+h\).

• \(P_{a}$ and $P_{a+h}\) - number of support points within block \(a\) and block \(a+h\).

• \(\gamma(u_{s}, u_{s'})\) - semivariance of point supports between blocks.

Then average block-to-block semivariance is calculated as:

\[\gamma_{h}(v, v_{h}) = \frac{1}{N(h)}\sum_{a=1}^{N(h)}\gamma(v_{a}, v_{a+h})\]

where:

• \(\gamma_{h}(v, v_{h})\) - averaged block-to-block semivariances for a lag \(h\),

• \(\gamma(v_{a}, v_{a+h})\) - semivariance of block \(a\) and paired block at a distance \(h\).

regularize(average_inblock_semivariances=None, semivariance_between_point_supports=None, experimental_block_variogram=None, theoretical_block_model=None)

Method regularizes point support model. Procedure is described in [1].

Parameters:

average_inblock_semivariancesnp.ndarray, default = None

The mean semivariance between the blocks. See Notes to learn more.

semivariance_between_point_supportsnp.ndarray, default = None

Semivariance between all blocks calculated from the theoretical model.

experimental_block_variogramnp.ndarray, default = None

The experimental semivariance between area centroids.

theoretical_block_modelTheoreticalVariogram, default = None

A modeled variogram.

Returns:

regularized_modelnumpy array

[lag, semivariance, number of point pairs]

Notes

Function has the form:

\[\gamma_v(h) = \gamma(v, v_h) - \gamma_h(v, v)\]

where:

• \(\gamma_v(h)\) - the regularized variogram,

• \(\gamma(v, v_h)\) - a variogram value between any two blocks separated by the distance \(h\) (calculated from their point support),

• \(\gamma_h(v, v)\) - average inblock semivariance between blocks.

Average inblock semivariance between blocks:

\[\gamma_h(v, v) = \frac{1}{(2*N(h))} \sum_{a=1}^{N(h)} [\gamma(v_{a}, v_{a}) + \gamma(v_{a+h}, v_{a+h})]\]

where \(\gamma(v_{a}, v_{a})\) and \(\gamma(v_{a+h}, v_{a+h})\) are inblock semivariances of block \(a\) and block \(a+h\) separated by the distance \(h\).

References

[1] Goovaerts P., Kriging and Semivariogram Deconvolution in the Presence of Irregular Geographical Units,

Mathematical Geology 40(1), 101-128, 2008

regularize_variogram()

Function regularizes semivariograms.

Returns:

reg_variogramnumpy array

[lag, semivariance]

Raises:

ValueError

Semivariance at a given lag is below zero.

Notes

Regularized semivariogram is a difference between the average block to block semivariance \(\gamma(v, v_{h})\) and the average inblock semivariances \(\gamma{h}(v, v)\) at a given lag \(h\).

\[\gamma_{v}(h)=\gamma(v, v_{h}) - \gamma{h}(v, v)\]

show_semivariograms()

Method plots:

• experimental variogram,

• theoretical model,

• average inblock semivariance,

• average block-to-block semivariance,

• regularized variogram.

Raises:

AttributeError

The semivariogram regularization process has not been performed.