estar (version 1.0-1)

recovery_extent: Calculate the extent of recovery after disturbance

Description

recovery_extent ( \(R_e\) ) calculates how close a state variable is to its baseline value at a time point specified by the user (usually after recovery has taken place). For functional stability, the distance can be calculated as the log-response ratio or as the difference between the state variables in a disturbed time-series and the baseline. The baseline can be

• a value at time t_rec of the baseline time-series b_data (if b = "input").

• pre-disturbance values of the state variable in the disturbed system over a period defined by b_tf (if b = "d"). In that case, the state variable is summarized as the mean or median (summ_mode).

For community stability, the distance is calculated as the dissimilarity between the disturbed and baseline communities.

Usage

recovery_extent(
  type,
  response = NULL,
  t_rec,
  summ_mode = "mean",
  b = NULL,
  b_tf = NULL,
  vd_i = NULL,
  td_i = NULL,
  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",
  na_rm = TRUE
)

Value

A numeric, the extent of recovery. Maximum (functional and compositional) recovery at 0. For functional stability, smaller or higher values indicate under- or overcompensation, respectively. For compositional stability using the Bray-Curtis index (default), \(0 \le R_e \le 1\)

. The higher the index, the further apart the communities are after recovery, and thus, the lower the recovery is.

Arguments

type

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

response

a string stating whether the stability metric should be calculated using the log-response ratio between the values in the disturbed system and the baseline (response = "lrr") or using the state variable values in the disturbed system alone.

t_rec

An integer, time point at which the extent of recovery should be calculated.

summ_mode

A string, stating whether the baseline should be summarized as the mean (summ_mode = "mean") or the median (summ_mode = "median"). Defaults to "mean".

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".

na_rm

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

Details

For functional stability, the log-response ratio or difference between the state variable in the disturbed systems \(v_d\) and in the baseline ( \(v_b\) or \(v_p\) if the baseline is pre-disturbance values) measured on the user-defined time step when the recovery is assumed to have taken place. Therefore, \(R_e = \log\!\left(\frac{v_d(t)}{v_b(t)}\right)\) , or \(R_e = \log\!\left(\frac{v_d(t)}{v_p(t)}\right)\) , or \(R_e = \lvert v_d(t) - v_b(t) \rvert\) , or \(R_e = \lvert v_d(t) - v_p(t) \rvert\) .

For community stability, the dissimilarity between the disturbed ( \(C_d\) ) and baseline ( \(C_b\) ) communities \(R_e = \mathrm{dissim}\!\left(\frac{C_d(t)}{C_b(t)}\right)\) .

Even though it is possible to use a single data value as baseline, it is not recommended, because a single value does not account for any variability in the system arising from, for example, demographic or environmental stochasticity.

Examples

recovery_extent(
  vd_i = "statvar_db", td_i = "time", d_data = aquacomm_resps,
  response = "lrr", b = "input", t_rec = 42, vb_i = "statvar_bl",
  tb_i = "time", b_data = aquacomm_resps, type = "functional"
)
recovery_extent(
  vd_i = "statvar_db", td_i = "time", d_data = aquacomm_resps,
  response = "diff", b = "input", t_rec = 42, vb_i = "statvar_bl",
  tb_i = "time", b_data = aquacomm_resps, type = "functional"
)
recovery_extent(
  vd_i = "statvar_db", td_i = "time", d_data = aquacomm_resps,
  response = "lrr", b = "d", t_rec = 42, b_tf = 8, type = "functional"
)
recovery_extent(
  vd_i = "statvar_db", td_i = "time", d_data = aquacomm_resps,
  response = "lrr", b = "d", t_rec = 42, b_tf = c(5, 10), type = "functional"
)
recovery_extent(
  vd_i = "statvar_db", td_i = "time", d_data = aquacomm_resps,
  response = "lrr", type = "functional",
  b = "d", t_rec = 42, b_tf = c(5, 10), summ_mode = "median"
)
recovery_extent(
  type = "compositional", t_rec = 28, comm_d = comm_dist,
  comm_b = comm_base, comm_t = "time"
)