R: Identify discrete events from time series and apply functions...

eventseq {hydromad}

R Documentation

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

Description

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

Usage

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, ...)

Arguments

`x, X`	a `ts` or `zoo` object. May be multivariate, i.e. have multiple columns.
`thresh`	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.
`mingap`	the minimum number of time steps that can separate events. Any inter-event durations shorter than this will be subsumed into the surrounding event.
`mindur`	the minimum number of time steps in each event window. Any events whose duration is shorter than this will be skipped.
`extend`	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`	`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`.
`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.
`indur`	the series must remain below `inthresh` for this many time steps in order to terminate an event.
`below`	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.
`all`	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`.
`continue`	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`.
`n`	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!
`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 (`cbind`ed) 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.
`simplify`	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.
`TIMING`	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?

Value

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: time that the event started (from time(X)).
Month, Year: month and year (as integers) of the mid-point of the event.
Value: result of FUN applied to the event.
Duration: length of the event in time steps / data points.
PreDuration: number of time steps since the last event ended.

Author(s)

Felix Andrews felix@nfrac.org

Examples

data(Queanbeyan)
## 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
nlevels(evq)
str(evq)
table(coredata(evq))
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))

evplot

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
set.seed(0)
ee <- eventseq(rnorm(100), n = 10, mingap = 2)
nlevels(ee)
attr(ee, "thresh")

## 
## example of classifying events based on hydro properties
##

data(Queanbeyan)
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)
table(coredata(combin[each.e]))

[Package hydromad version 0.9-18 Index]

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

Description

Usage

Arguments

Value

Author(s)

See Also

Examples