Merge pull request #8 from r-spatialecology/aggregation

Aggregation

DESCRIPTION

@@ -1,10 +1,11 @@
 Package: belg
 Title: Boltzmann Entropy of a Landscape Gradient
-Version: 0.2.3
+Version: 1.0.0
 Description: Calculates the Boltzmann entropy of a landscape gradient.
     This package uses the analytical method created by Gao, P., Zhang, H.
-    and Li, Z., 2018 (<doi:10.1111/tgis.12315>). It also extend the original 
-    idea by allowing calculations on data with missing values.
+    and Li, Z., 2018 (<doi:10.1111/tgis.12315>) and by Gao, P. and Li, Z., 2019
+    (<doi:10.1007/s10980-019-00854-3>). It also extend the original ideas by
+    allowing calculations on data with missing values.
 Authors@R: c(person("Jakub", "Nowosad", 
     email = "nowosad.jakub@gmail.com",
     role = c("aut", "cre"),
@@ -33,6 +34,6 @@ Suggests:
     rmarkdown,
     ggplot2,
     rasterVis
-URL: https://github.com/r-spatialecology/belg
+URL: https://r-spatialecology.github.io/belg/
 BugReports: https://github.com/r-spatialecology/belg/issues
 VignetteBuilder: knitr

NEWS.md

@@ -1,3 +1,8 @@
+# belg 1.0.0
+
+* The "Aggregation-based method for computing absolute Boltzmann entropy of landscape gradient with full thermodynamic consistency" (<doi:10.1007/s10980-019-00854-3>) added
+* New datasets added
+
 # belg 0.2.1
 
 * The first vignette added

R/RcppExports.R

@@ -5,3 +5,7 @@ get_boltzmann_default <- function(x, base, relative) {
     .Call('_belg_get_boltzmann_default', PACKAGE = 'belg', x, base, relative)
 }
 
+get_boltzmann_aggregation <- function(x, base, relative) {
+    .Call('_belg_get_boltzmann_aggregation', PACKAGE = 'belg', x, base, relative)
+}
+

R/datasets.R

@@ -1,11 +1,23 @@
+#' Complex landscape (small)
+#'
+#' A dataset containing small artificial complex landscape
+#'
+"complex_land"
+
+#' Simple landscape (small)
+#'
+#' A dataset containing small artificial simple landscape
+#'
+"simple_land"
+
 #' Complex landscape
 #'
 #' A dataset containing artificial complex landscape
 #'
-"complex_land"
+"land_gradient1"
 
 #' Simple landscape
 #'
 #' A dataset containing artificial simple landscape
 #'
-"simple_land"
+"land_gradient2"

R/get_boltzmann.R

@@ -5,6 +5,9 @@
 #' @param x RasterLayer, RasterStack, RasterBrick, matrix, or array
 #' @param base A logarithm base ("log", "log2" or "log10")
 #' @param relative TRUE/FALSE
+#' @param method A method used. Either "hierarchy" (default) for
+#' the hierarchy-based method (Gao et al., 2017) or "aggregation"
+#' for the aggregation-based method (Gao et al., 2019)
 #'
 #' @return a numeric vector
 #'
@@ -22,58 +25,77 @@
 #' analytical method for computing the Boltzmann entropy of a landscape
 #' gradient." Transactions in GIS (2018).
 #'
+#' @references Gao, Peichao and Zhilin Li. "Aggregation-based method
+#' for computing absolute Boltzmann entropy of landscape gradient
+#' with full thermodynamic consistency"
+#' Landscape Ecology (2019)
+#'
 #' @examples
 #' new_c = c(56, 86, 98, 50, 45, 56, 96, 25,
 #'           15, 55, 85, 69, 12, 52, 25, 56,
 #'           32, 25, 68, 98, 58, 66, 56, 58)
 #'
+#'
 #' lg = matrix(new_c, nrow = 3, ncol = 8, byrow = TRUE)
 #' get_boltzmann(lg, relative = FALSE, base = "log10")
 #' get_boltzmann(lg, relative = TRUE, base = "log2")
 #' get_boltzmann(lg, relative = TRUE, base = "log")
 #'
+#' \donttest{
+#'   get_boltzmann(lg, relative = FALSE, method = "aggregation")
+#'   get_boltzmann(lg, relative = TRUE, method = "aggregation")
+#' }
+#'
 #' @name get_boltzmann
 #' @export
-get_boltzmann = function(x, base = "log10", relative = FALSE) UseMethod("get_boltzmann")
+get_boltzmann = function(x, base = "log10", relative = FALSE, method = "hierarchy") UseMethod("get_boltzmann")
 
 #' @name get_boltzmann
 #' @export
-get_boltzmann.default = function(x, base = "log10", relative = FALSE){
-  get_boltzmann_default(x, base, relative)
+get_boltzmann.default = function(x, base = "log10", relative = FALSE, method = "hierarchy"){
+  if (method == "hierarchy"){
+    get_boltzmann_default(x, base, relative)
+  } else if (method == "aggregation"){
+    get_boltzmann_aggregation(x, base, relative)
+  }
 }
 
 #' @name get_boltzmann
 #' @export
-get_boltzmann.array = function(x, base = "log10", relative = FALSE){
-  apply(x, MARGIN = 3, get_boltzmann_default, base, relative)
+get_boltzmann.array = function(x, base = "log10", relative = FALSE, method = "hierarchy"){
+  if (method == "hierarchy"){
+    apply(x, MARGIN = 3, get_boltzmann_default, base, relative)
+  } else if (method == "aggregation"){
+    apply(x, MARGIN = 3, get_boltzmann_aggregation, base, relative)
+  }
 }
 
 #' @name get_boltzmann
 #' @export
-get_boltzmann.RasterLayer = function(x, base = "log10", relative = FALSE){
+get_boltzmann.RasterLayer = function(x, base = "log10", relative = FALSE, method = "hierarchy"){
   if (!requireNamespace("sp", quietly = TRUE))
     stop("Package sp required, please install it first")
   if (!requireNamespace("raster", quietly = TRUE))
     stop("Package raster required, please install it first")
-  get_boltzmann(raster::as.matrix(x), base = base, relative = relative)
+  get_boltzmann(raster::as.matrix(x), base = base, relative = relative, method = method)
 }
 
 #' @name get_boltzmann
 #' @export
-get_boltzmann.RasterStack = function(x, base = "log10", relative = FALSE){
+get_boltzmann.RasterStack = function(x, base = "log10", relative = FALSE, method = "hierarchy"){
   if (!requireNamespace("sp", quietly = TRUE))
     stop("Package sp required, please install it first")
   if (!requireNamespace("raster", quietly = TRUE))
     stop("Package raster required, please install it first")
-  get_boltzmann(raster::as.array(x), base = base, relative = relative)
+  get_boltzmann(raster::as.array(x), base = base, relative = relative, method = method)
 }
 
 #' @name get_boltzmann
 #' @export
-get_boltzmann.RasterBrick = function(x, base = "log10", relative = FALSE){
+get_boltzmann.RasterBrick = function(x, base = "log10", relative = FALSE, method = "hierarchy"){
   if (!requireNamespace("sp", quietly = TRUE))
     stop("Package sp required, please install it first")
   if (!requireNamespace("raster", quietly = TRUE))
     stop("Package raster required, please install it first")
-  get_boltzmann(raster::as.array(x), base = base, relative = relative)
+  get_boltzmann(raster::as.array(x), base = base, relative = relative, method = method)
 }

README.Rmd

@@ -20,7 +20,7 @@ knitr::opts_chunk$set(
 [![CRAN RStudio mirror downloads](http://cranlogs.r-pkg.org/badges/belg)](https://cran.r-project.org/package=belg)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.1209419.svg)](https://doi.org/10.5281/zenodo.1209419)
 
-Boltzmann entropy (also called configurational entropy) has been recently adopted to analyze entropy of landscape gradients (Gao et al. (2017), Gao et al. (2018)).
+Boltzmann entropy (also called configurational entropy) has been recently adopted to analyze entropy of landscape gradients (Gao et al. (2017, 2018, 2019)).
 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.
 
@@ -41,33 +41,41 @@ devtools::install_github("r-spatialecology/belg")
 
 ## Examples
 
-As an example, we use two small rasters - `complex_land` representing a complex landscape and `simple_land` representing a simple landscape:
+As an example, we use two rasters - `land_gradient1` representing a complex landscape and `land_gradient2` representing a simple landscape:
 
 ```{r, message=FALSE, fig.height=3}
 library(raster)
 library(belg)
-plot(stack(complex_land, simple_land))
+plot(stack(land_gradient1, land_gradient2))
 ```
 
-The main function in this package, `get_boltzmann`, calculates the Boltzmann entropy of a landscape gradient:
+The main function in this package, `get_boltzmann()`, calculates the Boltzmann entropy of a landscape gradient:
 
 ```{r}
-get_boltzmann(complex_land)
-get_boltzmann(simple_land)
+get_boltzmann(land_gradient1)
+get_boltzmann(land_gradient2)
 ```
 
 This function accepts a `RasterLayer`, `RasterStack`, `RasterBrick`, `matrix`, or `array` object as an input.
-It also allows for calculation of the relative (the `relative` argument equal to `TRUE`) and absolute Boltzmann entropy of a landscape gradient.
+It allows for calculation of the relative (the `relative` argument equal to `TRUE`) and absolute Boltzmann entropy of a landscape gradient.
 As a default, it uses a logarithm of base 10 (`log10`), however `log` and `log2` are also available options for the `base` argument.
 
 ```{r}
-get_boltzmann(complex_land, base = "log")
-get_boltzmann(complex_land, relative = TRUE)
-get_boltzmann(complex_land, base = "log2", relative = TRUE)
+get_boltzmann(land_gradient1, base = "log")
+get_boltzmann(land_gradient1, relative = TRUE)
+get_boltzmann(land_gradient1, base = "log2", relative = TRUE)
+```
+
+Two methods of calculating the Boltzmann entropy of a landscape gradient are available: `"hierarchy"` (default) for the hierarchy-based method (Gao et al., 2017) or `"aggregation"` for the aggregation-based method (Gao et al., 2019).
+The aggregation-based method requires that the number of rows and columns in the input data must be a multiple of 2.
+
+```{r}
+get_boltzmann(land_gradient1, method = "aggregation")
+get_boltzmann(land_gradient1, relative = TRUE, method = "aggregation")
 ```
 
 ## References
 
-- Gao, Peichao, Hong Zhang, and Zhilin Li. "An efficient analytical method for computing the Boltzmann entropy of a landscape gradient." Transactions in GIS (2018).
 - Gao, Peichao, Hong Zhang, and Zhilin Li. "A hierarchy-based solution to calculate the configurational entropy of landscape gradients." Landscape Ecology 32(6) (2017): 1133-1146.
-
+- Gao, Peichao, Hong Zhang, and Zhilin Li. "An efficient analytical method for computing the Boltzmann entropy of a landscape gradient." Transactions in GIS (2018).
+- Gao, Peichao and Zhilin Li. "Aggregation-based method for computing absolute Boltzmann entropy of landscape gradient with full thermodynamic consistency." Landscape Ecology (2019).

README.md

@@ -14,9 +14,9 @@ downloads](http://cranlogs.r-pkg.org/badges/belg)](https://cran.r-project.org/pa
 
 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.
+(2017, 2018, 2019)). 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.
 
 ## Installation
 
@@ -36,48 +36,64 @@ devtools::install_github("r-spatialecology/belg")
 
 ## Examples
 
-As an example, we use two small rasters - `complex_land` representing a
-complex landscape and `simple_land` representing a simple landscape:
+As an example, we use two rasters - `land_gradient1` representing a
+complex landscape and `land_gradient2` representing a simple landscape:
 
 ``` r
 library(raster)
 library(belg)
-plot(stack(complex_land, simple_land))
+plot(stack(land_gradient1, land_gradient2))
 ```
 
 <img src="man/figures/README-unnamed-chunk-1-1.png" width="100%" />
 
-The main function in this package, `get_boltzmann`, calculates the
+The main function in this package, `get_boltzmann()`, calculates the
 Boltzmann entropy of a landscape gradient:
 
 ``` r
-get_boltzmann(complex_land)
-#> [1] 48.43241
-get_boltzmann(simple_land)
-#> [1] 18.3818
+get_boltzmann(land_gradient1)
+#> [1] 66785968
+get_boltzmann(land_gradient2)
+#> [1] 30134170
 ```
 
 This function accepts a `RasterLayer`, `RasterStack`, `RasterBrick`,
-`matrix`, or `array` object as an input. It also allows for calculation
-of the relative (the `relative` argument equal to `TRUE`) and absolute
+`matrix`, or `array` object as an input. It allows for calculation of
+the relative (the `relative` argument equal to `TRUE`) and absolute
 Boltzmann entropy of a landscape gradient. As a default, it uses a
 logarithm of base 10 (`log10`), however `log` and `log2` are also
 available options for the `base` argument.
 
 ``` r
-get_boltzmann(complex_land, base = "log")
-#> [1] 111.5198
-get_boltzmann(complex_land, relative = TRUE)
-#> [1] 35.50168
-get_boltzmann(complex_land, base = "log2", relative = TRUE)
-#> [1] 117.934
+get_boltzmann(land_gradient1, base = "log")
+#> [1] 153780374
+get_boltzmann(land_gradient1, relative = TRUE)
+#> [1] 548520.4
+get_boltzmann(land_gradient1, base = "log2", relative = TRUE)
+#> [1] 1822145
+```
+
+Two methods of calculating the Boltzmann entropy of a landscape gradient
+are available: `"hierarchy"` (default) for the hierarchy-based method
+(Gao et al., 2017) or `"aggregation"` for the aggregation-based method
+(Gao et al., 2019). The aggregation-based method requires that the
+number of rows and columns in the input data must be a multiple of 2.
+
+``` r
+get_boltzmann(land_gradient1, method = "aggregation")
+#> [1] 188772.5
+get_boltzmann(land_gradient1, relative = TRUE, method = "aggregation")
+#> [1] 137645.4
 ```
 
 ## References
 
-  - Gao, Peichao, Hong Zhang, and Zhilin Li. “An efficient analytical
-    method for computing the Boltzmann entropy of a landscape gradient.”
-    Transactions in GIS (2018).
   - Gao, Peichao, Hong Zhang, and Zhilin Li. “A hierarchy-based solution
     to calculate the configurational entropy of landscape gradients.”
     Landscape Ecology 32(6) (2017): 1133-1146.
+  - Gao, Peichao, Hong Zhang, and Zhilin Li. “An efficient analytical
+    method for computing the Boltzmann entropy of a landscape gradient.”
+    Transactions in GIS (2018).
+  - Gao, Peichao and Zhilin Li. “Aggregation-based method for computing
+    absolute Boltzmann entropy of landscape gradient with full
+    thermodynamic consistency.” Landscape Ecology (2019).