Getting started with the codyna package
In codyna: Complex Dynamic Systems

knitr::opts_chunk$set(
  collapse = TRUE,
  fig.align = "center",
  dev = "jpeg",
  dpi = 300,
  out.width = "75%",
  comment = "#>"
)
suppressPackageStartupMessages({
  library("codyna")
})

This vignette demonstrates some basic usage of the codyna package. First, we load the package.

library("codyna")

We also load the engagement data available in the package (see ?engagement for further information)

data("engagement", package = "codyna")

Pattern Discovery

The codyna package provides an extensive set of features for discovering patterns in sequence data, such as n-grams, gapped patterns or repeated sequences of the same state using the function discover_patterns. The argument len can be used to specify the pattern lengths to look for. Similarly, argument gap specifies the gap sizes for gapped patterns.

discover_patterns(engagement, type = "ngram", len = 2:3)
discover_patterns(engagement, type = "gapped", gap = 1)
discover_patterns(engagement, type = "repeated", len = 2:3)

The returned data frames show the length of the pattern, the number of times it occurred across all sequences, its proportion among patterns of the same length, the number sequence that contained the pattern, and the proportion of sequences that contained the pattern (support). The function discover_patterns can also be used to look for specific patterns, for example

discover_patterns(engagement, pattern = "Active->*")

Here, the wildcard * matches any state, i.e., we are looking for patterns that start with the Active state and the following state can be any state.

We can also compute various sequence indices

sequence_indices(engagement)

Early Warning Signals

The codyna package provides methods for the detection of early warning signals (EWS). These methods have been adapted from the EWSmethods with a focus on high performance. Instead of explicit rolling window calculations, codyna implements the measures using update formulas, resulting up to 1000-fold reduction in computation time in some instances. First, we prepare some simple time series data for analysis.

set.seed(123)
ts_data <- stats::arima.sim(list(order = c(1, 1, 0), ar = 0.6), n = 200)

Both rolling window and expanding window methods are supported.

ews_roll <- detect_warnings(ts_data, method = "rolling")
ews_exp <- detect_warnings(ts_data, method = "expanding")

The function detect_warnings returns an object of class ews, and the results can be easily visualized with the plot method of this class.

plot(ews_roll)
plot(ews_exp)

Regime Detection

One of the core features of codyna is regime detection for time series data. Various methods are included with a user-friendly interface and automated parameter selection based on sensitivity. We continue with the example time series data.

regimes <- detect_regimes(
  data = ts_data,
  method = "threshold",
  sensitivity = "medium"
)
regimes

The columns value and time list the original time series values and time points. The column change shows when regime changes occur, and the type describes the type of regime change (which depends on the applied method). The id column provides the regime identifiers. The column magnitude quantifies the magnitude of the regime shift, and confidence is a method-dependent measure on the likelihood of an actual regime shift. In addition regime stability is described by stability along a stability score provided in the score column. The resulting object is of class regimes which has a customized plot method for visualizing the stability of the regimes along the original time series data.