patchdistr_sews: Early-warning signals based on patch size distributions
In spatialwarnings: Spatial Early Warning Signals of Ecosystem Degradation

patchdistr_sews

R Documentation

Early-warning signals based on patch size distributions

Description

Compute early-warning signals based on patch size distributions

Usage

patchdistr_sews(
  mat,
  merge = FALSE,
  fit_lnorm = FALSE,
  best_by = "BIC",
  xmin = 1,
  xmin_bounds = NULL,
  wrap = FALSE,
  nbmask = "von_neumann"
)

Arguments

`mat`	A logical matrix (`TRUE`/`FALSE` values) or a list of these
`merge`	The default behavior is to produce indicators values for each matrix. If this parameter is set to TRUE then the patch size distributions are pooled together before fitting, yielding only one final indicator value for the set of input matrices (argument `mat`).
`fit_lnorm`	When patch size distributions are compared, should we consider lognormal type ? (see details)
`best_by`	The criterion to use to select the best fit (one of "AIC", "BIC" or "AICc")
`xmin`	The `x_{min}` to be used to fit the patch size distributions. Use the special value "estimate" to compute first the `x_{min}` that produces the best power-law fit, then use this estimated value to fit all distributions.
`xmin_bounds`	Bounds when estimating `x_{min}` for power-law distributions
`wrap`	Determines whether patches are considered to wrap around the matrix when reaching the side
`nbmask`	Either "moore" for 8-way neighborhood, "von_neumann" for four-way neighborhood (default), or a 3x3 matrix describing which neighbors to consider around a cell. See `patchsizes` for details on how to specify such neighborhoods.

Details

Patterned ecosystems can exhibit a change in their spatial structure as they become more and more stressed. It has been suggested that this should be reflected in changes in the observed patch size distributions (PSD). The following sequence is expected to occur (Kefi et al. 2011) as patterned ecosystems become more and more degraded:

- Percolation of vegetation patches occurs (a patch has a width or height equal to the size of the system)

- The patch-size distribution follows a power-law

- The patch-size distribution deviates from a power-law as larger patches break down

- The patch-size distribution is closer to an exponential distribution

Additionally, it has been suggested that these changes in patch size distribution shape should be reflected in the power-law range (PLR). This function carries out all the required computations and helps display the results in a convenient form.

The fitting of PSDs is based on maximum-likelihood following Clauset et al.'s procedure. The best discrete distribution is estimated among these candidates: a power-law x^\lambda, an exponential exp(\alpha x), a truncated power-law and x^\lambda exp(\alpha x), and optionally, a log-normal. Each distribution parameter is estimated using maximum-likelihood, with a minimum patch size (xmin) fixed to one. The best distribution is selected based on BIC by default. In raw results, plexpo refers to the power-law exponent (\lambda in the previous equations) and cutoff referes to the exponential decay rate \alpha.

To compute the Power-law range (PLR), power-laws are fitted with a variable minimum patch size (xmin) and the one with the lowest Kolmogorov-Smirnov distance to the empirical distribution is retained. PLR is then computed using this best-fitting xmin:

\frac{log(x_{max}) - log(x_{min})}{log(x_{max}) - log(x_{smallest})}

Results can be displayed using the text-based summary and print, but graphical options are also available to plot the trends (plot) and the fitted distributions (plot_distr). Plotting functions are documented in a separate page. Observed and fitted distributions can be produced using the predict function, as documented on this page.

Value

A list object of class 'psdfit' containing among other things - the observed patch size distribution data - the model outputs for the candidate distribution fits - the power-law range values - the percolation values (if several matrices were provided and 'merge' was TRUE, then the average percolation value is returned)

References

Kefi, S., Rietkerk, M., Alados, C. L., Pueyo, Y., Papanastasis, V. P., ElAich, A., & De Ruiter, P. C. (2007). Spatial vegetation patterns and imminent desertification in Mediterranean arid ecosystems. Nature, 449(7159), 213-217.

Kefi, S., Rietkerk, M., Roy, M., Franc, A., de Ruiter, P.C. & Pascual, M. (2011). Robust scaling in ecosystems and the meltdown of patch size distributions before extinction: Patch size distributions towards extinction. Ecology Letters, 14, 29-35.

Berdugo, M, Sonia Kefi, Santiago Soliveres, and Fernando T. Maestre. (2017) Plant Spatial Patterns Identify Alternative Ecosystem Multifunctionality States in Global Drylands. Nature in Ecology and Evolution, no. 1.

Clauset, A., Shalizi, C. R., & Newman, M. E. (2009). Power-law distributions in empirical data. SIAM review, 51(4), 661-703.

Examples


data(forestgap)


psd_indic <- patchdistr_sews(forestgap)

summary(psd_indic)
plot(psd_indic)

# Plots can be modified using ggplot2 directives 
if ( require(ggplot2) ) { 
  plot(psd_indic) + 
    theme_minimal()
}

# Export results to a data.frame
psd_indic_export <- as.data.frame(psd_indic) 
head(psd_indic_export)

spatialwarnings documentation built on Sept. 11, 2024, 8:55 p.m.