Add metrics of stability following Ives et al examples

[nicholasjclark]

ar1 = 0.5
ar2 = -0.1
ar3 = -0.1
series <- arima.sim(model = list(ar = c(ar1, ar2, ar3)),
                    n = 100, sd = 1)

# Characteristic return rate (Ives et al 2003; 2010) is an 
# indicator of how quickly a dynamic process returns to 
# its stationary distribution following a perturbance; values
# approaching 1 (or greater than 1) indicate a longer time needed
# before the process returns to stability. To calculate this, all we 
# need is the AR coefficients in matrix form
B <- matrix(c(ar1, 1, 0,
              ar2, 0, 1,
              ar3, 0, 0),
           nrow = 3)

# Calculate eigenvalues of the AR coefficient matrix
evalues <- eigen(B)$values

# Complex eigenvalues indicate quasi-cyclic dynamics in
# which the process shows a characteristic periodicity
if(is.complex(evalues)){
  return_rate <- Re(evalues[1])
  period <- 2 * (pi / Im(evalues[1]))
} else {
  return_rate <- evalues[1]
  period <- NA
}
return_rate
period

plot(series)