flag_ts: Flag independent segments of a time series

In edwardlavender/Tools4ETS: Tools for Ecological Time Series

Flag independent segments of a time series

Description

The function 'flags' independent sections of time series using up to three methods. This is useful for identifying gaps in time series and/or for models of time series in which independent segments of time series need to be treated as such. To flag time series, the function can consider two drivers of independence: (a) a grouping factor (fct) which defines inherently independent time series in a dataset (e.g. a dataset may comprise time series for different individuals) and (b) gaps in the time series which, when greater than a user-defined threshold (duration_threshold), separate time series that can be considered effectively independent, even if they are derived from the same level of a grouping factor. Using these two criteria, time series can be flagged using three methods which different modelling approaches may require.

Usage

flag_ts(x, fct = NULL, dat = NULL, duration_threshold, flag = 1:3)

Arguments

x	A vector of time stamps, either as an integer/numeric object, a DateTimeClasses or a Date.
fct	(optional) A grouping factor defining independent segments of time series (e.g. individuals).
dat	(optional) A dataframe with a column x and, optionally, a column fct, can be supplied instead of x and fct.
duration_threshold	A numeric input defining the number of units (if x is an integer/numeric) or the number of minutes (if x is DateTimeClasses or a Date) between records after which separated time series are considered effectively 'independent'. This could be informed by the autocorrelation function of the residuals of a model without any autocorrelation.
flag	A numeric input/vector of 1, 2 or 3 specifying the flag type to be returned. flag = 1 returns a logical vector with TRUE marking the first observation in each independent segment of time series (e.g. as required by bam). flag = 2 returns identifies the first, second,... nth, independent segment of each factor level's time series. flag = 3 provides a unique identifier for each segment of time series (e.g. as required by gamm).

Details

Inputs should be ordered by ordered by fct (if applicable) then x.

Value

A dataframe with the duration between each observation and the next observation and corresponding flags.

Author(s)

Edward Lavender

Examples

#### Define some irregularly spaced time series
t <- c(seq.POSIXt(as.POSIXct("2016-01-01"), as.POSIXct("2016-01-02"), by = "6 hours"),
       as.POSIXct("2016-01-02 12:00:00"),
       seq.POSIXt(as.POSIXct("2016-01-02 18:00:00"), as.POSIXct("2016-01-03"), by = "5 hours")
)

#### Example (1) Supply a vector of time stamps to flag independent sections of time series
flag_ts(
  x = t,
  duration_threshold = 8*60,
  flag = 1:3)

#### Example (2) Supply a dataframe with a time stamp column instead
flag_ts(dat = data.frame(x = t),
        duration_threshold = 8*60,
        flag = 1:3)

#### Example (3) Supply a factor level which separates unique time series
fct_levels <- c(rep(1, length(t)), rep(2, length(t)))
t2 <- rep(t, 2)
flag_ts(
  x = t2,
  fct = fct_levels,
  duration_threshold = 8*60,
  flag = 1:3)

#### Example (4) Supply time series and a factor in a dataframe organised by fct then time stamp
flag_ts(dat = data.frame(x = t2, fct = fct_levels),
        duration_threshold = 8*60,
        flag = 1:3)

#### Example (5) Numeric example without factor
x <- c(seq(1, 5, by = 1), seq(100, 105, by = 1))
flag_ts(x = x,
        fct = NULL,
        dat = NULL,
        duration_threshold = 5,
        flag = 1:3)

#### Example (6) Numeric example with factor
fct_levels <- c(rep(1, length(x)), rep(2, length(x)))
x <- rep(x, 2)
flag_ts(x = x,
        fct = fct_levels,
        dat = NULL,
        duration_threshold = 5,
        flag = 1:3)

#### Example (7) Numeric example with factor via dat argument
cbind(x,
      flag_ts(dat = data.frame(x = x, fct = fct_levels),
              duration_threshold = 5,
              flag = 1:3)
)

edwardlavender/Tools4ETS documentation built on Nov. 29, 2022, 7:41 a.m.