strucDiv {StrucDiv}

Quantify Spatial Structural Diversity in an Arbitrary Raster Layer

Description

This is a wrapper function that returns a 'spatial structural diversity map' as a raster layer. Spatial refers to horizontal, i.e. spatially explicit, and 'spatial structural diversity' will hereafter be used synonymous to 'structural diversity'. Pixels are considered as pairs in user-specified distances and angles. Angles include horizontal and vertical direction, and the diagonals at 45° and 135°. The direction-invariant version considers all angles. The frequencies of pixel pairs are normalized by the total number of pixel pairs, which returns the gray level co-occurrence matrix (GLCM). The GLCM contains the empirical probabilities that pixel values are arranged in the specified way (distance and angle). The total number of pixel pairs depends on the extent of the area within which pixel pairs are counted, i.e. on the spatial scale. The spatial scale is defined by the window side length (wsl) of a moving window. The values in a GLCM are the same values that occur in the area within which pixel pairs were counted, therefore they can differ between GLCMs. In each GLCM, pixel values can be replaced with ranks. Structural diversity metrics are calculated on every element of the GLCM, their sum is assigned to the center pixel of the moving window and represents spatial structural diversity of the area captured by the moving window. The final map is called a '(spatial) structural diversity map' and is returned as a raster layer with the same dimensions as the input raster.

Usage

strucDiv(
  x,
  wsl,
  dist = 1,
  angle = "all",
  rank = FALSE,
  fun,
  delta = 0,
  na.handling = na.pass,
  padValue = NA,
  aroundTheGlobe = FALSE,
  filename = "",
  verbose = TRUE,
  ...
)

Arguments

x

raster layer. Input raster layer for which spatial structural diversity should be calculated.

wsl

uneven integer. The window side length, wsl x wsl defines the size of the moving window. The window must be smaller than the dimensions of the input raster. The moving window defines the spatial scale on which spatial structural diversity is quantified.

dist

integer. The distance between two pixels that should be considered as a pair, defaults to dist = 1 (direct neighbors).

angle

string. The angle on which pixels should be considered as pairs. Takes 5 options: "horizontal", "vertical", "diagonal45", "diagonal135", "all". The direction-invariant version is "all", which considers all of the 4 angles. Defaults to "all".

rank

logical. Should pixel values be replaced with ranks in each GLCM? Defaults to FALSE.

fun

function, the structural diversity metric. Takes one of the following: entropy, entropyNorm, contrast, dissimilarity, or homogeneity. Structural diversity entropy is entropy with different delta parameters. Shannon entropy is employed when delta = 0. Shannon entropy has a scale-dependent maximum. Additionally, the value gradient is considered when delta = 1 or delta = 2. The values of structural diversity entropy with delta = 1 or delta = 2 are not restricted and depend on the values of the input raster. The metric entropyNorm is Shannon entropy normalized over maximum entropy, which depends on the size of the moving window. The metric entropyNorm ranges between 0 and 1. The metrics contrast and dissimilarity consider the value gradient, their values are not restricted and depend on the values of the input raster. The metric homogeneity quantifies the closeness of empirical probabilities to the diagonal and ranges between 0 and 1. The metric homogeneity is 1 when all pixel pairs are the same and approaches 0 as differences increase.

delta

numeric, takes three options: 0, 1, or 2. The delta parameter defines how the differences between pixel values within a pixel pair should be weighted. If rank = TRUE, delta defines how the differences between ranks should be weighted. The default value is 0 (no weight). Set delta = 1 for absolute weight, or delta = 2 for squared weight. The delta parameter can only be set when the metric entropy is used. The metric dissimilarity automatically employs delta = 1, and contrast employs delta = 2.

na.handling

na.omit or na.pass. If na.handling = na.omit, NAs are ignored, structural diversity metrics are calculated with less values. In this case the GLCM does not sum to 1. If na.handling = na.pass and if there is at least one missing value inside the moving window, an NA is assigned to the center pixel. Therefore, the diversity map will contain more NAs than the input raster. Defaults to na.pass.

padValue

numeric or NA. The value of the padded cells at the edges of the input raster. Defaults to NA.

aroundTheGlobe

logical. If the input raster goes around the whole globe, set aroundTheGlobe = TRUE, and the input raster will be 'glued together' from both sides to calculate structural diversity without edge effects. Defaults to FALSE.

filename

character. If the output raster should be written to a file, define file name (optional).

verbose

logical. If verbose = TRUE, a progress bar will be visible. Defaults to TRUE.

...

possible further arguments.

Details

The memory requirement of the function is determined by raster::canProcessInMemory(). If the raster file cannot be processed in memory, its size needs to be reduced before strucDiv can be used.

Value

The output is a (spatial) structural diversity map, returned as a raster layer with the same dimensions as the input raster. When na.handling = na.pass, then the output map will have an NA-edge of 0.5*(wsl-1), and it will contain more missing values than the input raster. The output represents spatial structural diversity quantified on a spatial scale defined by the size of the moving window.

Examples

## Not run: 
# Construct a small raster file containing realizations of normal random variables:
a <- raster::raster(matrix(rnorm(648), 18, 36))
raster::plot(a)
# Calculate contrast:
contrast_a <- strucDiv(a, wsl = 3, fun = contrast)
raster::plot(contrast_a)

# Calculate dissimilarity:
b <- raster::raster(matrix(rnorm(100), 10, 10))
raster::plot(b)
dissim_b <- strucDiv(b, wsl = 5, angle = "horizontal", fun = dissimilarity)
raster::plot(dissim_b)

# Calculate structural diversity entropy with delta = 2 on NDVI data binned to 15 gray levels
ndvi.15gl <- raster::raster(ndvi.15gl)
sde_ndvi15 <- strucDiv(ndvi.15gl, wsl = 3, fun = entropy, delta = 2)
raster::plot(sde_ndvi15)

## End(Not run)