xrspatial.focal.hotspots#

xrspatial.focal.hotspots(agg=None, kernel=None, name='hotspots', boundary='nan', *, raster=None)[source]#

Identify statistically significant hot spots and cold spots in an input raster using the Getis-Ord Gi* statistic. To be a statistically significant hot spot, a feature will have a high value and be surrounded by other features with high values as well. Neighborhood of a feature defined by the input kernel, which currently support a shape of circle, annulus, or custom kernel.

For each feature i the Gi* z-score is

Gi* = (sum_j w_ij x_j - Xbar * W_i)

/ (S * sqrt((n * W2_i - W_i^2) / (n - 1)))

where w_ij are the kernel weights (the star variant includes feature i itself), W_i = sum_j w_ij, W2_i = sum_j w_ij^2, Xbar and S are the global mean and population standard deviation of the valid cells, and n is the count of valid (non-NaN) cells. The z-score is then classified into the confidence bands below. NaN cells are excluded from both the neighborhood sums and the global statistics.

The result should be a raster with the following 7 values:

  • 90 for 90% confidence high value cluster

  • 95 for 95% confidence high value cluster

  • 99 for 99% confidence high value cluster

  • 90 for 90% confidence low value cluster

  • 95 for 95% confidence low value cluster

  • 99 for 99% confidence low value cluster

  • 0 for no significance

Parameters:

  • agg (xarray.DataArray) – 2D Input raster image with agg.shape = (height, width). Can be a NumPy backed, CuPy backed, or Dask with NumPy backed DataArray

  • kernel (Numpy Array) – 2D array where values of 1 indicate the kernel.

  • name (str, default='hotspots') – Output xr.DataArray.name property.

  • boundary (str, default='nan') – How to handle edges where the kernel extends beyond the raster. 'nan' – fill missing neighbours with NaN (default). 'nearest' – repeat edge values. 'reflect' – mirror at boundary. 'wrap' – periodic / toroidal.

Returns:

  • hotspots_agg (xarray.DataArray of same type as agg) – 2D array of hotspots with values indicating confidence level.

  • .. deprecated:: – The raster keyword argument is deprecated; use agg.

Examples

>>> import numpy as np
>>> import xarray as xr
>>> from xrspatial.convolution import custom_kernel
>>> kernel = custom_kernel(np.array([[1, 1, 0]]))
>>> data = np.array([
...    [0, 1000, 1000, 0, 0, 0],
...    [0, 0, 0, -1000, -1000, 0],
...    [0, -900, -900, 0, 0, 0],
...    [0, 100, 1000, 0, 0, 0]])
>>> from xrspatial.focal import hotspots
>>> hotspots(xr.DataArray(data), kernel)
array([[  0,   0,  99,   0,   0,   0],
       [  0,   0,   0,   0, -99,   0],
       [  0,   0, -95,   0,   0,   0],
       [  0,   0,   0,   0,   0,   0]], dtype=int8)
Dimensions without coordinates: dim_0, dim_1