estar (version 1.0-1)

invariability: Calculate the invariability of a state variable after disturbance

Description

invariability returns the temporal invariability \(I\) of a system following disturbance. Invariability can be calculated using the post-disturbance values of the state variable in the disturbed system as the response, or the log-response ratio of the state variable in the disturbed system compared to the baseline. Two variants of invariability can be calculated: as the inverse of the coefficient of variation of the system's response, or the inverse of the standard deviation of residuals of the linear model that uses the time as the predictor of the system's response.

Usage

invariability(
  type,
  mode = NULL,
  response = NULL,
  metric_tf,
  vd_i = NULL,
  td_i = NULL,
  d_data = NULL,
  vb_i = NULL,
  tb_i = NULL,
  b_data = NULL,
  comm_b = NULL,
  comm_d = NULL,
  comm_t = NULL,
  method = "bray",
  binary = "FALSE",
  na_rm = TRUE
)

Value

A single numeric, the invariability ( \(I\) ) value. The larger in magnitude \(I\)

is, the higher the stability, since the variation around the trend is lower.

Arguments

type

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

mode

A string stating which variant of invariability should be calculated, the one based on the coefficient of variation of the state variable mode = "cv", or the one based on fitting the linear model "lm_res".

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 (response == "v").

metric_tf

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

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_b

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

comm_d

a data frame containing long format community data (species 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

Instability can be calculated as the coefficient fo variation of the system:

• For functional stability, the response is the log response ratio between the state variable’s value in the disturbed ( \(v_d\) ) and in the baseline systems ( \(v_b\) or \(v_p\) if the baseline is pre-disturbance values) or the state variable’s value in the disturbed system itself. Therefore, \(I = \mathrm{CV}\!\left( \log\!\left( \frac{v_d}{v_b} \right) \right)^{-1}\) , or \(I = \mathrm{CV}\!\left( \log\!\left( \frac{v_d}{v_p} \right) \right)^{-1}\) , or \(I = \mathrm{CV}(v_d)^{-1}\) .

• For compositional stability, the response is the dissimilarity between the disturbed ( \(C_d\) ) and baseline ( \(C_b\) ) communities: \(I = \mathrm{CV}\!\left(\mathrm{dissim}\!\left( \frac{C_d}{C_b} \right) \right)^{-1} \)

Alternatively, instability can be calculated as inverse of the standard deviation of residuals of the linear model where the response (same as above) is predicted by time, whereby: \(I = \sigma(\varepsilon)^{-1}\) , from \(y = \alpha + R_r\, t + \varepsilon\) , where \( y \in \left\{ \log\!\left(\frac{v_d}{v_b} \right), \log\!\left(\frac{v_d}{v_p} \right), v_d, \mathrm{dissim}\!\left( \frac{C_d}{C_b} \right) \right\} \) , \(\alpha\) is the intercept, and \(R_r\) is the recovery rate.

Examples

invariability(
  vd_i = "statvar_db", td_i = "time", response = "v", mode = "cv",
  metric_tf = c(11, 50), d_data = aquacomm_resps, type = "functional"
)
invariability(
  vd_i = aquacomm_resps$statvar_db, td_i = aquacomm_resps$time,
  response = "v", mode = "cv", metric_tf = c(11, 50), type = "functional"
)
invariability(
  vd_i = "statvar_db", td_i = "time", response = "lrr", mode = "lm_res",
  metric_tf = c(11, 50), d_data = aquacomm_resps, vb_i = "statvar_bl",
  tb_i = "time", b_data = aquacomm_resps, type = "functional"
)
invariability(
  vd_i = aquacomm_resps$statvar_db, td_i = aquacomm_resps$time,
  response = "lrr", type = "functional",
  metric_tf = c(11, 50), mode = "lm_res", vb_i = aquacomm_resps$statvar_bl,
  tb_i = aquacomm_resps$time
)
invariability(
  type = "compositional", metric_tf = c(0.14, 56), comm_d = comm_dist,
  comm_b = comm_base, comm_t = "time"
)