kiener7: Asymmetric Kiener Distribution K7 (K2)
In FatTailsR: Kiener Distributions and Fat Tails in Finance

Description Usage Arguments Details References See Also Examples

Density, distribution function, quantile function, random generation, value-at-risk, expected shortfall (+ signed left/right tail mean) and additional formulae for asymmetric Kiener distribution K7 = K2. With K7, the vector of parameters is provided as coefk, usually estimated with paramkienerX (and ~X5,~X7) or regkienerLX$coefk. Main inputs can be supplied as vector (x,q,p) and matrix (coefk) and the resulting output is a matrix (useful for simulation).

dkiener7(x, coefk = c(0, 1, 3.2, 3.2, 3.2, 0, 0), log = FALSE)

pkiener7(q, coefk = c(0, 1, 3.2, 3.2, 3.2, 0, 0), lower.tail = TRUE,
  log.p = FALSE)

qkiener7(p, coefk = c(0, 1, 3.2, 3.2, 3.2, 0, 0), lower.tail = TRUE,
  log.p = FALSE)

rkiener7(n, coefk = c(0, 1, 3.2, 3.2, 3.2, 0, 0), same_p = FALSE)

dpkiener7(p, coefk = c(0, 1, 3.2, 3.2, 3.2, 0, 0), log = FALSE)

dqkiener7(p, coefk = c(0, 1, 3.2, 3.2, 3.2, 0, 0), log = FALSE)

lkiener7(x, coefk = c(0, 1, 3.2, 3.2, 3.2, 0, 0))

dlkiener7(lp, coefk = c(0, 1, 3.2, 3.2, 3.2, 0, 0), log = FALSE)

qlkiener7(lp, coefk = c(0, 1, 3.2, 3.2, 3.2, 0, 0), lower.tail = TRUE)

varkiener7(p, coefk = c(0, 1, 3.2, 3.2, 3.2, 0, 0), lower.tail = TRUE,
  log.p = FALSE)

ltmkiener7(p, coefk = c(0, 1, 3.2, 3.2, 3.2, 0, 0), lower.tail = TRUE,
  log.p = FALSE)

rtmkiener7(p, coefk = c(0, 1, 3.2, 3.2, 3.2, 0, 0), lower.tail = TRUE,
  log.p = FALSE)

dtmqkiener7(p, coefk = c(0, 1, 3.2, 3.2, 3.2, 0, 0), lower.tail = TRUE,
  log.p = FALSE)

eskiener7(p, coefk = c(0, 1, 3.2, 3.2, 3.2, 0, 0), lower.tail = TRUE,
  log.p = FALSE, signedES = FALSE)

`x`	vector of quantiles.
`coefk`	vector of 7 parameters `c(m,g,a,k,w,d,e)` or matrix with 7 columns.
`log`	logical. If TRUE, densities are given in log scale.
`q`	vector of quantiles.
`lower.tail`	logical. If TRUE, use p. If FALSE, use 1-p.
`log.p`	logical. If TRUE, probabilities p are given as log(p).
`p`	vector of probabilities.
`n`	integer. Number of observations. If length(n) > 1, the length is taken to be the number required.
`same_p`	logical. If FALSE (default), random probabilies are generated on the fly. If TRUE, the same set of random probabilities is used for each line of coefk (if coefk is a matrix).
`lp`	vector of logit of probabilities.
`signedES`	logical. FALSE (default) returns positive numbers for left and right tails. TRUE returns negative number (= `ltmkiener7`) for left tail and positive number (= `rtmkiener7`) for right tail.

Kiener distributions use the following parameters, some of them being redundant. See aw2k and pk2pk for the formulas and the conversion between parameters:

m (mu) is the median of the distribution.
g (gamma) is the scale parameter.
a (alpha) is the left tail parameter.
k (kappa) is the harmonic mean of a and w and describes a global tail parameter.
w (omega) is the right tail parameter.
d (delta) is the distortion parameter.
e (epsilon) is the eccentricity parameter.

Kiener distribution K7 is designed after kiener2 but uses as input coefk rather than m, g, a and w.

The d, p functions have no explicit forms. They are provided here for convenience. They are estimated from a reverse optimization on the quantile function and can be (very) slow, depending the number of points to estimate. We recommand to use the quantile function as much as possible. WARNING: Results may become inconsistent when a or w are smaller than 1.

qkiener7 function is defined for p in (0, 1) by:

qkiener7(p, coefk) = m + g * k * (- exp(-logit(p)/a) + exp(logit(p)/w) )

where k is the harmonic mean of the tail parameters a and w calculated by k = aw2k(a, w).

rkiener7 generates n random quantiles.

In addition to the classical d, p, q, r functions, the prefixes dp, dq, l, dl, ql are also provided.

dpkiener7 is the density function calculated from the probability p. It is defined for p in (0, 1) by:

dpkiener7(p, coefk) = p * (1 - p) / k / g / ( exp(-logit(p)/a)/a + exp(logit(p)/w)/w

dqkiener7 is the derivate of the quantile function calculated from the probability p. It is defined for p in (0, 1) by:

dqkiener7(p, coefk) = k * g / p / (1 - p) * ( exp(-logit(p)/a)/a + exp(logit(p)/w)/w )

lkiener7 function is estimated from a reverse optimization and can be (very) slow depending the number of points to estimate. Initialization is done by assuming a symmetric distribution lkiener1 around the harmonic mean k, then optimization is performed to take into account the true values a and w. The result can be then compared to the empirical probability logit(p). WARNING: Results may become inconsistent when a or w are smaller than 1.

dlkiener7 is the density function calculated from the logit of the probability lp = logit(p). it is defined for lp in (-Inf, +Inf) by:

dlkiener7(lp, coefk) = p * (1 - p) / k / g / ( exp(-lp/a)/a + exp(lp/w)/w )

qlkiener7 is the quantile function calculated from the logit of the probability. It is defined for lp in (-Inf, +Inf) by:

qlkiener7(lp, coefk) = m + g * k * ( - exp(-lp/a) + exp(lp/w) )

varkiener7 designates the Value a-risk and turns negative numbers into positive numbers with the following rule:

varkiener7 <- if(p <= 0.5) { - qkiener7 } else { qkiener7 }

Usual values in finance are p = 0.01, p = 0.05, p = 0.95 and p = 0.99. lower.tail = FALSE uses 1-p rather than p.

ltmkiener7, rtmkiener7 and eskiener7 are respectively the left tail mean, the right tail mean and the expected shortfall of the distribution (sometimes called average VaR, conditional VaR or tail VaR). Left tail mean is the integrale from -Inf to p of the quantile function qkiener7 divided by p. Right tail mean is the integrale from p to +Inf of the quantile function qkiener7 divided by 1-p. Expected shortfall turns negative numbers into positive numbers with the following rule:

eskiener7 <- if(p <= 0.5) { - ltmkiener7 } else { rtmkiener7 }

Usual values in finance are p = 0.01, p = 0.025, p = 0.975 and p = 0.99. lower.tail = FALSE uses 1-p rather than p.

dtmqkiener7 is the difference between the left tail mean and the quantile when (p <= 0.5) and the difference between the right tail mean and the quantile when (p > 0.5). It is in quantile unit and is an indirect measure of the tail curvature.

P. Kiener, Explicit models for bilateral fat-tailed distributions and applications in finance with the package FatTailsR, 8th R/Rmetrics Workshop and Summer School, Paris, 27 June 2014. Download it from: https://www.inmodelia.com/exemples/2014-0627-Rmetrics-Kiener-en.pdf

P. Kiener, Fat tail analysis and package FatTailsR, 9th R/Rmetrics Workshop and Summer School, Zurich, 27 June 2015. Download it from: https://www.inmodelia.com/exemples/2015-0627-Rmetrics-Kiener-en.pdf

C. Acerbi, D. Tasche, Expected shortfall: a natural coherent alternative to Value at Risk, 9 May 2001. Download it from: https://www.bis.org/bcbs/ca/acertasc.pdf

Symmetric Kiener distribution K1 kiener1, asymmetric Kiener distributions K2, K3 and K4 kiener2, kiener3, kiener4, conversion functions aw2k, estimation function paramkienerX, estimation function fitkienerX, regression function regkienerLX.

head(ED <- fatreturns(extractData())) 
(coefk  <- paramkienerX(ED, dgts = 3))  
x  <- -4
xx <- -4:4
p  <- 0.1
pp <- pprobs2

dkiener7(x)
dkiener7(x,  coefk) 
dkiener7(xx)
dkiener7(xx, coefk)

pkiener7(x)
pkiener7(x,  coefk) 
pkiener7(xx)
pkiener7(xx, coefk)

qkiener7(p)
qkiener7(p,  coefk) 
qkiener7(pp)
qkiener7(pp, coefk)

rkiener7(10)
rkiener7(10, coefk)

varkiener7(p)
varkiener7(p, coefk)
varkiener7(pp)
varkiener7(pp, coefk) 

ltmkiener7(p)
ltmkiener7(p, coefk)
ltmkiener7(pp)
ltmkiener7(pp, coefk)

eskiener7(p)
eskiener7(p, coefk)
eskiener7(pp)
eskiener7(pp, coefk)