---
title: "LandComp"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{LandComp}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(LandComp)
```

`LandComp` is a package for quantifying landscape diversity and structure at
multiple scales. For these purposes Juhász-Nagy's functions, i.e. compositional 
diversity (CD) and associatum (AS), are calculated.

## Examples

Suggest we have data on some vegetation types along a landscape. Note, there are three requirements:

* the landscape data should be numeric binary, i.e. it should contain 0 or 1 values
* the geometry of the landscape data should be a regular square or hexagonal grid
* the geometry of the landscape data should have projected coordinates (i.e. WGS84 is not eligible)

### Using regular square grid

Have a look at the square grid data.

```{r square_data, echo = TRUE}
suppressPackageStartupMessages(library("sf"))
library(LandComp)
data("square_data")
str(square_data)
```

```{r square_data_plot, out.width = '100%', echo = FALSE}
knitr::include_graphics(path = "../man/figures/README-square_data-1.png")
```

_**Fig. 1.** Visualization of the square grid data._

CD and AS of the landscape at the scale of the base square grid (i.e. using the input grid cells as spatial units) can be calculated as

```{r square_example1, echo=TRUE}
LandComp(x = square_data, aggregation_steps = 0)
```

However, Juhász-Nagy's functions, i.e. compositional diversity (CD) and associatum (AS) should be calculated at multiple scales. For this purpose spatial units can be selected using a buffer of grid cells around the central grid cell, where 0 means the original cell without enlargement.

```{r square_units_plot, out.width = '50%', echo = FALSE}
knitr::include_graphics(path = "../man/figures/spatial_units_square.png")
```

_**Fig. 2.** Main properties of the spatial units used for the calculation of Juhász-Nagy's functions. In the integer aggregation steps, radially enlarged spatial units consisting of 9, 25, 49 etc. squares are produced. Enlarged spatial units of fraction aggregation steps are created using the spatial unit of the next integer aggregation step, but excluding the grid cells that touch the corners of the next integer unit. A~s~ is the area of the square grid cell of the input data._ 

The analysis can be done more precise by giving also fraction numbers as input. Thus, the following values of CD and AS can be calculated as e.g.

```{r square_example2, echo=TRUE}
LandComp(x = square_data, aggregation_steps = c(0.5, 1))
```

### Using regular hexagonal grid

The example dataset contains pointy-topped hexagons. Note, the methods are also fine for regular hexagonal grids containing flat-topped hexagons. 
Have a look at the hexagonal grid data.

```{r hexagonal_data, echo = TRUE}
data("hexagonal_data")
str(hexagonal_data)
```

```{r hexagonal_data_plot, out.width = '100%', echo = FALSE}
knitr::include_graphics(path = "../man/figures/README-hexagonal_data-1.png")
```

_**Fig. 3.** Visualization of the hexagonal grid data._

CD and AS of the landscape at the scale of the base hexagonal grid (i.e. using the input grid cells as spatial units) can be calculated as 

```{r hexagonal_example1, echo=TRUE}
LandComp(x = hexagonal_data, aggregation_steps = 0)
```

However, Juhász-Nagy's functions, i.e. compositional diversity (CD) and associatum (AS) should be calculated at multiple scales. For this purpose spatial units can be selected using a buffer of grid cells around the central grid cell, where 0 means the original cell without enlargement.

```{r hexagonal_units_plot, out.width = '50%', echo = FALSE}
knitr::include_graphics(path = "../man/figures/spatial_units_hexagon.png")
```

_**Fig. 4.** Main properties of the spatial units used for the calculation of Juhász-Nagy's functions. In the integer aggregation steps, radially enlarged spatial units consisting of 7, 19, 37 etc. hexagons are produced. Enlarged spatial units of fraction aggregation steps are created using the spatial unit of the next integer aggregation step, but excluding the grid cells that touch the vertices of the next integer unit. A~h~ is the area of the hexagonal grid cell of the input data._ 

Analysis can be done more precise by giving also fraction numbers as input. Thus, the following values of CD and AS can be calculated as e.g.

```{r hexagonal_example2, echo=TRUE}
LandComp(x = hexagonal_data, aggregation_steps = c(1, 1.5))
```

**Note,** in the case of hexagonal grid, steps falling in the interval ]0,1[ cannot be evaluated.