2.1 Tail dependence structure

The tail structure of dependence is described by the stable tail dependence function ℓ defined above. In this package, it is saved in a ds object. The function gen.ds is used to generate these objects.

The multivariate asymmetric logistic model obtained through the option type = "alog". It generates a multivariate asymmetric logistic model, which has been first introduced by Tawn (1990). We have ℓ(x₁, …, x_d) = ∑_b ∈ B(∑_i ∈ b(β_i, b x_i)^1/α_b)^α_b where B is the power set of {1, ..., d} (or a strict subset of the power set), the dependence parameters α_b lie in (0, 1] and the collection of asymmetric weights β_i, b are coefficients from [0, 1] satisfying ∀i ∈ {1, …, d}, ∑_{b ∈ B : i ∈ b}β_i, b = 1. Missing asymmetric weights β_i, b are assumed to be zero.

The class ds is a list that consists of:

• the dimension d.

• the type (log or alog).

• the list sub that corresponds to B. When sub is provided, the same list of subsets is returned, eventually sorted. When sub = NULL then sub is a subset of the power set of {1, ..., d}. When the option mnns is used, the latter integer indicates the cardinality of non singleton subsets in B.

• the dependence parameter dep = α or the vector of dependence parameters dep = {α_b, b ∈ B}. When missing, these coefficients are obtained from independent standard uniform sampling.

• the list asy of asymmetric weights β_i, b for b ∈ B and i ∈ b. When missing, these coefficients are obtained from independent standard uniform sampling followed by a renormalization in order to satisfy the sum-to-one constraints.

Let us consider some examples.

## Construction of a ds object without using gen.ds
ds5 <- vector("list")
ds5$d <- 5
ds5$type <- "alog" 
ds5$sub <- list(c(1,3),2:4,c(2,5))
ds5$asy <- list(c(1,.3),c(.5,1-.3,1), c(1-.5,1))
ds5$dep <- c(.2,.5,.3)

For larger dimensions, defining a ds object can become tricky, and the use of gen.ds is very helpful. For example, a 10-dimensional asymmetric tail dependence structure can be randomly created as follows.

## Three constructions of ds object by using gen.ds
# only d is  given, sub, asy and dep are randomly sampled
ds10 <- gen.ds(d = 10)
# d and sub are given, asy and dep are randomly sampled
ds10 <- gen.ds(d = 10,  sub = list(1:2,1:7,3:5,7:10)) 
# d is  given, mnns indicates the cardinality of non singleton subsets in B
# sub, asy and dep are randomly sampled
ds10 <- gen.ds(d = 10, mnns = 4)

The symmetric case can be obtained through the type = "log" option in the gen.ds function, which yields a multivariate symmetric logistic model. This model is a well-known generalization of the bivariate extreme value logistic model introduced by Gumbel (1960). The parameter dep (with $0 < {\rm dep} \leq 1$) is the only parameter needed to write the following equation

$$\ell(x_1,\ldots,x_d) = ( \sum_{i=1}^d x_i^{1/{\rm dep}} )^{\rm dep}.$$

If the parameter dep is missing, the function gen.ds will randomly generate its value from a standard uniform distribution.

For example, to obtain a 3-dimensional symmetric tail dependence structure with a randomly generated dependence parameter, you can use the following code

ds3 <- gen.ds(d = 3, type = "log")
ds3$dep

## [1] 0.6160385

If you know the value of the dependence parameter, you can specify it by setting ds3$dep <- .3, or by using the dep argument directly

ds3 <- gen.ds(d = 3, type = "log", dep = .3)

2.2 Sampling models

As mentioned at the beginning of the previous section, the satdad package studies both the Mevlog and ArchimaxMevlog theoretical models.

Samples of the MEV random vector with logistic dependence structures can be obtained via the rMevlog function using Algorithms 2.1 and 2.2 in Stephenson(2003).

n <- 1000
sample.frechet <- rMevlog(n, ds5) # standard Frechet margins
loc <- runif(5)
scale <- runif(5, 1, 2)
shape <- runif(5, -1, 1)
mar.gev <- cbind(loc, scale, shape)
sample.gev <- rMevlog(n, ds5, mar = mar.gev) # GEV margins all distinct
sample.samegev <- rMevlog(n, ds5, mar = c(-1,0.1,1)) # Gumbel margins

In addition, the package provides functions for computing the stable tail dependence function (ellMevlog), cumulative distribution function (pMevlog), and probability density function (dMevlog) of the Mevlog distribution. The following are examples of commands for these functions, but without evaluation.

x5 <- runif(5)
ellMevlog(x5, ds5)
pMevlog(x5, ds5) # cdf under standard Frechet margins
pMevlog(x5, ds5, mar = c(1,1,0)) # cdf under standard Gumbel margins
dMevlog(x5, ds5) # pdf under standard Frechet margins

In addition to multivariate extreme value logistic models, referred to as Mevlog, the satdad package provides some particular cases of ArchimaxMevlog. We follow here Algorithm 4.1 of p. 124 in Charpentier et al. (2014). Let ψ defined by ψ(x) = ∫₀^∞exp (−xt)dF_V(t), where F_V is the cumulative distribution function of a positive random variable.

We define the random vector (U₁, ..., U_d) as U_i = ψ(−log (Y_i)/V) where

• Z has a multivariate extreme value distribution with stable tail dependence function ℓ ; here Z has standard Frechet margins,

• (Y₁, ..., Y_d) = (exp (−1/Z₁), ..., exp (−1/Z_d)) is the margin transform of $\bf Z$ so that $\bf Y$ is sampled from the extreme value copula associated with ℓ,

• V has the distribution function F_V,

• Y and V are independent.

Then, $\bf U$ is sampled from the Archimax copula C(x₁, …, x_d) = ψ(ℓ(ψ⁻¹(x₁), …, ψ⁻¹(x_d))) .

The package provides ArchimaxMevlog realizations of random vectors $\bf U$. The cases covered by the satdad package are as follows:

– ψ is one among three types:

• ψ(t) = exp (−t) ; set dist = "ext".

• $\psi(t)=\dfrac{{\rm lambda}}{t+{\rm lambda}}$ ; set dist = "exp" and dist.param = lambda.

• $\psi(t)=\dfrac{1}{(t+{\rm scale})^{\rm shape}}$ ; set dist = "gamma" and dist.param = c(shape, scale).

– ℓ is the stable tail dependence function (stdf) associated with (a)symmetric logistic extreme value models.

ArchimaxMevlog samples are obtained via

n <- 1000
sample.ext <- rArchimaxMevlog(n, ds5, dist = "ext")
lambda <- runif(1, 1, 2)
sample.exp <- rArchimaxMevlog(n, ds5, dist = "exp", dist.param = lambda)
shape <- runif(1, 1, 2)
scale <- runif(1, 1, 2)
sample.gamma <- rArchimaxMevlog(n, ds5, dist = "gamma", dist.param = c(shape, scale))

The satdadpackage provides functions for computing ℓ C, ψ, and ψ⁻¹ for ArchimaxMevlog models. Specifically, ellArchimaxMevlog, copArchimaxMevlog, psiArchimaxMevlog and psiinvArchimaxMevlog can be used.

x <- runif(5)
ellMevlog(x, ds5)

## [1] 0.8818475

ellArchimaxMevlog(x, ds5)

## [1] 0.8818475

copArchimaxMevlog(x, ds5, dist = "ext")

## [1] 7.885969e-05

copArchimaxMevlog(x, ds5,  dist = "exp", dist.param = lambda)

## [1] 0.002429436

copArchimaxMevlog(x, ds5, dist = "gamma", dist.param = c(shape, scale))

## [1] 0.002904689

2.3 Measures and plots of the tail dependence

The tail dependence is completely characterized by the stdf ℓ, or equivalently by the ds object in this package. Summaries and graphical tools are obviously appreciated.

Well known extremal coefficients (ec), introduced by Tiago de Oliveira, J. (1962/63) and Smith (1990), are available in satdad. However, the focus is on the tail superset importance coefficients, which were introduced in Mercadier and Roustant (2019) and upper bounded in Mercadier and Ressel (2021). We believe that they also offer an interesting perspective on the description of the structure of the stable tail dependence function.

The theoretical functional decomposition of the variance of the stdf ℓ consists in writing D(ℓ) = ∑_{I ⊆ {1, ..., d}}D_I(ℓ) where D_I(ℓ) measures the variance of ℓ_I(U_I) the term associated with subset I in the Hoeffding-Sobol decomposition of ℓ ; note that U_I represents a random vector with independent standard uniform entries. Fixing a subset of components I, the theoretical tail superset importance coefficient (tsic) is defined as Υ_I(ℓ) = ∑_J ⊇ ID_J(ℓ) . An integral representation of the superset importance coefficient is provided by Formula (9) of Liu and Owen (2006). See also Mercadier and Roustant (2019) for its use in the extreme value context. Thus, the tsic here is the value of Υ_I(ℓ) obtained by Monte Carlo methods from the integral formula (3) in Mercadier and Roustant (2019).

res.tsic5 <- tsic(ds5)
as.character(res.tsic5$subsets)

##  [1] "1:2"     "c(1, 3)" "c(1, 4)" "c(1, 5)" "2:3"     "c(2, 4)" "c(2, 5)"
##  [8] "3:4"     "c(3, 5)" "4:5"

res.tsic5$tsic

##  [1] 1.477342e-32 7.067470e-04 1.359013e-32 9.815309e-33 1.464199e-04
##  [6] 4.055881e-04 1.987717e-03 9.838925e-04 9.571101e-33 8.393973e-33

The graphs function in satdad implements the methodology introduced in Mercadier and Roustant (2019). The default option which = taildependograph draws the PAIRWISE tsic in a graphical representation called the tail dependograph. The command is as follows.

oldpar <- par(mfrow=c(1,2))
graphs(ds10) # (left) the nodes are plotted on an invisible circle
graphs(ds10, random = TRUE) # (right) the position of the nodes are random

par(oldpar)

oldpar <- par(mfrow=c(1,2))
graphs(ds3) # (left) the symmetric structure
graphs(ds5) # (right) the asymmetric structure contructed "manualy"

par(oldpar)

A theoretical upper bound for tsic Υ_I(ℓ) is given by Theorem 2 in Mercadier and Ressel (2021) which states that $$\Upsilon_I(\ell)\leq \frac{2(|I|!)^2}{(2|I|+2)!}$$ for any stdf ℓ. This allows for meaningful comparison of these indices, regardless of the cardinality of I, using the expression $$\dfrac{\Upsilon_I(\ell)}{D(\ell)}\times \frac{(2|I|+2)!}{2(|I|!)^2}\;.$$ The option sobol = TRUE provides the renormalization by D(ℓ), while norm = TRUE multiplies by the inverse of the upper bound. The Cleveland dot plot is a useful tool to globally compare these coefficients.

plotClev(ds5)

The variance contribution D_I(ℓ) are referred to as the tail importance coefficient (tic) in this package, and should not be confused with the previously mentioned tsic, where “s” denotes supersets. The sobol version of tic, defined as $$S_I(\ell)=\frac{D_I(\ell)}{D(\ell)}$$ can also be computed using this package.

res.tic5 <- tic(ds5, ind = "with.singletons", sobol = TRUE)
sobol5 <- res.tic5$tic # which sum should be 1

Well known extremal coefficients (ec) can be computed and visualized as follows.

res.ec10 <- ec(ds10)
as.character(res.ec10$subsets)

##  [1] "1:2"      "c(1, 3)"  "c(1, 4)"  "c(1, 5)"  "c(1, 6)"  "c(1, 7)" 
##  [7] "c(1, 8)"  "c(1, 9)"  "c(1, 10)" "2:3"      "c(2, 4)"  "c(2, 5)" 
## [13] "c(2, 6)"  "c(2, 7)"  "c(2, 8)"  "c(2, 9)"  "c(2, 10)" "3:4"     
## [19] "c(3, 5)"  "c(3, 6)"  "c(3, 7)"  "c(3, 8)"  "c(3, 9)"  "c(3, 10)"
## [25] "4:5"      "c(4, 6)"  "c(4, 7)"  "c(4, 8)"  "c(4, 9)"  "c(4, 10)"
## [31] "5:6"      "c(5, 7)"  "c(5, 8)"  "c(5, 9)"  "c(5, 10)" "6:7"     
## [37] "c(6, 8)"  "c(6, 9)"  "c(6, 10)" "7:8"      "c(7, 9)"  "c(7, 10)"
## [43] "8:9"      "c(8, 10)" "9:10"

res.ec10$ec

##  [1] 1.819242 1.734868 1.731691 1.587897 2.000000 1.905721 1.829907 1.588352
##  [9] 1.945701 2.000000 1.770313 2.000000 2.000000 1.951804 1.911774 2.000000
## [17] 2.000000 1.832538 1.659476 2.000000 1.469354 1.416739 1.463328 1.469354
## [25] 1.918743 2.000000 1.875893 1.783928 1.918743 1.918743 2.000000 1.804355
## [33] 1.804355 1.202656 1.804355 2.000000 2.000000 2.000000 2.000000 1.275807
## [41] 1.608205 1.066084 1.608205 1.306577 1.608205

The option which = "iecgraph" in the graphs function of the package draws TWO minus the pairwise ec in a graphical representation.

oldpar <- par(mfrow=c(1,2))
graphs(ds5, which = "iecgraph")
graphs(ds10, which = "iecgraph")

par(oldpar)

3.1 Basics

Proposition 1 and Theorem 2 of Mercadier and Roustant (2019) indeed provide several rank-based expressions. Non parametric estimations of Υ_I(ℓ), D(ℓ), D_I(ℓ), and S_I(ℓ) are as follows:

$$\hat{\Upsilon}_{I,k,n}=\frac{1}{k^2}\sum_{s=1}^n\sum_{s^\prime=1}^n \prod_{t\in I}(\min(\overline{R}^{(t)}_s,\overline{R}^{(t)}_{s^\prime})-\overline{R}^{(t)}_{s}\overline{R}^{(t)}_{s^\prime}) \prod_{t\notin I} \min(\overline{R}^{(t)}_s,\overline{R}^{(t)}_{s^\prime})$$

$$\hat{D}_{k,n}=\frac{1}{k^2}\sum_{s=1}^n\sum_{s^\prime=1}^n \prod_{t\in I}\min(\overline{R}^{(t)}_s,\overline{R}^{(t)}_{s^\prime})- \prod_{t\in I}\overline{R}^{(t)}_{s}\overline{R}^{(t)}_{s^\prime}$$ $$\hat{D}_{I,k,n}=\frac{1}{k^2}\sum_{s=1}^n\sum_{s^\prime=1}^n \prod_{t\in I}(\min(\overline{R}^{(t)}_s,\overline{R}^{(t)}_{s^\prime})-\overline{R}^{(t)}_{s}\overline{R}^{(t)}_{s^\prime}) \prod_{t\notin I} \overline{R}^{(t)}_s\overline{R}^{(t)}_{s^\prime}$$ and $$\hat{S}_{I,k,n}=\dfrac{\hat{D}_{I,k,n}}{\hat{D}_{k,n}}\;.$$

The functions tsic, graphs, plotClev, ec and tic have thus an empirical counterpart, namely, tsicEmp, graphsEmp, plotClevEmp, ecEmp and ticEmp. The graphsEmp function has another version called graphsMapEmp when coordinates of the nodes are provided.

res.ecEmp <- ecEmp(sample.ext, ind = "with.singletons", k = 100)
res.tsicEmp <- tsicEmp(sample.exp, ind = "all", k = 100)
res.ticEmp <- ticEmp(sample.gamma, ind = 4, k = 100)

The plots only are displayed.

graphsEmp(sample.ext, k = 100)

plotClevEmp(sample.exp, ind = "all", k = 100)

3.2 The Danube dataset

The package graphicalExtremes implements the statistical methodology of Engelke and Hitz (2020), see also Asadi, Davison and Engelke (2015). The danube dataset in their package describes the river discharges for tributaries of the Danube.

library(graphicalExtremes)
g <- igraph::graph_from_edgelist(danube$flow_edges)
loc <- as.matrix(danube$info[,c('PlotCoordX', 'PlotCoordY')])
plot(g, layout = loc, vertex.color ="white", vertex.label.color = "darkgrey")

The tail dependence understood through the global sensibility analysis is now provided.

dan <- danube$data_clustered
graphsEmp(dan,  k=50, layout = loc)

The representation is also given on a realistic map.

lon <- as.numeric(unlist(danube$info[,"Long"]))
lat <- as.numeric(unlist(danube$info[,"Lat"]))*2
coord.dan <- list(lat = lat, lon = lon)
graphsMapEmp(dan, region = NULL, coord = coord.dan, k = 50, eps = 0.1)

A global comparison of the pairwise empirical tail superset importance coefficients is given by the empirical Cleveland’s dot plot of the sample.

plotClevEmp(dan,  k = 50,  ind = 2, labels = FALSE)

Observing the largest points, we focus on the largest below.

graphsEmp(dan,  k=50, layout = loc, select = 50, simplify = TRUE)

graphsMapEmp(dan, region = NULL, coord = coord.dan, k = 50, select = 50, eps = 0.1)

Graphs based on inverse extremal coefficients can also be obtained by adding the option which = "iecgraph".

3.3 Other datasets

We provide below some figures from Mercadier and Roustant (2019), first about temperatures (France dataset) and then log returns then (Stock dataset).

 ## Figure 9 (a) of Mercadier  and Roustant (2019).
graphsMapEmp(sample = France$ymt, k = 55,
        coord = France$coord,  region = 'France', thick.td = 3, select = 9)

## Figure 9 (b) of Mercadier  and Roustant (2019).
graphsMapEmp(sample = France$ymt, k = 55,
        coord = France$coord,  region = 'France', thick.td = 3, select = 30)

## Figure 9 (c) of Mercadier  and Roustant (2019).
graphsMapEmp(sample = France$ymt, k = 55, 
      coord = France$coord,  region = 'France', thick.td = 3)

## Figure 7(a) of Mercadier and Roustant (2019).
graphsEmp(Stock, k = 26, names = colnames(Stock), random = TRUE)

## Figure 8(a) of Mercadier and Roustant (2019).
graphsEmp(Stock, k = 26, names = colnames(Stock), random = TRUE, select = 9)

## Figure 8(b) of Mercadier and Roustant (2019).
graphsEmp(Stock, k = 26, names = colnames(Stock), random = TRUE, select = 20)