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.1-7 Index]