indictest: Significance-assessment of spatial early-warning signals

In spatialwarnings: Spatial Early Warning Signals of Ecosystem Degradation

Significance-assessment of spatial early-warning signals

Description

Assess the significance of spatial early-warning indicators

Usage

indictest(x, nulln = 999, null_method = "perm", null_control = NULL, ...)

Arguments

x	An object such as one produced by the *_sews functions, or compute_indicator
nulln	The number of values to produce the null distribution
null_method	The method used to produce the null values (see Details)
null_control	List of arguments used to control the generation of null matrices. If NULL, then sensible defaults are chosen (see Details)
...	Additional arguments are ignored

Details

indictest is used to test the significance of early-warning signals against 'null matrices', which represent the expected spatial structure in the absence of the biological process of interest.

For a given indicator, a null distribution is obtained by producing a set of 'null' matrices, from which indicator values are recomputed. This produces a null distribution of nulln indicator values against which the observed value is tested.

Several methods are available to produce the set of null matrices. If null_method is set to "perm", the original matrix is reshuffled to obtain a null matrix. If null_method is set to "intercept", then a generalized linear model of the form 'y ~ 1' (where y represents the values of the matrix) is fitted, then values are drawn from this model. If null_method is set to "smooth", then a smooth surface is fitted based on a generalized additive model (using gam) to the matrix, then values are drawn from this model. When using the "intercept" or "smooth" null models, it is important to make sure the model 'family' corresponds to the type of values present in the matrix. By default, if a matrix contains TRUE/FALSE values, a 'binomial()' family is used, otherwise a 'gaussian()' family is used. More information about null models is available in the spatialwarnings FAQ.

Please note that specific null methods may exists for some indicators, such as flowlength. These are often based on analytical approximation and allow faster computations.

If a matrix has attributes, then these are preserved and passed to the function used to compute the indicator value, except when using the null method 'perm', in which case matrix attributes are discarded.

The list null_control can be used to adjust the computation of null matrices. It can have the following components:

family

The family used in the model used to produce the null matrices. Typically, it is one of binomial(), gaussian(), etc.

qinf

The lower quantile to compute from the null distribution and display in summaries/plots. A numeric value between 0 and 1.

qsup

The upper quantile to compute from the null distribution and display in summaries/plots. A numeric value between 0 and 1.

Value

An object with a class ending in *_sews_test, whose exact class depends on the input object. plot, summary methods are available to display the results of computations, and additional methods may be available depending on the input object (e.g. see patchdistr_sews_plot).

References

Kefi, S., Guttal, V., Brock, W.A., Carpenter, S.R., Ellison, A.M., Livina, V.N., et al. (2014). Early Warning Signals of Ecological Transitions: Methods for Spatial Patterns. PLoS ONE, 9, e92097

See Also

generic_sews, spectral_sews, kbdm_sews, compute_indicator, flowlength_sews

spatialwarnings documentation built on Aug. 18, 2025, 5:23 p.m.