# StrucDiv

## StrucDiv: Spatial structural diversity quantification in raster data

Spatial structural diversity refers to the spatial, i.e. horizontal, configuration of landscape elements. The StrucDiv package provides methods to quantify spatial structural diversity, hereafter structural diversity, in raster data, i.e. data in gridded field format. This means that landscape elements are pixels. The methods are based on the spatial arrangement of pixels as pairs, based on Haralick, Shanmugam, and Dinstein (1973). Pixels are considered as pairs at user-specified distances and angles. Distance refers to the distance between the two pixels that are considered a pair. Angle refers to the angle at which two pixels are considered a pair. Angles can be horizontal or vertical direction, or the diagonals at 45° or 135°. The direction-invariant version considers all angles.

The frequencies of pixel pair occurrences are normalized by the total number of pixel pairs, which returns the gray level co-occurrence matrix (GLCM). The GLCM contains the empirical probabilities $$P_{i,j}$$ that pixel values v$$_{i}$$ and v$$_{j}$$ occur as a pair at the specified distance and angle(s), in the area within which pixel pairs are counted. 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.

Pixel values v$$_{i}$$ and v$$_{j}$$ that occur as a pair enter the GLCM as row and column names, hence $$i$$ and $$j$$ index the position of a pixel value in the GLCM. The values at positions $$i$$ and $$j$$ can differ between GLCMs. Instead of pixel values v$$_{i}$$ and v$$_{j}$$, ranks (r, s) can be considered. Ranks refer to the position of the pixel value in the GLCM, hence the value associated with a rank can differ between GLCMs. The total (GLCM-specific) number of values is denoted with $$m$$, and the total (GLCM-specific) number of ranks is denoted with $$l$$.

Diversity metrics are calculated for every element of the GLCM, and their sum is assigned to the center pixel of the moving window and represents structural diversity of the window. The final map is called a ‘structural diversity map.’

Diversity metrics include second-order texture metrics: contrast, dissimilarity, homogeneity and entropy (i.e. Shannon entropy). Additionally, structural diversity entropy includes a difference weight $$\delta \in \{1,2\}$$, which weighs the difference between pixel values v$$_{i}$$ and v$$_{j}$$, either by absolute, or by squared differences. When $$\delta$$ = 0, structural diversity entropy corresponds to Shannon entropy. Dissimilarity naturally employs $$\delta = 1$$, contrast employs $$\delta = 2$$, and homogeneity employs $$\delta = 2$$ in the denominator. Furthermore, normalized entropy is available. Normalized entropy is Shannon entropy normalized over maximum entropy. Maximum entropy depends on the extent of the area within which pixel pairs are counted, i.e. on the spatial scale. These methods can be applied to any continuous raster data, or continuous raster data that is binned to reduce the number of gray levels (GL). The methods can also be applied to categorical data if categories are numbered in a meaningful way, or if entropy or normalized entropy are used. This is because otherwise $$\delta$$ cannot be computed or is meaningless.

For entropy, normalized entropy, and homogeneity, the possible number of GL is restricted, i.e. high numbers of GL lead to structureless diversity maps (Schuh et al. 2020).

With these methods, structural diversity features can be detected. Structural diversity features are also called latent landscape features. Typical structural diversity features include narrow borders, line features, patches and hotspots Schuh et al. (2021).

### Structural diversity metrics using pixel values

\begin{align} \text{Structural diversity entropy} & = \ - \sum_{i,j=1}^{m} P_{ij} \ln P_{ij} \ |v_{i}-v_{j}| ^ \delta, \delta \in \{0,1,2\} \label{DivEnt} \\ \text{Contrast} & = \sum_{i,j=1}^{m} P_{ij} \ |v_{i}-v_{j}| ^ \delta, \delta = 2 \label{ValCon} \\ \text{Dissimilarity} & = \sum_{i,j=1}^{m} P_{ij} \ |v_{i}-v_{j}| ^\delta, \delta = 1 \label{ValDis} \\ \text{Homogeneity} & = \sum_{i,j=1}^{m} P_{ij} / (1 + |i-j|^\delta), \delta = 2 \label{ValHom} \end{align}

### Structural diversity metrics using ranks

\begin{align} \text{Structural diversity entropy} & = \ - \sum_{r,s=1}^{l} P_{rs} \ln P_{rs} \ |r-s| ^ \delta, \delta \in \{0,1,2\} \label{RankDivEnt}\\ \text{Contrast} & = \sum_{r,s=1}^{l} P_{rs} \ |r-s| ^ \delta, \delta = 2 \label{RankCon} \\ \text{Dissimilarity} & = \sum_{r,s=1}^{l} P_{rs} \ |r-s| ^ \delta, \delta = 1 \label{ConDis} \\ \text{Homogeneity} & = \sum_{r,s=1}^{l} P_{rs} / (1 + |r-s|^\delta), \delta = 2 \label{HomRank} \end{align}

## Installation

You can install the released version of StrucDiv from CRAN with:

install.packages("StrucDiv")

## Example

Calculate normalized entropy on Normalized Difference Vegetation Index (NDVI) data, which was binned to 15 GL (see data documentation). We define the size of the moving window with WSL three, and we consider distance one between pixels (i.e. direct neighbors), and a direction-invariant approach.


entNorm <- StrucDiv(ndvi.15gl, wsl = 5, dist = 1, angle = "all", fun = entropyNorm,
na.handling = na.pass)

## References

Haralick, R. M., K. Shanmugam, and I. Dinstein. 1973. “Textural Features for Image Classification.” IEEE Transactions on Systems, Man, and Cybernetics SMC-3 (6): 610–21. https://doi.org/10.1109/TSMC.1973.4309314.
Schuh, L., M. J. Santos, R. de Jong, M. Schaepman, and R. Furrer. 2021. Structural Diversity Entropy: A Unified Diversity Measure to Detect Latent Landscape Features. Under review.
Schuh, L., M. Schaepman, M. J. Santos, R. de Jong, and R. Furrer. 2020. “Advancing Texture Metrics to Model Landscape Heterogeneity.” In IGARSS 2020 - 2020 IEEE International Geoscience and Remote Sensing Symposium, 2735–38. https://doi.org/10.1109/IGARSS39084.2020.9323930.