weave.kernels#

Calculate the smoothing weight for nearby point given current point.

Notes

In general, kernel functions should have the form [1]

\[k(x, y; r) = f\left(\frac{d(x, y)}{r}\right)\]

with components:

  • \(d(x, y)\): distance function

  • \(r\): kernel radius

Kernel functions should also satisfy the following properties:

  1. \(k(x, y; r)\) is real-valued, finite, and nonnegative

  2. \(k(x, y; r)\) is decreasing (or non-increasing) for increasing distances between \(x\) and \(y\):

    • \(k(x, y; r) \leq k(x, y'; r)\) if \(d(x, y) > d(x, y')\)

    • \(k(x, y; r) \geq k(x, y'; r)\) if \(d(x, y) < d(x, y')\)

The exponential(), tricubic(), and depth() kernel functions are modeled after the age, time, and location weights used in CODEm [2] (see the spatial-temporal models sub-section within the methods section). There are many other kernel functions in common use [3].

The kernel functions in this module compute weights using the distance between points as input rather than the points themselves.

References

weave.kernels.exponential(distance, radius)[source]#

Get exponential smoothing weight.

Parameters:

  • distance (nonnegative int or float) – Distance between points.

  • radius (positive int or float) – Kernel radius.

Returns:

Exponential smoothing weight.

Return type:

nonnegative numpy.float32

Notes

The exponential kernel function is defined as

\[k(d; r) = \frac{1}{\exp\left(\frac{d}{r}\right)},\]

which is equivalent to the CODEm age weight

\[w_{a_{i, j}} = \frac{1}{\exp(\omega \cdot d_{i, j})}\]

with \(r = \frac{1}{\omega}\) and \(d_{i, j} =\) weave.distance.euclidean\((a_i, a_j)\).

Examples

Get exponential smoothing weights.

>>> import numpy as np
>>> from weave.kernels import exponential
>>> exponential(0, 0.5)
1.0
>>> exponential(1, 0.5)
0.13533528
>>> exponential(2, 0.5)
0.01831564
weave.kernels.tricubic(distance, radius, exponent)[source]#

Get tricubic smoothing weight.

Parameters:

  • distance (nonnegative int or float) – Distances between points.

  • radius (positive int or float) – Kernel radius.

  • exponent (positive int or float) – Exponent value.

Returns:

Tricubic smoothing weight.

Return type:

nonnegative numpy.float32

Notes

The tricubic kernel function is defined as

\[k(d; r, s) = \left(1 - \left(\frac{d}{r}\right)^s\right)^3_+,\]

which is equivalent to the CODEm time weight

\[w_{t_{i, j}} = \left(1 - \left(\frac{d_{i, j}}{\max_k|t_i - t_k| + 1}\right)^\lambda\right)^3\]

with \(r = \max_k|t_i - t_k| + 1\), \(s = \lambda\), and \(d_{i, j} =\)weave.distance.euclidean\((t_i, t_j)\).

The parameter radius is not assigned in dimension.kernel_pars because it is automatically set to \(\max_k d_{i, k} + 1\). Since the radius depends on \(t_i\), this kernel is not symmetric.

Examples

Get tricubic smoothing weights.

>>> import numpy as np
>>> from weave.kernels import tricubic
>>> tricubic(0, 2, 3)
1.0
>>> tricubic(1, 2, 3)
0.6699219
>>> tricubic(2, 2, 3)
0.0
weave.kernels.depth(distance, levels, radius, version)[source]#

Get depth smoothing weight.

Parameters:

  • distance (nonnegative int or float) – Distance between points.

  • levels (positive int) – Number of levels in distance.tree.

  • radius (float in (0.5, 1)) – Kernel radius.

  • version ({'codem', 'stgpr'}) – Depth kernel version corresponding to CODEm’s location scale factors or ST-GPR’s location scale factors.

Returns:

Depth smoothing weight.

Return type:

nonnegative numpy.float32

Notes

When version = ‘codem’, the depth kernel is defined as

\[\begin{split}k(d; r, s) = \begin{cases} r & \text{if } d = 0, \\ r(1 - r)^{\lceil d \rceil} & \text{if } 0 < d \leq s - 2, \\ (1 - r)^{\lceil d \rceil} & \text{if } s - 2 < d \leq s - 1, \\ 0 & \text{if } d > s - 1, \end{cases}\end{split}\]

which is the same as CODEm’s location scale factors with \(d =\)weave.distance.tree\((\ell_i, \ell_j)\), \(r = \zeta\), and \(s =\) the number of levels in the location hierarchy (e.g., locations with coordinates ‘super_region’, ‘region’, and ‘country’ would have \(s = 3\)). If \(s = 1\), the possible weight values are 1 and 0.

When version = ‘stgpr’, the depth kernel function is defined as

\[\begin{split}k(d; r, s) = \begin{cases} 1 & \text{if } d = 0, \\ r^{\lceil d \rceil} & \text{if } 0 < d \leq s - 1, \\ 0 & \text{if } d > s - 1, \end{cases}\end{split}\]

which is the same as ST-GPR’s location scale factors with \(d =\)weave.distance.tree\((\ell_i, \ell_j)\), \(r = \zeta\), and \(s =\) the number of levels in the location hierarchy (e.g., locations with coordinates ‘super_region’, ‘region’, and ‘country’ would have \(s = 3\)). If \(s = 1\), the possible weight values are 1 and 0.

The parameter levels is not assigned in dimension.kernel_pars because it is automatically set to the length of dimension.coordinates.

Examples

Get weight for a pair of points (CODEm version).

>>> import numpy as np
>>> from weave.kernels import depth
>>> depth(0, 3, 0.9, 'codem')
0.9
>>> depth(1, 3, 0.9, 'codem')
0.09
>>> depth(2, 3, 0.9, 'codem')
0.01
>>> depth(3, 3, 0.9, 'codem')
0.0

Get weight for a pair of points (ST-GPR version).

>>> import numpy as np
>>> from weave.kernels import depth
>>> depth(0, 3, 0.9, 'stgpr')
1.0
>>> depth(1, 3, 0.9, 'stgpr')
0.9
>>> depth(2, 3, 0.9, 'stgpr')
0.81
>>> depth(3, 3, 0.9, 'stgpr')
0.0
weave.kernels.inverse(distance, radius)[source]#

Get inverse-distance smoothing weight.

Parameters:

  • distance (nonnegative int or float) – Distance between points.

  • radius (positive int or float) – Kernel radius.

Returns:

Inverse-distance smoothing weight.

Return type:

nonnegative numpy.float32

Notes

The inverse-distance kernel function for a single dimension is defined as

\[k(d; r) = \frac{d}{r},\]

which is combined over all dimensions \(m \in \mathcal{M}\) to create intermediate weights

\[\tilde{w}_{i,j} = \frac{1} {\sum_{m \in \mathcal{M}} k(d_{i,j}^m; r^m) + \sigma_i^2}.\]

When using inverse-distance weights, all dimension kernels must be set to ‘inverse’, and the stdev argument is required for weave.smoother.Smoother().