eventseq {hydromad}R Documentation

Identify discrete events from time series and apply functions to them.


Identify discrete events from time series and apply functions to them.


eventseq(x, thresh = 0, mingap = 1, mindur = 1, extend = 0,
         inthresh = thresh, inx = x, indur = 1,
         below = FALSE, all = FALSE, continue = FALSE,
         n = NA)

eventapply(X, events, FUN = sum, ...,
           by.column = TRUE, simplify = TRUE,
           TIMING = c("start", "middle", "end"))

eventinfo(X, events, FUN = mean, ...)


x, X

a ts or zoo object. May be multivariate, i.e. have multiple columns.


threshold value: the data must be strictly above this level (or, if below = TRUE, below this level) to define an event. If x is a matrix (with multiple columns), thresh is allowed to be a vector with one value per column. In this case, events continue while any series exceeds the threshold. Finally, thresh can be a full matrix or vector of the same dimension as x. Any missing values are treated as below the threshold.


the minimum number of time steps that can separate events. Any inter-event durations shorter than this will be subsumed into the surrounding event.


the minimum number of time steps in each event window. Any events whose duration is shorter than this will be skipped.


a number of time steps to include on the end of each event window, before accounting for inthresh. If this causes events to run into following events they will be merged.


inthresh gives a second threshold value to define when events stop: after an event is initiated by exceeding thresh, it continues until the second (lower) threshold inthresh is reached (for at least indur steps). If missing or NULL, it defaults to thresh. As with thresh, inthresh is allowed to be a vector with values corresponding to the columns of inx.


optionally, a different series may be given to determine event termination with inthresh. E.g. an input series may define event starts and a response series may define when they end. If missing or NULL, defaults to x. As with x, this is allowed to be a matrix.


the series must remain below inthresh for this many time steps in order to terminate an event.


reverses the definition of events, to identify events where the data falls below thresh (and/or inthresh). Setting this to TRUE is equivalent to negating x and thresh, etc.


to include the periods between events as additional levels (i.e. as events in themselves). These inter-events will be assigned negative levels, while the actual events will have positive levels. Otherwise – in the default case – these inter-event periods are left as NA.


set continue = TRUE to extend each event until the following event; otherwise there are gaps between events (the default behaviour). This has no effect if all = TRUE.


number of events to be identified: if this is given (and > 0), then a value of thresh is estimated such that about this many events are returned. A warning is given if the actual number of events is not within 5 percent of n. Note that there may be multiple possible threshold levels giving the same number of events!


a factor-like object, perhaps ts or zoo. Its levels (unique values) define events, and NA values are ignored. If events is a factor or vector, its values are assumed to correspond to X; otherwise, it is assumed to be a time series object and is merged (cbinded) with X.

FUN, ..., by.column

a function to apply to the values in each event. In the default case of by.column = TRUE, FUN will be passed a vector of values from one column of X. When by.column = FALSE, which only makes sense when X is a matrix, FUN will be passed a matrix. The dots (...) are passed on too.


if FALSE, the result will be returned as a list with one (named) element for each event, rather than a time series like object. This case allows FUN to return a complex object or vectors of variable lengths.


defines how to construct the time index of the result. Should the time corresponding to an event be taken from the time() of its start, middle, or end?


eventseq returns a zoo object, with core data consisting of an ordered factor, representing the identified events, and the same time index as x. Periods between events are left as NA, unless all = TRUE in which case they are treated as separate events. The returned object stores thresh as an attribute.

eventapply returns a zoo object (an irregular time series in this case), with the value returned from FUN applied to each discrete event in X.

eventinfo returns a data.frame with columns


time that the event started (from time(X)).

Month, Year

month and year (as integers) of the mid-point of the event.


result of FUN applied to the event.


length of the event in time steps / data points.


number of time steps since the last event ended.


Felix Andrews

See Also

cut.Date, tapply, rollapply, aggregate.zoo, panel.xblocks, clusters in the evd package.


## wet period
x <- window(Queanbeyan, start = "1974-01-01", end = "1976-12-01")

evp <- eventseq(x$P, thresh = 5, inthresh = 1, indur = 4, continue = TRUE)
evq <- eventseq(x$Q, thresh = 2, indur = 4, mingap = 5)

nlevels(evp) ## number of events
eventapply(x$Q, evq, FUN = sum)
eventapply(x, evq, FUN = mean)
eventinfo(x$Q, evq)

evplot <- xyplot(x) + 
  layer_(panel.xblocks(evp, col = c("grey90", "grey80"), border = "grey80")) +
  layer(panel.xblocks(evq, block.y = 0, vjust = 1, col = 1))


update(evplot, type = "s",
    xlim = as.Date(c("1990-07-01", "1990-08-31"))) +
  layer(panel.abline(h = c(5,1), lty = 2), packets = 1)

## example of requesting a threshold giving about 'n' events
ee <- eventseq(rnorm(100), n = 10, mingap = 2)
attr(ee, "thresh")

## example of classifying events based on hydro properties

x <- window(Queanbeyan, start = "1974-01-01", end = "1976-12-01")
e <- eventseq(x$P, thresh = 5, inthresh = 1, indur = 4, continue = TRUE)

## classify events based on max flow
qclass <- cut(ave(coredata(x$Q), coredata(e), FUN = max),
              c(0, 0.5, 1, Inf))
qclass <- zoo(qclass, time(x))

## Classify events based on antecedent flow
x <- merge(x, Q1 = lag(x$Q, -1), all = c(TRUE, FALSE))
head1 <- function(z) z[1]
q1class <- cut(ave(coredata(x$Q1), coredata(e), FUN = head1),
               c(0, 0.2, 0.3, Inf))
q1class <- zoo(q1class, time(x))

## combined classification
combin <- factor(paste("M", unclass(qclass), "_A", unclass(q1class), sep =""))
combin <- zoo(combin, time(x))

## check results
head(data.frame(x, event = unclass(e), qclass, q1class, combin), 50)

## number of events in each class
each.e <- !duplicated(e)
[Package hydromad version 0.9-18 Index]