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

Description Usage Arguments Details Value See Also Examples

View source: R/etfit.R

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

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

`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.

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.

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

## 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)