Title: Partitioning the Drivers of Stability of Ecological Communities
Version: 0.0.3
Description: Contains the basic functions to apply the unified framework for partitioning the drivers of stability of ecological communities. Segrestin et al. (2024) <doi:10.1111/geb.13828>.
License: GPL-3
URL: https://github.com/jsegrestin/comstab
BugReports: https://github.com/jsegrestin/comstab/issues
Imports: graphics, stats, Ternary
Encoding: UTF-8
RoxygenNote: 7.3.1
NeedsCompilation: no
Packaged: 2024-04-26 12:34:39 UTC; jsegrestin
Author: Jules Segrestin ORCID iD [aut, cre, cph]
Maintainer: Jules Segrestin <jsegrestin@gmail.com>
Repository: CRAN
Date/Publication: 2024-04-26 12:50:10 UTC

Simulating time series for ecological communities

Description

comTS() is a function used to simulate community Time Series based on custom parameters.

Usage

comTS(nsp, ny, even, mvs, sync = c("-2", "-1", "0", "1", "2"))

Arguments

nsp

Number of species in the community (integer).

ny

Length of the time series in years (integer > 5).

even

Parameter of the geometric rank-abundance curve ranging between 0 and 1 (numeric) .

mvs

Scaling coefficient of the mean-variance relationship ranging between 1 and 2 (numeric).

sync

Level of synchrony between species (factor):

  • "0": independant fluctuations.

  • "1": positive synchrony.

  • "2": high positive synchrony.

  • "-1": anti-synchronous fluctuations.

  • "-2": high anti-synchronous fluctuations.

Details

The simulation produces temporal series of abundances of 'nsp' species for 'ny' years. The mean abundance of each species is determined by a geometric series of 'nsp' values using a constant 'even' ratio between successive terms. Hence, a high 'even' value means a community with even species abundances while a low 'even' means a strongly dominated community. Species temporal variances are calculated following Taylor’s power law, using with a 'mvs' scaling coefficient. Finally, for each species, the 'ny' abundance values are sampled from a normal distribution with the corresponding species parameters, and bounded to positive values. Since each species is simulated independently of others, the resulting simulation can be used to describe a community where the 'nsp' species fluctuate independently ('sync' = "0"). To simulate an overall positive synchrony ('sync' = "1"), the temporal sequences of each species are sorted to maximize the number of years with all species having values above or below their respective median (one random selection among many possible combinations). A stabilizing negative synchrony ('sync' = "-1") is simulated by sorting the temporal sequences of each species to maximize the number of years where successively abundant species have values above and below their respective median (one random selection among many possible combinations). High positive synchrony ('sync' = "2") and high negative synchrony ('sync' = "-2") are generated using a similar approach but sorting values based on four quartiles instead of using the median only.

The simulation uses a simplistic approach where species fluctuations are not related to any underlying environmental factor nor demographic parameters. Consequently, the temporal order of the simulated abundances for each species cannot be considered realistic. Nevertheless, this simplification has little influence on the analyses performed in this R package since none of the indices calculated depend on the temporal order of individual series, but rather describe the overall variability and temporal coordination of species.

Value

A matrix of 'ny' rows and 'nsp' columns, containing numerical values of species abundances. The parameters used to compute species values (even, mvs, and sync) are stored as attributes of the matrix.

Author(s)

Jules Segrestin, jsegrestin@gmail.com

Examples

require(stats)

comTS(nsp = 10, ny = 30, even = 0.6, mvs = 1.5, sync = "0")

Partitioning of the temporal CV of ecological communities

Description

PartitionR() is a function used to partition the temporal coefficient of variation of a community into the variability of the average species and three stabilizing effects: the dominance, asynchrony and averaging effects (see Details).

Usage

partitionR(z, ny = 1)

Arguments

z

A matrix containing repeated measurements of species abundances. The matrix must contain numerical values only, with years in rows and species in columns. Remove any extra column.

ny

Only species appearing more than ny years (integer, defaults to 1) are used in the calculations.

Details

The analytic framework is described in details in Segrestin et al. (2024). In short, the partitioning relies on the following equation:

CV_{com} = CV_e \Delta \Psi \omega

where CV_{com} is the community coefficient of variation (reciprocal of community stability), CV_e is the expected community CV when controlling for the dominance structure and species temporal synchrony, \Delta is the dominance effect, \Psi is the asynchrony effect, and \omega is the averaging effect.

Value

Returns an object of class 'comstab'.

An object of class 'comstab' is a list containing the following components:

Author(s)

Jules Segrestin, jsegrestin@gmail.com

References

Segrestin et al. (2024) A unified framework for partitioning the drivers of stability of ecological communities. Global Ecology and Biogeography, 33(5), e13828. https://doi.org/10.1111/geb.13828

Examples

require(stats)

# Simulates a custom community time series using 'comTS()':
z <- comTS(nsp = 10, ny = 30, even = 0.6, mvs = 1.5, sync = "0")

# Runs the partitioning of the community coefficient of variation:
partitionR(z)

Plotting a comstab object

Description

Plotting method for object inheriting from class "comstab".

Usage

## S3 method for class 'comstab'
plot(x, ..., xlab = "", ylab = "Log scale", cex.comp = 1)

Arguments

x

object of class 'comstab'.

...

other parameters to be passed through to plotting functions.

xlab

a label for the x axis, removed by defaults.

ylab

a label for the y axis, defaults to 'Log scale'.

cex.comp

A numerical value giving the label size of stabilizing components. This is an absolute measure, not scaled by par("cex").

Value

No return value, graphical function.

Author(s)

Jules Segrestin, jsegrestin@gmail.com

Examples

require(graphics)

# Simulates a custom community time series using 'comTS()':
z <- comTS(nsp = 10, ny = 30, even = 0.6, mvs = 1.5, sync = "0")

# Runs the partitioning of the community coefficient of variation:
x <- partitionR(z)

# Plots the result
plot(x)

Plotting the relative contribution of stabilizing effects

Description

ternStab() is a graph function used to represent the relative contributions of the three stabilizing effects ("Dominance", "Asynchrony" and "Averaging") on a ternary plot.

Usage

ternStab(x, ..., point = TRUE, add = FALSE)

Arguments

x

object of class 'comstab'.

...

other parameters to be passed through to plotting functions.

point

plot the community on the ternary plot (logical, defaults to TRUE)

add

add the community on the current plot window (logical, defaults to FALSE)

Value

No return value, graphical function.

Author(s)

Jules Segrestin, jsegrestin@gmail.com

Examples

require(Ternary)

# Simulates a custom community time series using 'comTS()':
z <- comTS(nsp = 10, ny = 30, even = 0.6, mvs = 1.5, sync = "0")

# Runs the partitioning of the community coefficient of variation:
x <- partitionR(z)

# Plots the relative contributions
oldpar <- par(no.readonly = TRUE)
par(mar = c(0, 0, 0, 0))
ternStab(x)

# Adds a second community on the ternary plot
z2 <- comTS(nsp = 15, ny = 30, even = .7, mvs = 1.1, sync = "1")
x2 <- partitionR(z2)
ternStab(x2, add = TRUE, col = "red")

par(oldpar)