create_indicator: Custom Spatial Early-Warning signals
In spatialwarnings: Spatial Early Warning Signals of Ecosystem Degradation

Description Usage Arguments Details Value Examples

Computation, significance assessment and display of trends of a custom, user-defined indicator.

create_indicator(fun)

## S3 method for class 'custom_spews_list'
plot(x, along = NULL, ...)

## S3 method for class 'custom_spews'
indictest(x, nperm = 999, ...)

## S3 method for class 'custom_spews_test'
plot(x, along = NULL, what = "value",
  display_null = TRUE, ...)

`fun`	A function that takes a real-valued matrix as input and returns a single, numerical value.
`x`	A `custom_spews` object (as provided by the custom indicator function created by `create_indicator`).
`along`	A vector providing values over which the indicator trend will be plotted. If `NULL` then the values are plotted sequentially in their original order.
`...`	Ignored
`nperm`	The number of replicates to use to compute use in the null distribution
`what`	The trendline to be displayed. Defaults to the indicator's values ("value") but other metrics can be displayed. Correct values are "value", "pval" or "z_score".
`display_null`	Chooses whether a grey ribbon should be added to reflect the null distribution. Note that it can not be displayed when the trend line reflects something else than the indicator values (when `what` is not set to "value").

Spatial Early-warning signals (EWS) are metrics that are based on the spatial structure of a system and measure the degradation of an ecological system. The package spatialwarnings provides generic indicators (generic_spews), spectrum-based indicators (spectral_spews) and indicators based on patch size distributions (patchdistr_spews).

create_indicator can extend the package to any indicator function. It takes a function 'fun' and returns another function that can be used as an indicator function similar to the *_spews functions. The results of this function can be assessed for significance using the generic function indictest and trends can be displayed using plot, summary, etc. (see Examples).

fun should be a function that takes as input a matrix and possibly more arguments, and return a single numeric value. Note that the matrix is converted internally to numeric values, as a side effect of using c++ code when assessing significance. When working with logical matrices (e.g. when computing patch size distributions), the matrix has to be explicitely converted to logical within function 'fun'.

create_indicator returns a function that can be used in the same way than the other *_spews functions (e.g. generic_spews)

# Use the maximum patch size as indicator of degradation
maxpatchsize <- function(mat) { 
  # Note that we explicitely convert mat here to logical as it can be 
  # transformed into numeric internally. 
  max(patchsizes(mat > 0))
}

# Create the indicator function
maxpatch_spews <- create_indicator(maxpatchsize)

# Then work with this function as if it were a function from the *_spews 
# family. 
mp_indic <- maxpatch_spews(forestgap)
summary(mp_indic)

## Not run:  
# Assess significance and display trends
options(mc.cores = 2)
mp_test <- indictest(mp_indic, nperm = 49)
plot(mp_test)

## End(Not run)



# Try spatial coefficient of variation as a spatial EWS. This function can 
# have arguments. 
spatial_cv <- function(mat, subsize) { 
  matc <- coarse_grain(mat, subsize)
  return( sd(matc) / mean(matc) )
}

# Create indicator function
cv_spews <- create_indicator(spatial_cv)

# Compute and display trends
cv_indic <- cv_spews(serengeti, subsize = 3)
plot(cv_indic, along = serengeti.rain)

## Not run:  
indictest(cv_indic, nperm = 99)

## End(Not run)