Calculates selected spatial signatures based on categorical raster data. It also allows for calculations for any defined regular and irregular areas. It has several built-in signatures but also allows for any user-defined functions.

lsp_signature(
  x,
  type,
  window = NULL,
  neighbourhood = 4,
  threshold = 0.9,
  ordered = FALSE,
  repeated = FALSE,
  normalization = "pdf",
  wecoma_fun = "mean",
  wecoma_na_action = "replace",
  classes = NULL
)

Arguments

x

Object of class stars, stars_proxy, or terra's SpatRaster. It should have one attribute (for "coma", "cove"), two attributes ("cocoma", "cocove", "wecoma", "wecove"), two or more attributes ("incoma", "incove"), or any number of attributes suitable for user-defined functions.

type

Type of the calculated signature. It can be "coma" (co-occurrence matrix), "cove" (co-occurrence vector), "cocoma" (co-located co-occurrence matrix), "cocove" (co-located co-occurrence vector), "wecoma" (weighted co-occurrence matrix), "wecove" (weighted co-occurrence vector), "incoma" (integrated co-occurrence matrix), "incove" (integrated co-occurrence vector), "composition" or any function that can summarize stars objects.

window

Specifies areas for analysis. It can be either: NULL, a numeric value, or an sf object. If window=NULL calculations are performed for a whole area. If the window argument is numeric, it is a length of the side of a square-shaped block of cells. Expressed in the numbers of cells, it defines the extent of a local pattern. If an sf object is provided, each feature (row) defines the extent of a local pattern. The sf object should have one attribute (otherwise, the first attribute is used as an id).

neighbourhood

The number of directions in which cell adjacencies are considered as neighbours: 4 (rook's case) or 8 (queen's case). The default is 4.

threshold

The share of NA cells (0-1) to allow metrics calculation.

ordered

For "cove", "cocove", "wecove" and "incove" only. The type of pairs considered. Either "ordered" (TRUE) or "unordered" (FALSE). The default is FALSE.

repeated

For "incove" only. Should the repeated co-located co-occurrence matrices be used? Either "ordered" (TRUE) or "unordered" (FALSE). The default is FALSE.

normalization

For "cove", "cocove", "wecove", "incove", "composition", or user-provided functions only. Should the output vector be normalized? Either "none" or "pdf". The "pdf" option normalizes a vector to sum to one. The default is "pdf".

wecoma_fun

For "wecoma" and "wecove" only. Function to calculate values from adjacent cells to contribute to exposure matrix, "mean" - calculate average values of local population densities from adjacent cells, "geometric_mean" - calculate geometric mean values of local population densities from adjacent cells, or "focal" assign a value from the focal cell

wecoma_na_action

For "wecoma" and "wecove" only. Decides on how to behave in the presence of missing values in w. Possible options are "replace", "omit", "keep". The default, "replace", replaces missing values with 0, "omit" does not use cells with missing values, and "keep" keeps missing values.

classes

Which classes (categories) should be analyzed? This parameter expects a list of the same length as the number of attributes in x, where each element of the list contains integer vector. The default is NULL, which means that the classes are calculated directly from the input data and all of them are used in the calculations.

Value

Object of class lsp. It has three columns: (1) id - an id of each window. For irregular windows, it is the values provided in the window argument, (2) na_prop - share (0-1) of NA cells for each window, (3) signature - a list-column containing calculated signatures

Examples

library(stars)

landcover = read_stars(system.file("raster/landcover2015s.tif", package = "motif"))

landcover_coma = lsp_signature(landcover, type = "coma", threshold = 0.9, window = 2000)
landcover_coma
#> # A tibble: 1 × 3
#>      id na_prop signature    
#> * <int>   <dbl> <list>       
#> 1     1   0.895 <int [7 × 7]>

landcover_comp = lsp_signature(landcover, type = "composition", threshold = 0.9)
landcover_comp
#> # A tibble: 1 × 3
#>      id na_prop signature    
#> * <int>   <dbl> <list>       
#> 1     1  0.0555 <dbl [1 × 7]>

# \donttest{
# larger data example
library(stars)

landcover = read_stars(system.file("raster/landcover2015.tif", package = "motif"))

landcover_coma = lsp_signature(landcover, type = "coma", threshold = 0.9, window = 2000)
landcover_coma
#> # A tibble: 6 × 3
#>      id na_prop signature    
#> * <int>   <dbl> <list>       
#> 1     1   0.659 <int [7 × 7]>
#> 2     2   0.374 <int [7 × 7]>
#> 3     3   0.705 <int [7 × 7]>
#> 4     6   0.671 <int [7 × 7]>
#> 5     7   0.509 <int [7 × 7]>
#> 6     8   0.804 <int [7 × 7]>

landcover_comp = lsp_signature(landcover, type = "composition", threshold = 0.9)
landcover_comp
#> # A tibble: 1 × 3
#>      id na_prop signature    
#> * <int>   <dbl> <list>       
#> 1     1   0.666 <dbl [1 × 7]>
# }