strucDivDom {StrucDiv}

Returns the structural diversity value, the gray level co-occurrence matrix (GLCM) and the structural diversity matrix of the domain.

Description

The function strucDivDom returns the spatial, i.e. horizontal, structural diversity value for the domain (i.e. the input raster). 'Spatial structural diversity' will hereafter be used synonymous to 'structural diversity'. The function also returns the gray level co-occurrence matrix (GLCM) and the structural diversity matrix of the domain. Structural diversity is calculated on every element of the GLCM, which generates the structural diversity matrix.

Usage

strucDivDom(x, dist = 1, angle = "all", rank = FALSE, fun, delta = 0)

Arguments

x

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

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: entropyDom, entropyNormDom, contrastDom, dissimilarityDom, or homogeneityDom. Structural diversity entropy is entropyDom with different delta parameters. Shannon entropy is employed when delta = 0. Shannon entropy has a scale-dependent maximum. Scale-dependent means dependent on the extent of he area within which structural diversity is quantified, because this area defines he total number of pixel pairs. The metric entropyNormDom is Shannon entropy normalized over scale-dependent maximum entropy. Additionally, the value gradient is considered with delta = 1 and 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 metrics contrastDom and dissimilarityDom consider the value gradient, their values are not restricted and depend on the values of the input raster. The metric homogeneityDom quantifies the closeness of empirical probabilities to the diagonal and ranges between 0 and 1.

delta

numeric, takes three options: 0, 1, or 2. The parameter delta is the difference weight, it 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. Defaults to 0 (no weight). Set delta = 1 for absolute weights, or delta = 2 for square weights. 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.

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 strucDivDom can be used.

Value

The output is a list containing the structural diversity value of the domain, which can be accessed with $div. the list also contains the gray level co-occurrence matrix ($GLCM) and the structural diversity matrix ($divMat) of the domain.

Examples

## Not run: 
# Calculate entropy on simulated random patch data
a <- raster::raster(matrix(rnorm(100), 10, 10))
sdivDom <- strucDivDom(a, angle = "vertical", fun = entropyDom)
# Structural diversity value of the domain
div <- sdivDom$div
# Gray level co-occurrence matrix
glcm <- sdivDom$GLCM
# Diversity matrix
divmat <- sdivDom$divMat

## End(Not run)