---
title: "Basic Usage of NLMR"
author: "Marco Sciaini & Craig E.Simpkins"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
bibliography: Citations.bib
vignette: >
  %\VignetteIndexEntry{Basic Usage of NLMR}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r global_options, include=FALSE}
library(raster)
library(NLMR)
```

`NLMR` is a `R` package designed to generate neutral landscape models (NLMs), 
simulated landscapes used to explore landscape scale ecological patterns and 
processes. The `NLMR` package was designed with a similar philosophy to the 
Python package `NLMpy` [see @Etheringtonnlmr2015], offering a general numeric 
framework allowing for a high degree of flexibility. Most of the common NLMs, 
as described by the relevant literature, can be produced using NLMR. 
Additionally, NLMR allows users to merge multiple landscapes, classify landscape
elements categorically and measure basic landscape level metrics. All NLMs 
produced take the form of two-dimensional raster arrays with specified row and 
column dimensions and cell values ranging between 0 and 1. By returning raster 
arrays, NLMs are easily integrated into the workflow of many useful spatial
analysis packages, notably the `raster` package.

For further information on neutral landscape models, the authors goals for
this package, and additional use case examples please see the associated
publication Sciani, Fritsch, Scherer and Simpkins [-@Sciani2018]

## Basic landscape generation

`NLMR` supplies 16 NLM algorithms. The algorithms differ from each other in 
spatial auto-correlation, from no auto-correlation (random NLM) to a constant 
gradient (planar gradients) [see @Palmer1992].  

The 16 NLM algorithms are:

1. distance gradient
1. edge gradient  
1. hierarchical curdling
1. wheyed hierarchical curdling
1. midpoint displacement 
1. neighbourhood clustering
1. planar gradient  
1. random  
1. random cluster nearest-neighbour 
1. random element 
1. random mosaic fields
1. random polygonal landscapes
1. random percolation  
1. random rectangular cluster 
1. spatially correlated random fields (Gaussian random fields)  
1. two-dimensional fractional Brownian motion

The basic syntax used to produce a NLM landscape is:
```
nlm_modeltype(ncol, nrow, resolution, ...)
```
    
For example, to produce a simple random neutral landscape one could use the 
following code:

```{r, fig.height=7, fig.width=7, fig.align='center'}
x <- NLMR::nlm_random(20,20)
plot(x)
```

## Merging landscapes

Multiple NLM rasters can be merged or merged together to create new landscape 
patterns. A single primary or base raster can be merged with any number of 
additional secondary rasters, with optional scaling factors used to control the 
influence of the secondary rasters.  

The `util_merge` function is used to merge the rasters as in the example below:

```{r, fig.height=7, fig.width=7, fig.align='center'}
  #Create primary landscape raster
  pL <- NLMR::nlm_edgegradient(ncol = 100,
                               nrow = 100)

  plot(pL)

  #Create secondary landscape rasters
  sL1 <- NLMR::nlm_distancegradient(ncol = 100,
                                    nrow = 100,
                                    origin = c(10, 10, 10, 10))
  sL2 <- NLMR::nlm_random(ncol = 100,
                          nrow = 100)

  mL1 <- pL + (sL1 + sL2)
  
  plot(mL1)
```

## Classifying categories

Landscape rasters generated by `NLMR` contain continuous values between 0 and 1,
though these can be converted into categorical values using `util_classify` from 
**landscapetools**. By default classes are numerical starting from 1. 
If non-numerical levels are required, `level_names` can be 
specified. These classes can be plotted by selecting `discrete = TRUE` in 
`show_landscape`.

```{r fig.height=7, fig.width=7, fig.align='center'}
nr <- NLMR::nlm_fbm(50, 100, fract_dim = 1.2)
                              
nr_classified <- landscapetools::util_classify(nr, weighting = c(0.3, 0.3, 0.3))

plot(nr_classified)
```

## References