# etfit: Estimate dependence measures In tsxtreme: Bayesian Modelling of Extremal Dependence in Time Series

## Description

Appropriate marginal transforms are done before the fit using standard procedures, before the dependence model is fitted to the data. Then the posterior distribution of a measure of dependence is derived. `thetafit` gives posterior samples for the extremal index θ(x,m) and `chifit` does the same for the coefficient of extremal dependence χ_m(x).

## Usage

 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17``` ```thetafit(ts, lapl = FALSE, nlag = 1, R = 1000, S = 500, u.mar = 0, u.dep, probs = seq(u.dep, 0.9999, length.out = 30), method.mar = c("mle", "mom","pwm"), method = c("prop", "MCi"), silent = FALSE, fit = TRUE, prev.fit=bayesfit(), par = bayesparams(), submodel = c("fom", "none"), levels=c(.025,.975)) chifit(ts, lapl = FALSE, nlag = 1, R = 1000, S = 500, u.mar = 0, u.dep, probs = seq(u.dep, 0.9999, length.out = 30), method.mar = c("mle", "mom","pwm"), method = c("prop", "MCi"), silent = FALSE, fit = TRUE, prev.fit=bayesfit(), par = bayesparams(), submodel = c("fom", "none"), levels=c(.025,.975)) ```

## Arguments

 `ts` a vector, the time series for which to estimate the extremal index θ(x,m) or the coefficient of extremal dependence χ_m(x), with x a probability level and m a run-length (see details). `lapl` logical; `TRUE` indicates that `ts` has a marginal Laplace distribution. If `FALSE` (default), `method.mar` is used to transform the marginal distribution of `ts` to Laplace. `nlag` the run-length; an integer larger or equal to 1. `R` the number of samples per MCMC iteration drawn from the sampled posterior distributions; used for the estimation of the dependence measure. `S` the number of posterior distributions sampled to be used for the estimation of the dependence measure. `u.mar` probability; threshold used for marginal transformation if `lapl` is `FALSE`. Not used otherwise. `u.dep` probability; threshold used for the extremal dependence model. `probs` vector of probabilities; the values of x for which to evaluate θ(x,m) or χ_m(x). `method.mar` a character string defining the method used to estimate the marginal GPD; either `"mle"` for maximum likelihood of `"mom"` for method of moments or `"pwm"` for probability weighted moments methods. Defaults to `"mle"`. `method` a character string defining the method used to estimate the dependence measure; either `"prop"` for proportions or `"MCi"` for Monte Carlo integration (see details). `silent` logical (`FALSE`); verbosity. `fit` logical; `TRUE` means that the dependence model must be fitted and the values in `par` are used. Otherwise the result from a previous call to `depfit`. `prev.fit` an object of class 'bayesfit'. Needed if `fit` is FALSE. Typically returned by a previous call to `depfit`. `par` an object of class '`bayesparams`' to be used for the fit of dependence model. `submodel` a character string, either `"fom"` for first order Markov or `"none"` for no specification. `levels` vector of probabilites; the quantiles of the posterior distribution of the extremal measure to be computed.

## Details

The sub-asymptotic extremal index is defined as

θ(x,m) = Pr(X_1 < x,…,X_m < x | X_0 > x),

whose limit as x and m go to appropriately is the extremal index θ. The extremal index can be interpreted as the inverse of the asymptotic mean cluster size (see `thetaruns)`.

The sub-asymptotic coefficient of extremal dependence is

χ_m(x) = Pr(X_m > x | X_0 > x),

whose limit χ defines asymptotic dependence (χ > 0) or asymptotic independence (χ = 0).

Both types of extremal dependence measures can be estimated either using a

* proportion method (`method == "prop"`), sampling from the conditional probability given X_0 > x and counting the proportion of sampled points falling in the region of interest, or

* Monte Carlo integration (`method == "MCi"`), sampling replicates from the marginal exponential tail distribution and evaluating the conditional tail distribution in these replicates, then taking their mean as an approximation of the integral.

`submodel == "fom"` imposes a first order Markov structure to the model, namely a geometrical decrease in α and a constant β across lags, i.e. α_j = α^j and β_j = β, j=1,…,m.

## Value

An object of class 'depmeasure', containing a subset of:

 `bayesfit ` An object of class 'bayesfit' `theta ` An array with dimensions `m` * `length(probs)` * (2+`length(levels)`), with the last dimension listing the posterior mean and median, and the `level` posterior quantiles `distr ` An array with dimensions `m` * `length(probs)` * `S`; posterior samples of `theta` `chi ` An array with dimensions `m` * `length(probs)` * (2+`length(levels)`), with the last dimension listing the posterior mean and median, and the `level` posterior quantiles `probs ` `probs` `levels ` `probs` transformed to original scale of `ts`

`depfit`, `theta2fit`, `thetaruns`
 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28``` ```## generate data from an AR(1) ## with Gaussian marginal distribution n <- 10000 dep <- 0.5 ar <- numeric(n) ar[1] <- rnorm(1) for(i in 2:n) ar[i] <- rnorm(1, mean=dep*ar[i-1], sd=1-dep^2) plot(ar, type="l") plot(density(ar)) grid <- seq(-3,3,0.01) lines(grid, dnorm(grid), col="blue") ## rescale the margin (focus on dependence) ar <- qlapl(pnorm(ar)) ## fit the data params <- bayesparams() params\$maxit <- 100 # bigger numbers would be params\$burn <- 10 # more sensible... params\$thin <- 4 theta <- thetafit(ts=ar, R=500, S=100, u.mar=0.95, u.dep=0.98, probs = c(0.98, 0.999), par=params) ## or, same thing in two steps to control fit output before computing theta: fit <- depfit(ts=ar, u.mar=0.95, u.dep=0.98, par=params) plot(fit) theta <- thetafit(ts=ar, R=500, S=100, u.mar=0.95, u.dep=0.98, probs = c(0.98, 0.999), fit=FALSE, prev.fit=fit) ```