clust {POT}R Documentation

Identify Extreme Clusters within a Time Series

Description

A function to identify clusters of exceedances of a time series.

Usage

clust(data, u, tim.cond = 1, clust.max = FALSE, plot = FALSE,
only.excess = TRUE, ...)

Arguments

data A matrix/data.frame with two columns. Columns names must be ``obs'' for observations and ``time'' for the associated date of each observation.
u Numeric. A value giving the threshold.
tim.cond A time condition to ensure independence between events. Should be in the same unit than data[,"time"].
clust.max Logical. If FALSE (the default), a list containing the clusters of exceedances is returned. Else, a matrix containing the cluster maxima and related dates is returned.
plot Logical. If TRUE, identified clusters are displayed. Else (the default), no plot is produced.
only.excess Logical. If TRUE (the default), only exceedances are plotted. Else, all observations are displayed.
... Optional parameters to be passed in plot function.

Details

The clusters of exceedances are defined as follows:

  • The first exceedance initiates the first cluster;
  • The first observation under the threshold u ``ends'' the current cluster unless tim.cond does not hold;
  • The next exceedance initiates a new cluster;
  • The process is iterated as needed.

    This function differs from the function clusters of evd Package as independence condition i.e. tim.cond could be a ``temporal'' condition. That is, two events are considered independent if the inter-arrival time is greater than a fixed duration.

    However, it is also possible to used the ``index'' independence as in clust by setting data[,"time"] = 1:length(data[,"obs"]).

    Value

    If clust.max is FALSE, a list containing the clusters of exceedances is returned. Else, a matrix containing the cluster maxima, related dates and indices are returned.
    In any case, the returned object has an attribute exi giving an estimation of the Extremal Index, that is the inverse of the average cluster size.

    Author(s)

    Mathieu Ribatet

    See Also

    clusters of package evd.

    Examples

    data(ardieres)
    par(mfrow=c(1,2))
    clust(ardieres, 4, 10 / 365)
    clust(ardieres, 4, 10 / 365, clust.max = TRUE)
    clust(ardieres, 4, 10 / 365, clust.max = TRUE, plot = TRUE)
    ##The same but with optional arguments passed to function ``plot''
    clust(ardieres, 4, 10 / 365, clust.max = TRUE, plot = TRUE,
    xlab = "Time (Years)", ylab = "Flood discharges",
    xlim = c(1972, 1980))
    

    [Package POT version 1.0-5 Index]