estar (version 1.0-1)

persistence: Calculate the persistence of a state variable over a defined time interval

Description

persistence ( \(P\) ) returns the proportion of time the state variable remained inside the interval defined by one baseline's \(\pm\) sd from the baseline's mean (functional stability) or the user-defined upper and lower limits of the community dissimilarity (compositional stability). The proportion is calculated in relation to the time period (metric_tf) defined by the user.

Usage

persistence(
  type,
  metric_tf,
  b,
  b_tf = NULL,
  vd_i,
  td_i,
  d_data = NULL,
  vb_i = NULL,
  tb_i = NULL,
  b_data = NULL,
  comm_d = NULL,
  comm_b = NULL,
  comm_t = NULL,
  method = "bray",
  binary = "FALSE",
  low_lim = NULL,
  high_lim = NULL,
  na_rm = TRUE
)

Value

A single numeric value, the persistence, \(0 \le P \le 1\)

. The higher persistence is, the more stable the system.

Arguments

type

a string defining the type of stability ("functional" or "compositional") to be calculated.

metric_tf

a numerical vector, specifying the beginning and end of the time period over which the stability metric should be measured.

b

a string stating whether the baseline is defined by a separate baseline that is specified by the user (b = "input") or by a period of the disturbed system (b = "d") prior to the disturbance. This period is specified by b_tf.

b_tf

a numerical vector, specifying the beginning and end of the pre-disturbance time period for the disturbed time-series that defines the baseline. Obligatory if (b = "d"), see 'Details'.

vd_i

a numeric vector containing the state variable in the disturbed system or a string specifying the name of the column containing said variable in the dataframe provided in d_data.

td_i

a numeric vector containing the time or a string specifying the name of the column containing the time in the dataframe provided in d_data.

d_data

an optional data frame containing the time series of the state variable values in a disturbed system.

vb_i

an optional numeric vector containing the state variable in the baseline, or a string for the name of the column in b_data containing said variable in the dataframe with baseline values.

tb_i

an optional numeric vector containing the time period over which the baseline was measured, or a string for the name of the column in b_data containing said the time variable in the dataframe with baseline values.

b_data

an optional data frame containing the time series of the state variable values in the baseline.

comm_d

a data frame containing long format community data (species as columns over time as rows) to calculate compositional metrics.

comm_b

a data frame containing long format community data (species names as columns over time as rows) to calculate compositional metrics.

comm_t

the name of the time variable in comm_b and comm_d.

method

a string identifying the dissimilarity index to be used to calculate dissimilarity. For more options, see ?vegdist. Defaults to "bray".

binary

a boolean stating whether presence/absence standardization should be performed before calculating the dissimilarity. For more options, see ?vegdist. Defaults to "bray".

low_lim

minimal dissimilarity value the user expects for a persistent community

high_lim

maximal dissimilarity value the user expects for a persistent community

na_rm

a logical determining whether NAs should be taken out prior to the estimation of the stability metric. Defaults to TRUE.

Details

$$ P = \frac{t_P}{t_a} $$

where \(t_a\) is the total time frame defined by the user (metric_tf) and \(t_P\) is the time period during which the response remain inside the limits defined by the user.

If the baseline is defined by the pre-disturbed values of the state variable in the disturbed system (b = "d"), this pre-disturbed time period used as baseline (b_tf) cannot overlap with the time period for which the persistence is to be calculated (metric_tf), because of redundancy: the values over b_tf define the interval for which the values in metric_tf are checked. If they are the same (or partly, if overlap is partial), the returned value of persistence will be falsely higher.

Examples

persistence(
  type = "functional", vd_i = "statvar_db", td_i = "time", d_data = aquacomm_resps, b = "d",
  b_tf = c(1, 9), metric_tf = c(28, 56)
)
persistence(
  type = "functional", vd_i = "statvar_db", td_i = "time", d_data = aquacomm_resps, b = "d",
  b_tf = c(1, 9), metric_tf = c(28, 56)
)
persistence(
  type = "functional", vd_i = "statvar_db", td_i = "time", d_data = aquacomm_resps, b = "input",
  metric_tf = c(28, 56), vb_i = "statvar_bl", tb_i = "time",
  b_data = aquacomm_resps
)
persistence(
  type = "functional", vd_i = "statvar_db", td_i = "time", d_data = aquacomm_resps, b = "input",
  metric_tf = c(28, 56), vb_i = "statvar_bl", tb_i = "time",
  b_data = aquacomm_resps
)
persistence(
  type = "compositional", b = "input",metric_tf = c(28, 56), comm_d = comm_dist,
  comm_b = comm_base, comm_t = "time", low_lim = 0.5, high_lim = 0.9
)