spatialwarnings (version 1.2)

create_indicator: Custom Spatial Early-Warning signals

Description

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

Usage

create_indicator(fun, fun.name = as.character(substitute(fun)))
custom_indicator(mat, fun, fun.name = as.character(substitute(fun)), ...)
# S3 method for custom_sews_list
plot(x, along = NULL, ...)
# S3 method for custom_sews
indictest(x, nperm = 999, ...)
# S3 method for custom_sews_test
plot(x, along = NULL, what = "value",
  display_null = TRUE, ...)

Arguments

fun

A function that takes a real-valued matrix as input and returns a single, numerical value.

fun.name

The indicator name. Optional, used for plots and textual summaries, but mandatory if fun is an anonymous function.

mat

A matrix or a list of matrices.

...

Ignored

x

A custom_sews 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.

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").

Value

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

Details

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_sews), spectrum-based indicators (spectral_sews) and indicators based on patch size distributions (patchdistr_sews).

create_indicator extends the package to any arbitrary function. It takes a function `fun` and returns another function that can be used as an indicator similar to the *_sews function family. The results of this function can be assessed for significance using indictest and trends can be displayed using plot, summary, etc. (see Examples). custom_indicator does the same but without creating an intermediate indicator function.

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`.

Examples

# NOT RUN {
# 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_sews <- create_indicator(maxpatchsize)

# Then work with this function as if it were a function from the *_sews 
# family. 
mp_indic <- maxpatch_sews(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)
# }
# 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_sews <- create_indicator(spatial_cv)

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

# We can do the same work in one run using custom_indicator
cv_indic2 <- custom_indicator(serengeti, spatial_cv, subsize = 3)
plot(cv_indic2, along = serengeti.rain)

# }
# NOT RUN {
indictest(cv_indic, nperm = 99)
# }