Main functions
Examples of each function applied to the example dataset. For the functions that require a user-defined time step when were the system has recovered, we use week 28, when all groups seem to have stabilized their growth curve (Fig.1).
Functional stability
Invariability
Invariability calculated as the inverse of standard deviation of
residuals of the linear model that predicts the log response ratio of
the state variable in the disturbed and baseline systems by time. The
baseline system in our example dataset is reflected by control ditches,
to which no pesticide was applied. The time frame is defined by
tb_i and specified in the data frame d_data
(aquacomm_resps, Fig. 2-a).
invariability(
type = "functional",
mode = "lm_res",
response = "lrr",
metric_tf = c(1, max(aquacomm_resps$time)),
vd_i = "statvar_db",
td_i = "time",
d_data = aquacomm_resps,
vb_i = "statvar_bl",
tb_i = "time",
b_data = aquacomm_resps
)
#> [1] 1.862129Invariability calculated as the inverse of standard deviation of residuals of the linear model fitted to predict the state variable in the disturbed system by time (Fig. 2-b).
invariability(
type = "functional",
mode = "lm_res",
metric_tf = c(1, max(aquacomm_resps$time)),
response = "v",
vd_i = "statvar_db",
td_i = "time",
d_data = aquacomm_resps,
vb_i = "statvar_bl",
tb_i = "time",
b_data = aquacomm_resps
)
#> [1] 0.003769501Invariability calculated as the inverse of the coefficient of variation of the log response ratio of the state variable in the disturbed and baseline systems (Fig. 2-c).
invariability(
type = "functional",
response = "lrr",
mode = "cv",
metric_tf = c(1, max(aquacomm_resps$time)),
vd_i = "statvar_db",
td_i = "time",
b_data = aquacomm_resps,
vb_i = "statvar_bl",
tb_i = "time",
d_data = aquacomm_resps
)
#> [1] 0.03962186Invariability calculated as the inverse of the coefficient of variation of a state variable in the disturbed system (Fig. 2-d).
invariability(
type = "functional",
response = "v",
mode = "cv",
metric_tf = c(1, max(aquacomm_resps$time)),
vd_i = "statvar_db",
td_i = "time",
d_data = aquacomm_resps,
vb_i = "statvar_bl",
tb_i = "time",
b_data = aquacomm_resps
)
#> [1] 1.083218Figure 2: Schematic representation of the possible metrics of invariability available in the estar package. ‘lrr’ refers to the log response ratio of the state variable in the disturbed system compared to the baseline time-series, and ‘v’ to ‘state variable’ in the disturbed system. a) and b) demonstrate calculation of invariability based on the standard deviation of the residuals of the fitted linear model, whereby the linear model fit is shown by a blue solid line. c) and d) demonstrate calculation of invariability based on the coefficient of variation
Resistance
Resistance calculated in relation to a baseline time series
(b = "input"), as the log response ratio
(res_mode = "lrr") of the state variable in the disturbed
and baseline systems at the first time step following disturbance
(res_time = "defined", res_t = 1, Fig.
3-a).
resistance(
type = "functional",
b = "input",
res_mode = "lrr",
res_time = "defined",
res_t = 1,
vd_i = "statvar_db",
td_i = "time",
d_data = aquacomm_resps,
vb_i = "statvar_bl",
tb_i = "time",
b_data = aquacomm_resps
)
#> [1] -0.3432519Resistance calculated in relation to a baseline time series
(b = "input"), as the highest
(res_time = "max") log response ratio
(res_mode = "lrr") of the state variable in the disturbed
and baseline systems during a given time frame
(res_tf = c(1, 20), Fig. 3-b).
resistance(
type = "functional",
b = "input",
res_mode = "lrr",
res_time = "max",
res_tf = c(1, 20),
vd_i = "statvar_db",
td_i = "time",
d_data = aquacomm_resps,
vb_i = "statvar_bl",
tb_i = "time",
b_data = aquacomm_resps
)
#> [1] 0.5301988Resistance calculated in relation to a baseline time series
(b = "input"), as the difference
(res_mode = "diff") at the first time step following
disturbance (res_time = "defined", res_t = 1,
Fig. 3-c).
resistance(
type = "functional",
b = "input",
res_mode = "diff",
res_time = "defined",
res_t = 1,
vd_i = "statvar_db",
td_i = "time",
d_data = aquacomm_resps,
vb_i = "statvar_bl",
tb_i = "time",
b_data = aquacomm_resps
)
#> [1] -43Resistance calculated in relation to a baseline time series
(b = "input"), as the highest
(res_time = "max") absolute difference
(res_mode = "diff") during a given time frame
(res_tf = c(11, 50), Fig. 3-d).
resistance(
type = "functional",
b = "input",
res_mode = "diff",
res_time = "max",
res_tf = c(1, 20),
vd_i = "statvar_db",
td_i = "time",
d_data = aquacomm_resps,
vb_i = "statvar_bl",
tb_i = "time",
b_data = aquacomm_resps
)
#> [1] 154.75Resistance calculated in relation to a pre-disturbance baseline
(b = "d"), composed of the state variable values in the
three time steps before disturbance (b_tf = c(-4, -0.14)),
as the highest (res_time = "max") absolute difference
(res_mode = "diff") during a given time frame
(res_tf = c(11, 50), Fig. 3-d).
resistance(
type = "functional",
b = "d",
b_tf = c(-4, 0.14),
res_time = "max",
res_mode = "diff",
res_tf = c(1, 20),
vd_i = "statvar_bl",
td_i = "time",
d_data = aquacomm_resps
)
#> [1] 423.8333Resistance calculated in relation to a pre-disturbance baseline
(b = "d"), composed of the state variable values in the
three time steps before disturbance (b_tf = c(-4, -0.14)),
as the highest (res_time = "defined") absolute log-ratio
(res_mode = "lrr") at a precise time step
(res_t = 1), Fig. 3-d).
resistance(
type = "functional",
b = "d",
b_tf = c(-4, 0.14),
res_mode = "lrr",
res_time = "defined",
res_t = 1,
vd_i = "statvar_db",
td_i = "time",
d_data = aquacomm_resps
)
#> [1] -0.5681957Figure 3: Schematic representation of the possible metrics of resistance available in the estar package. ‘lrr’ and ‘diff’ refer, respectively, to the log response ratio and to the difference between the state variable in the disturbed system in relation to the baseline value(s), ‘v’ to ‘state variable’, ‘td+1’, to the first time step after disturbance, and ‘tlow’, to the time step of the highest response in relation to the baseline.
Extent of recovery
Extent of recovery calculated as the log response ratio
(response = "lrr") of the state variable in the disturbed
and baseline systems (b = "input"), at a user-defined time
step (t_rec = 28, Fig. 4-a).
recovery_extent(
type = "functional",
response = "lrr",
b = "input",
t_rec = 28,
vd_i = "statvar_db",
td_i = "time",
d_data = aquacomm_resps,
vb_i = "statvar_bl",
tb_i = "time",
b_data = aquacomm_resps
)
#> [1] 1.166994Extent of recovery calculated as the difference
(response = "lrr") between the state variables in a
disturbed time-series and the baseline (b = "input"), at
the predefined time step (t_rec = 28, Fig. 4-b).
recovery_extent(
type = "functional",
response = "diff",
b = "input",
t_rec = 28,
vd_i = "statvar_db",
td_i = "time",
d_data = aquacomm_resps,
vb_i = "statvar_bl",
tb_i = "time",
b_data = aquacomm_resps
)
#> [1] 664.25Extent of recovery calculated as the log response ratio
(response = "lrr") of the state variable in the disturbed
time-series in relation to the state variable pre-disturbance
(b = "d"), summarized by the mean value
(summ_mode = "mean" - default, over a period
b_tf = c(5, 10)). The extent of recovery is calculated at
the point we understand all groups have stabilized
(t_rec = 28).
recovery_extent(
type = "functional",
response = "lrr",
b = "d",
summ_mode = "mean",
b_tf = c(5, 10),
t_rec = 28,
vd_i = "statvar_db",
td_i = "time",
d_data = aquacomm_resps
)
#> [1] 1.322534Figure 4: Schematic representation of the possible metrics of extent of recovery available in the estar package. ‘lrr’ refers to the log response ratio of the state variable in the disturbed system compared to the baseline time-series, ‘diff’ to the difference between them, and ‘tpost’, to a post-disturbance time step, specified by the user.
Rate of recovery
Rate of recovery calculated as the slope of the linear model which
predicts the log response ratio of the state variable in the disturbed
system compared to the baseline (b = "input) by time (over
a time frame (metric_tf = c(1, 28), Fig. 5-a).
recovery_rate(
type = "functional",
response = "v",
b = "input",
metric_tf = c(1, 28),
vd_i = "statvar_db",
td_i = "time",
d_data = aquacomm_resps,
vb_i = "statvar_bl",
tb_i = "time",
b_data = aquacomm_resps
)
#> [1] 22.20337Rate of recovery calculated as the slope of the linear model which
predicts the values of the state variable in the disturbed system
(response = "v") by time (over a time frame
(metric_tf = c(1, 28), Fig. 5-b).
recovery_rate(
type = "functional",
response = "v",
b = "input",
metric_tf = c(1, 28),
vd_i = "statvar_db",
td_i = "time",
d_data = aquacomm_resps,
vb_i = "statvar_bl",
tb_i = "time",
b_data = aquacomm_resps
)
#> [1] 22.20337Figure 5: Schematic representation of the possible metrics of rate of recovery available in the estar package. ‘lrr’ refers to the log response ratio of the state variable in the disturbed system compared to the baseline time-series, ‘v’ to ‘state variable’. The blue solid line identifies the linear model fitted to predict the response from time (along with its equation) and the double-headed arrow identifies the slope, which is the measure of rate of recovery
Persistence
Proportion of time over which the system persisted as defined by it
being within 1 standard deviation from the mean of the state variable
values in an independent baseline (b = "input") during the
same time period for which persistence is measured
(metric_tf = c(28, max(aquacomm_resps$time)), Fig. 6).
persistence(
type = "functional",
b = "input",
metric_tf = c(28, max(aquacomm_resps$time)),
vd_i = "statvar_db",
td_i = "time",
d_data = aquacomm_resps,
vb_i = "statvar_bl",
tb_i = "time",
b_data = aquacomm_resps
)
#> [1] 0.4Proportion of time over which the system persisted as defined by it
being within 1 standard deviation from the mean of the state variable
values during a pre-disturbance (b = "d") time period
(b_tf = c(-4, 0.14)). Persistence is measured for the
post-disturbance time period (metric_tf = c(1, 60), Fig.
6).
persistence(
type = "functional",
b = "d",
b_tf = c(-4, 0.14),
metric_tf = c(28, max(aquacomm_resps$time)),
vd_i = "statvar_db",
td_i = "time",
d_data = aquacomm_resps
)
#> [1] 0.2Overall Ecological Vulnerability
Area under the curve of the log response ratio
(response = "lrr") between the state variable in the
disturbed and baseline scenarios, since shortly after the disturbance
(we don’t have data from t = 0, the moment of application of the
insecticide) until the the end of the observation period
(metric_tf = c(0.14, 56)).
oev(
type = "functional",
response = "lrr",
metric_tf = c(0.14, 56),
vd_i = "statvar_db",
td_i = "time",
d_data = aquacomm_resps,
vb_i = "statvar_bl",
tb_i = "time",
b_data = aquacomm_resps
)
#> [1] 12.06002 ## Compositional
stability
The functions for functional stability can be used to calculate the
stability of community composition from community compositional data. To
do so, the functions call the vegdist function (from the
vegan package), which can be parameterized with the
method and binary arguments.
# Reformatting the macroinvertebrate community long-format data into
# community composition data
comm_data <- aquacomm_fgps |>
dplyr::group_by(time, treat) |>
dplyr::filter(treat %in% c(0, 44)) |>
dplyr::summarize_at(vars(herb, detr_herb, carn, omni, detr),
mean) |>
dplyr::ungroup()
control_comm <- comm_data |>
dplyr::filter(treat == 0) |>
dplyr::select(-treat)
dist_comm <- comm_data |>
dplyr::filter(treat == 44) |>
dplyr::select(-treat)It is worth noting that, if the user wants to calculate compositional stability from other metrics, they can simply input it as a single variable time-series, as demonstrated in the section “Functional stability”.
Invariability
Resistance
Maximal resistance (res_time = "max") over a time period
defined by the user (res_tf = c(0.14, 28)).
resistance(type = "compositional",
res_tf = c(0.14, 28),
res_time = "max",
comm_d = dist_comm,
comm_b = control_comm,
comm_t = "time")
#> [1] 0.8255708Resistance at a time step chosen by the user
(res_time = "defined", res_t = 28,).