spectral_sews {spatialwarnings}

Spectrum-based spatial early-warning signals.

Description

Computation of spatial early warning signals based on spectral properties.

Usage

spectral_sews(mat, sdr_low_range = NULL, sdr_high_range = NULL, quiet = FALSE)

Arguments

mat

The input matrix or a list of matrices.

sdr_low_range

The range of values (in proportion) to use for the computation of the spectral density ratio. For example, for the lowest 20 c(0, .2). See also the Details section.

sdr_high_range

The range of values (in proportion) to use for the computation of the spectral density ratio. For example, for the higher 20 c(.8, 1). See also the Details section.

quiet

Do not display some warnings

Details

Spectral early warning signals are based on the fact that some dynamical systems can exhibit an change in some characteristics of their spatial structure when approaching a transition. In particular, long-range correlations are expected to have an increased importance.

This is expected to be reflected in the spectrum of the spatial structure by an increase of the relative importance of lower frequencies over higher frequencies ("reddening" of the spectrum).

This task allows computing the radial-spectrum which gives the relative importance of each space scale as a function of distance, from 1 to N/2 (N being the minimum between the number of rows and columns). If the matrix is not square, then it is cropped to biggest square that fits within the left side of the matrix.

Additionally, it summarizes this spectrum into a Spectral Density Ratio (SDR), which is the ratio of low frequencies over high frequencies of the r-spectrum. The SDR value is expected to increase before a transition point.

The significance of spectral early-warning signals can be estimated by reshuffling the original matrix (function indictest). Indicators are then recomputed on the shuffled matrices and the values obtained are used as a null distribution. P-values are obtained based on the rank of the observed value in the null distribution.

The trend of SDR values can be plotted using the plot() method. Alternatively, the spectrum itself can be plotted (with facets if multiple input matrices were used) using the plot_spectrum method.

Value

Function spectral_sews object of class spectral_sews_list or spectral_sews_single depending on whether the input was a list of matrices or a single matrix.

Function indictest

The plot methods returns a ggplot object (usually displayed immediately when called interactively).

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

rspectrum, plot_spectrum, raw_sdr, extract_spectrum

indictest, to test the significance of indicator values.

Examples

## Not run: 

data(serengeti) 
data(serengeti.rain) 


spec_indic <- spectral_sews(serengeti, 
                             sdr_low_range  = c(0, .2), 
                             sdr_high_range = c(.8, 1))

summary(spec_indic)

# Display trends along the varying model parameter
plot(spec_indic, along = serengeti.rain)

# Computing spectra many times is expensive, consider setting parallel 
# computing using: options(mc.cores = n)

# Assess significance
spec_test <- indictest(spec_indic, nulln = 199)
summary(spec_test)

# Display the SDR trend, now with a grey ribbon representing 5%-95% 
# quantiles of the null distribution
plot(spec_test, along = serengeti.rain)

# Add a line highlighting the shift 
if (require(ggplot2)) {
  plot(spec_test, along = serengeti.rain) + 
    geom_vline(xintercept = 590, color = "red", linetype = "dashed")
}


# Display radial-spectra
plot_spectrum(spec_indic, along = serengeti.rain)

# Graphics can be modified using ggplot2 functions
if (require(ggplot2)) { 
  plot_spectrum(spec_indic, along = serengeti.rain) + 
    scale_y_log10()
}


## End(Not run)