xrspatial.focal.hotspots

xrspatial.focal.hotspots(raster, kernel)[source]

Identify statistically significant hot spots and cold spots in an input raster. 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.

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
  • raster (xarray.DataArray) – 2D Input raster image with raster.shape = (height, width).

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

Returns

hotspots_agg – 2D array of hotspots with values indicating confidence level.

Return type

xarray.DataArray of same type as raster

Examples

import matplotlib.pyplot as plt
import numpy as np
import xarray as xr

from xrspatial import generate_terrain, aspect
from xrspatial.convolution import circle_kernel
from xrspatial.focal import hotspots

# Generate Example Terrain
W = 500
H = 300

template_terrain = xr.DataArray(np.zeros((H, W)))
x_range=(-20e6, 20e6)
y_range=(-20e6, 20e6)

terrain_agg = generate_terrain(
    template_terrain, x_range=x_range, y_range=y_range
)

# Edit Attributes
terrain_agg = terrain_agg.assign_attrs(
    {
        'Description': 'Example Terrain',
        'units': 'km',
        'Max Elevation': '4000',
    }
)

terrain_agg = terrain_agg.rename({'x': 'lon', 'y': 'lat'})
terrain_agg = terrain_agg.rename('Elevation')

# Create Kernel
kernel = circle_kernel(10, 10, 100)

# Create Hotspots Aggregate array
hotspots_agg = hotspots(raster = terrain_agg,
                        kernel = kernel)

# Edit Attributes
hotspots_agg = hotspots_agg.rename('Significance')
hotspots_agg = hotspots_agg.assign_attrs(
    {
        'Description': 'Example Hotspots',
        'units': '%',
    }
)

# Plot Terrain
terrain_agg.plot(cmap = 'terrain', aspect = 2, size = 4)
plt.title("Terrain")
plt.ylabel("latitude")
plt.xlabel("longitude")

# Plot Hotspots
hotspots_agg.plot(aspect = 2, size = 4)
plt.title("Hotspots")
plt.ylabel("latitude")
plt.xlabel("longitude")
../../_images/xrspatial-focal-hotspots-1_00.png

(png, hires.png, pdf)

../../_images/xrspatial-focal-hotspots-1_01.png

(png, hires.png, pdf)

>>> print(terrain_agg[200:203, 200:202])
<xarray.DataArray 'Elevation' (lat: 3, lon: 2)>
array([[1264.02296597, 1261.947921  ],
       [1285.37105519, 1282.48079719],
       [1306.02339636, 1303.4069579 ]])
Coordinates:
* lon      (lon) float64 -3.96e+06 -3.88e+06
* lat      (lat) float64 6.733e+06 6.867e+06 7e+06
Attributes:
    res:            (80000.0, 133333.3333333333)
    Description:    Example Terrain
    units:          km
    Max Elevation:  4000

>>> print(hotspots_agg[200:203, 200:202])
<xarray.DataArray 'Significance' (lat: 3, lon: 2)>
array([[0, 0],
       [0, 0],
       [0, 0]], dtype=int8)
Coordinates:
* lon      (lon) float64 -3.96e+06 -3.88e+06
* lat      (lat) float64 6.733e+06 6.867e+06 7e+06
Attributes:
    res:            (80000.0, 133333.3333333333)
    Description:    Example Hotspots
    units:          %
    Max Elevation:  4000