belg: Boltzmann Entropy of a Landscape Gradient

Jakub Nowosad

2022-12-15

Boltzmann entropy (also called configurational entropy) has been recently adopted to analyze entropy of landscape gradients (Gao et al. (2017), Gao et al. (2018)). The goal of belg is to provide an efficient C++ implementation of this method in R. It also extend the original idea by allowing calculations on data with missing values.

Basic example

library(raster)
library(belg)
complex_land = raster(system.file("raster/complex_land.tif", package = "belg"))
simple_land = raster(system.file("raster/simple_land.tif", package = "belg"))

Let’s take two small rasters - complex_land representing a complex landscape and simple_land representing a simple landscape.

#> Assigning a new crs. Use 'project' to transform a SpatRaster to a new crs
#> Assigning a new crs. Use 'project' to transform a SpatRaster to a new crs
#> Warning: Using `size` aesthetic for lines was deprecated in ggplot2 3.4.0.
#> ℹ Please use `linewidth` instead.

#> Assigning a new crs. Use 'project' to transform a SpatRaster to a new crs
#> Assigning a new crs. Use 'project' to transform a SpatRaster to a new crs

The main function in this package, get_boltzmann(), calculates the Boltzmann entropy of a landscape gradient:

get_boltzmann(complex_land, method = "hierarchy")
#> Assigning a new crs. Use 'project' to transform a SpatRaster to a new crs
#> Assigning a new crs. Use 'project' to transform a SpatRaster to a new crs
#> [1] 191.1567
get_boltzmann(simple_land, method = "hierarchy")
#> Assigning a new crs. Use 'project' to transform a SpatRaster to a new crs
#> Assigning a new crs. Use 'project' to transform a SpatRaster to a new crs
#> [1] 104.8581

The results, unsurprisingly, showed that the complex landscape has a larger value of the Boltzmann entropy than the simple one.

The get_boltzmann() function accepts a RasterLayer, RasterStack, RasterBrick, matrix, or array object as an input. As a default, it uses a logarithm of base 10 (log10), however log and log2 are also available options for the base argument.

get_boltzmann(complex_land, method = "hierarchy") # log10
#> Assigning a new crs. Use 'project' to transform a SpatRaster to a new crs
#> Assigning a new crs. Use 'project' to transform a SpatRaster to a new crs
#> [1] 191.1567
get_boltzmann(complex_land, method = "hierarchy", base = "log")
#> Assigning a new crs. Use 'project' to transform a SpatRaster to a new crs
#> Assigning a new crs. Use 'project' to transform a SpatRaster to a new crs
#> [1] 440.1546
get_boltzmann(complex_land, method = "hierarchy", base = "log2")
#> Assigning a new crs. Use 'project' to transform a SpatRaster to a new crs
#> Assigning a new crs. Use 'project' to transform a SpatRaster to a new crs
#> [1] 635.0089

It also allows for calculation of the relative (the relative argument equal to TRUE) and absolute Boltzmann entropy of a landscape gradient.

Relative Boltzmann entropy of a landscape gradient

The main idea behind the Boltzmann entropy of a landscape gradient is to calculate an entropy in a sliding window of 2 x 2 pixels. The relative configurational entropy is a sum of entropies for all windows of the original data.

get_boltzmann(complex_land, method = "hierarchy", relative = TRUE)
#> Assigning a new crs. Use 'project' to transform a SpatRaster to a new crs
#> Assigning a new crs. Use 'project' to transform a SpatRaster to a new crs
#> [1] 88.55451

Absolute Boltzmann entropy of a landscape gradient

It is possible to calculate an average value for each sliding window of 2 x 2 pixels and therefore create a resampled version of the original dataset:

#> Assigning a new crs. Use 'project' to transform a SpatRaster to a new crs
#> Assigning a new crs. Use 'project' to transform a SpatRaster to a new crs

The absolute configurational entropy is a sum of relative configurational entropies for all levels, starting from the original data to the resampled dataset with at least two rows or columns.

get_boltzmann(complex_land, method = "hierarchy", relative = FALSE)
#> Assigning a new crs. Use 'project' to transform a SpatRaster to a new crs
#> Assigning a new crs. Use 'project' to transform a SpatRaster to a new crs
#> [1] 191.1567

Calculation of the configurational entropy in a sliding window

Determining the number of microstates belonging to a defined macrostate in a crucial concept for calculation of the configurational entropy. We explore this topic using five different cases of 2 x 2 windows:

win_1 = raster(matrix(c(1, 3, 3, 4), ncol = 2))
win_2 = raster(matrix(c(1, 3, 3, NA), ncol = 2))
win_3 = raster(matrix(c(1, 3, NA, NA), ncol = 2))
win_4 = raster(matrix(c(1, NA, NA, NA), ncol = 2))
win_5 = raster(matrix(c(NA, NA, NA, NA), ncol = 2))

Data without missing values

The configurational entropy for data without missing values is calculated using the analytical method by Gao et al. (2018).

Twenty-four different microstate are possible in the above case. The common (base 10) logarithm of 24 is equal to 1.380211. We can compare this result to the get_boltzmann() output:

get_boltzmann(win_1, method = "hierarchy")
#> [1] 1.380211

The generalized (resampled) version of this window has one value, 3, which is a rounded average of the four original values.

Data with missing values

The papers of Gao et al. (2017, 2018) only considered data without missing values. However, the belg package provides a modification allowing for calculation also for data with missing values. Cells with NA are not considered when calculating microstates.

For example, three microstates are possible for the above case:

The common (base 10) logarithm of 3 is equal to 0.477121.

get_boltzmann(win_2, method = "hierarchy")
#> [1] 0.6361617

The generalized (resampled) version of this window is 2.

The third window has two combinations. The common logarithm of 2 is equal to 0.30103.

get_boltzmann(win_3, method = "hierarchy")
#> [1] 0.60206

The generalized (resampled) version of this window is also 2.

The fourth window has only one microstate, therefore its common logarithm equals to 0.

get_boltzmann(win_4, method = "hierarchy")
#> [1] 0

The generalized (resampled) version of this window is the same as only existing value - 1.

Finally, the last window consists of four missing values. In these cases, the configurational entropy is zero.

get_boltzmann(win_5, method = "hierarchy")
#> [1] NaN

Importantly, the generalized version of this window is represented by NA.

References