In TrashBirdEcology/regimeDetectionMeasures: Calculate Measures for Detecting Ecological Regimes

knitr::opts_chunk$set(echo=TRUE, fig.align='center', out.width = "85%")

About

This package calculates various regime detection metrics that have been used to detect ecological regime shifts. A 'new' metric, distance travelled (and the velocity of distance travelled) is also calculated. Functions for calculating the following regime detection measures are provided:

1. COMPOSITE:

   1. Distance travelled -see also package distanceTravelled.
   2. Fisher Information
   3. Variance Index

2. UNIVARIABLE:

   1. Skewness (mean and mode versions)
   2. Kurtosis
   3. Variance
   4. Mean
   5. Mode
   6. Coefficient of variation, CV
   7. Autocorrelation lag-1 (using stats::acf)

The UNIVARIABLE metrics are calculated using a moving-window analysis and can handle only individual state variables. That is, you will get one measurement per state variable. The COMPOSITE metrics can handle an infinite number of state variables, and will return a single measurement at each time point. It should be noted that the Fisher Information can be calculated using multiple methods (see the function description for rdm_window_analysis for more details).

Install package and load

devtools::install_github("trashbirdecology/regimedetectionmeasures", force=FALSE)

Load the package

library(regimeDetectionMeasures)
ggplot2::theme_set(theme_bw())

Munge and explore the original data

The function munge_orig_dat will munge your original dataset. If no data is provided in the argument data, it will download an example dataset from [Spanbauer][1] *link to original data.

origData <-  munge_orig_dat(example = TRUE)
# glimpse(origData)

If the argument for fill is not specified, the function munge_orig_dat will fill in missing species by time observations with zero ('0'). If data are true zeroes, in that a missing observation is not an NA, but is rather something else, this can be specified:

origData <- munge_orig_dat(example = TRUE, fill=NA) %>% glimpse()

Next, we can visualize the original data using a few different functions:

We can plot the original time series:

plot_orig_data(data = origData)

We can inspect the time beteween observations (i.e., is sampling regular, or irregular?):

plot_timeDiff(data = origData)

We can examine if species richness, or the number of unique state variables changes over time:

plot_richness(data = origData,
              example = F,
              print = T)

Calculate Regime Detection Measures: Velocity and Distance Travelled

Next, we want to calculate the distance travelled, velocity, and acceleration measures. This requires the data input dataInDist to have the following column names: c("sortVar", "variable","value"). If the column 'site' exists, and multiple sites are sampled, then the metrics will be calculated at each site independent of one another. Our example data [1] has a unique site, 'Foy' (Foy Lake).

distance.results <- calculate_distanceTravelled(origData, derivs = TRUE) %>% 
    gather(key=metricType, value=metricValue, -cellID,-sortVar)
# glimpse(distance.results)
unique(distance.results$metricType) 

This function outputs the following variables: - cellID: this is imputed, and can be ignored. This is used for the package bbsRDM - sortVar: this is the 'x-axis' variable; usually, this will be time, but if conducting spatial analyses, can be space (e.g. longitude) - ds: this is the total change in system variables between the current and previous time point. This value can take on any number or sign, and is uniquely calculated for every time step except the first - s: this the the distance travelled metric. It is used to calculate the velocity (dsdt), and is calculated at each time step as the cumulative sum of s. - dsdt (v): this is the velocity measurement. It is calculated as the speed of S at each time step. This is the first derivative of s, s^' -d2sdt2: this is the acceleration of s at each time step. This is the second derivative of s, s^''.

Calculate Regime Detection Measures: Fisher Information, Variance Index and other early warning signals

Calculate Fisher Inforamtion, Variance Index, and other univariate early warning signals using a moving-window approach. Results are all given in a long formatted data frame.

# remove the site variable
ews.results <- rdm_window_analysis(origData %>% dplyr::select(-site))
glimpse(ews.results)

Note the default of this function is to return VI (variance index), FI (fisher information), central tendencies and variance, CV (coefficient of variation), and skewness (using the mean and mode calculations):

ews.results %>% distinct(metricType)

Visualize the Results

Fisher Information & Variance Index

Use any method to visualize the results. Here, we use ggplot to visualize FI and VI, since these are metrics obtained for multiple species over time, rather than a single species over time.

fi.vi <- ews.results %>% filter(metricType  %in% c("FI_Eqn7.12", "VI"))

# Visualize using the window stop time, since these were moving window anlayses
ggplot(data = fi.vi, aes(x=winStop, y = metricValue))+
    geom_point() +
    facet_wrap(~metricType, scales = "free_y")

Distance Travelled and Velocity

Use any method to visualize the results. Here, we use ggplot to visualize the distance travelled and the velocity of the distance travelled.

# Visualize using the window stop time, since these were moving window anlayses
ggplot(data = distance.results, aes(x=sortVar, y = metricValue))+
    geom_line() +
    facet_wrap(~metricType, scales = "free_y")+xlab("years before 1950")

TrashBirdEcology/regimeDetectionMeasures documentation built on Oct. 13, 2019, 5:15 p.m.