exdex (version 1.2.3)

dgaps: Maximum likelihood estimation using left-censored inter-exceedances times

Description

Calculates maximum likelihood estimates of the extremal index \(\theta\) based on a model for threshold inter-exceedances times of Holesovsky and Fusek (2020). We refer to this as the \(D\)-gaps model, because it uses a tuning parameter \(D\), whereas the related \(K\)-gaps model of Suveges and Davison (2010) has a tuning parameter \(K\).

Usage

dgaps(data, u, D = 1, inc_cens = TRUE)

Value

An object (a list) of class c("dgaps", "exdex") containing

theta

The maximum likelihood estimate (MLE) of \(\theta\).

se

The estimated standard error of the MLE, calculated using an algebraic expression for the observed information. If the estimate of \(\theta\) is 0 then se is NA.

se_exp

The estimated standard error of the MLE, calculated using an algebraic expression for the expected information. If the estimate of \(\theta\) is 0 then se_exp is NA. This is provided because cases may be encountered where the observed information is not positive.

ss

The list of summary statistics returned from dgaps_stat.

D, u, inc_cens

The input values of D, u and inc_cens.

max_loglik

The value of the log-likelihood at the MLE.

call

The call to dgaps.

Arguments

data

A numeric vector or numeric matrix of raw data. If data is a matrix then the log-likelihood is constructed as the sum of (independent) contributions from different columns. A common situation is where each column relates to a different year.

If data contains missing values then split_by_NAs is used to divide the data further into sequences of non-missing values, stored in different columns in a matrix. Again, the log-likelihood is constructed as a sum of contributions from different columns.

u

A numeric scalar. Extreme value threshold applied to data.

D

A numeric scalar. The censoring parameter \(D\). Threshold inter-exceedances times that are not larger than D units are left-censored, occurring with probability \(\log(1 - \theta e^{-\theta d})\), where \(d = q D\) and \(q\) is the probability with which the threshold \(u\) is exceeded.

inc_cens

A logical scalar indicating whether or not to include contributions from right-censored inter-exceedance times, relating to the first and last observations. It is known that these times are greater than or equal to the time observed. If data has multiple columns then there will be right-censored first and last inter-exceedance times for each column.

Details

If inc_cens = FALSE then the maximum likelihood estimate of the extremal index \(\theta\) under the \(D\)-gaps model of Holesovsky and Fusek (2020) is calculated. Under this model inter-exceedance times that are less than or equal to \(D\) are left-censored, as a strategy to mitigate model mis-specification resulting from the fact that inter-exceedance times that are equal to 0 are expected under the model but only positive inter-exceedance times can be observed in practice.

If inc_cens = TRUE then information from the right-censored first and last inter-exceedance times are also included in the likelihood to be maximized. For an explanation of the idea see Attalides (2015). The form of the log-likelihood is given in the Details section of dgaps_stat.

It is possible that the estimate of \(\theta\) is equal to 1, and also possible that it is equal to 0. dgaps_stat explains the respective properties of the data that cause these events to occur.

References

Holesovsky, J. and Fusek, M. Estimation of the extremal index using censored distributions. Extremes 23, 197-213 (2020). tools:::Rd_expr_doi("10.1007/s10687-020-00374-3")

Suveges, M. and Davison, A. C. (2010) Model misspecification in peaks over threshold analysis, Annals of Applied Statistics, 4(1), 203-221. tools:::Rd_expr_doi("10.1214/09-AOAS292")

See Also

dgaps_confint to estimate confidence intervals for \(\theta\).

dgaps_methods for S3 methods for "dgaps" objects.

dgaps_imt for the information matrix test, which may be used to inform the choice of the pair (u, D).

choose_ud for a diagnostic plot based on dgaps_imt.

dgaps_stat for the calculation of sufficient statistics for the \(D\)-gaps model.

Examples

### S&P 500 index

u <- quantile(sp500, probs = 0.60)
theta <- dgaps(sp500, u = u, D = 1)
theta
summary(theta)
coef(theta)
nobs(theta)
vcov(theta)
logLik(theta)

### Newlyn sea surges

u <- quantile(newlyn, probs = 0.60)
theta <- dgaps(newlyn, u = u, D = 2)
theta
summary(theta)

### Uccle July temperatures

# Using vector input, which merges data from different years
u <- quantile(uccle720$temp, probs = 0.9, na.rm = TRUE)
theta <- dgaps(uccle720$temp, u = u, D = 2)
theta

# Using matrix input to separate data from different years
u <- quantile(uccle720m, probs = 0.9, na.rm = TRUE)
theta <- dgaps(uccle720m, u = u, D = 2)
theta