add Bivariate Extreme Value Copulas

Project.toml

@@ -18,6 +18,7 @@ Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 Roots = "f2b01f46-fcfa-551c-844a-d8ac1e96c665"
 SpecialFunctions = "276daf66-3868-5448-9aa4-cd146d93841b"
 StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
+StatsFuns = "4c63d2b9-4356-54db-8cca-17b64c39e42c"
 TaylorSeries = "6aa5eb33-94cf-58f4-a9d0-e4b2c4fc25ea"
 WilliamsonTransforms = "48feb556-9bdd-43a2-8e10-96100ec25e22"
 
@@ -39,6 +40,7 @@ Roots = "1, 2"
 SpecialFunctions = "2"
 StableRNGs = "1"
 StatsBase = "0.33, 0.34"
+StatsFuns = "0.9, 1.3"
 TaylorSeries = "0.12, 0.13, 0.14, 0.15, 0.16, 0.17"
 Test = "1.6"
 TestItemRunner = "v0.2"

README.md

@@ -77,6 +77,7 @@ There are competing packages in Julia, such as [`BivariateCopulas.jl`](https://g
 | - Classic Bivariate      | ✔️ | ✔️ | ✔️ |
 | - Classic Multivariate   | ✔️ | ✔️ | ❌ |
 | - Archimedeans           | ✔️ (All of them) | ⚠️ Selected ones | ⚠️Selected ones |
+| - Bivariate Extreme Value| ✔️ | ❌ | ❌ |
 | - Obscure Bivariate      | ✔️ | ❌ | ❌ |
 | - Archimedean Chains     | ❌ | ✔️ | ❌ |
 

docs/make.jl

@@ -28,13 +28,15 @@ makedocs(;
             "Elliptical Copulas" => "elliptical/generalities.md",
             "Archimedean Copulas" => "archimedean/generalities.md",
             "Liouville Copulas" => "Liouville.md",
+            "Extreme Value Copulas" => "extremevalue/generalities.md",
             "Empirical Copulas" => "empirical/generalities.md",
             "Dependence measures" => "dependence_measures.md",
         ],
 
         "Bestiary" => [
             "elliptical/available_models.md",
             "archimedean/available_models.md",
+            "extremevalue/available_models.md",
             "empirical/available_models.md",
             "Other Copulas" => "miscellaneous.md",
             "Transformed Copulas" => "transformations.md",

docs/src/assets/references.bib

@@ -737,3 +737,112 @@ @article{Raftery2023
   year={2023},
   publisher={MDPI}
 }
+
+@article{tawn1988bivariate,
+  title={Bivariate extreme value theory: models and estimation},
+  author={Tawn, Jonathan A},
+  journal={Biometrika},
+  volume={75},
+  number={3},
+  pages={397--415},
+  year={1988},
+  publisher={Oxford University Press}
+}
+
+@article{mai2011bivariate,
+  title={Bivariate extreme-value copulas with discrete Pickands dependence measure},
+  author={Mai, Jan-Frederik and Scherer, Matthias},
+  journal={Extremes},
+  volume={14},
+  pages={311--324},
+  year={2011},
+  publisher={Springer}
+}
+
+@article{nikoloulopoulos2009extreme,
+  title={Extreme value properties of multivariate t copulas},
+  author={Nikoloulopoulos, Aristidis K and Joe, Harry and Li, Haijun},
+  journal={Extremes},
+  volume={12},
+  pages={129--148},
+  year={2009},
+  publisher={Springer}
+}
+
+@book{mai2012simulating,
+  title={Simulating copulas: stochastic models, sampling algorithms, and applications},
+  author={Mai, Jan-Frederik and Scherer, Matthias},
+  volume={4},
+  year={2012},
+  publisher={World Scientific}
+}
+
+@article{husler1989maxima,
+  title={Maxima of normal random vectors: between independence and complete dependence},
+  author={H{\"u}sler, J{\"u}rg and Reiss, Rolf-Dieter},
+  journal={Statistics \& Probability Letters},
+  volume={7},
+  number={4},
+  pages={283--286},
+  year={1989},
+  publisher={Elsevier}
+}
+
+@article{galambos1975order,
+  title={Order statistics of samples from multivariate distributions},
+  author={Galambos, Janos},
+  journal={Journal of the American Statistical Association},
+  volume={70},
+  number={351a},
+  pages={674--680},
+  year={1975},
+  publisher={Taylor \& Francis}
+}
+
+@article{ghoudi1998proprietes,
+  title={Propri{\'e}t{\'e}s statistiques des copules de valeurs extr{\^e}mes bidimensionnelles},
+  author={Ghoudi, Kilani and Khoudraji, Abdelhaq and Rivest, Et Louis-Paul},
+  journal={Canadian Journal of Statistics},
+  volume={26},
+  number={1},
+  pages={187--197},
+  year={1998},
+  publisher={Wiley Online Library}
+}
+
+@inproceedings{gudendorf2010extreme,
+  title={Extreme-value copulas},
+  author={Gudendorf, Gordon and Segers, Johan},
+  booktitle={Copula Theory and Its Applications: Proceedings of the Workshop Held in Warsaw, 25-26 September 2009},
+  pages={127--145},
+  year={2010},
+  organization={Springer}
+}
+
+@article{Joe1990,
+  title={Families of min-stable multivariate exponential and multivariate extreme value distributions},
+  author={Joe, Harry},
+  journal={Statistics \& probability letters},
+  volume={9},
+  number={1},
+  pages={75--81},
+  year={1990},
+  publisher={Elsevier}
+}
+
+@article{deheuvels1991limiting,
+  title={On the limiting behavior of the Pickands estimator for bivariate extreme-value distributions},
+  author={Deheuvels, Paul},
+  journal={Statistics \& Probability Letters},
+  volume={12},
+  number={5},
+  pages={429--439},
+  year={1991},
+  publisher={Elsevier}
+}
+@book{mai2014financial,
+  title={Financial engineering with copulas explained},
+  author={Mai, Jan-Frederik and Scherer, Matthias},
+  year={2014},
+  publisher={Springer}
+}

docs/src/extremevalue/available_models.md

@@ -0,0 +1,60 @@
+```@meta
+CurrentModule = Copulas
+```
+
+# [Extreme Values Copulas](@id available_extreme_models)
+
+## `AsymGalambosCopula`
+```@docs
+AsymGalambosCopula
+```
+
+## `AsymLogCopula`
+```@docs
+AsymLogCopula
+```
+
+## `AsymMixedCopula`
+```@docs
+AsymMixedCopula
+```
+
+## `BC2Copula`
+```@docs
+BC2Copula
+```
+
+## `CuadrasAugeCopula`
+```@docs
+CuadrasAugeCopula
+```
+
+## `GalambosCopula`
+```@docs
+GalambosCopula
+```
+
+## `HuslerReissCopula`
+```@docs
+HuslerReissCopula
+```
+
+## `LogCopula`
+```@docs
+LogCopula
+```
+
+## `MixedCopula`
+```@docs
+MixedCopula
+```
+
+## `MOCopula`
+```@docs
+MOCopula
+```
+
+## `tEVCopula`
+```@docs
+tEVCopula
+```

docs/src/extremevalue/generalities.md

@@ -0,0 +1,99 @@
+```@meta
+CurrentModule = Copulas
+```
+
+# [Extreme Value Copulas](@id Extreme_theory)
+
+*Extreme value copulas* are fundamental in the study of rare and extreme events due to their ability to model dependency in situations of extreme risk. This package proposes a wide selection of bivariate extreme values copulas, while multivariate cases are not implemented yet. Feel free to open an issue and/or propose pull requests if you want an implementation of a multivariate case. 
+
+
+A bivariate extreme value copula [gudendorf2010extreme](@cite) $C$ is a copula that has the following caracteristic property: 
+
+$$C(u_1^t, u_2^t)=C(u_1,u_2)^t, t > 0.$$
+
+It can be represented through its stable tail dependence function $\ell(\cdot)$:
+
+$$C(u_1, u_2)=\exp\{-\ell(\log(u_1),\log(u_2))\},$$
+
+or through a convex function $A: [0,1] \to [1/2, 1]$ satisfying $\max(t, t-1)\leq A(t) \leq 1,$ called its Pickands dependence function:
+
+$$C(u_1,u_2)=\exp\left\{\log(u_1u_2)A\left(\frac{\log(u_1)}{\log(u_1u_2)}\right)\right\},$$
+
+In the context of bivariate extreme value copulas, the functions $\ell$ and $A$ are related as follows:
+
+$$\ell(u_1,u_2)=(u_1+u_2)A\left(\frac{u_1}{u_1+u_2}\right).$$
+
+Therefore, in this implementation, it is sufficient to provide the Pickands dependence function $A$ to construct the implementation structure of an extreme value copula.
+
+In this package, there is an abstract type [`ExtremeValueCopula`](@ref) that provides a foundation for defining extreme value copulas. Many extreme value copulas are already implemented for you! See [this list](@ref available_extreme_models) to get an overview.
+
+If you do not find the one you need, you may define it yourself by subtyping `ExtremeValueCopula`. The API does not require much information, which is really convenient. Only a method for the pickand function `A(C::ExtremeValueCopula) = ...` is required. By providing this functions, you can easily create a new extreme value copula that fits your specific needs:
+
+```julia
+struct MyExtremeValueCopula{P} <: ExtremeValueCopula{P}
+    θ::P
+end
+
+A(C::ExtremeValueCopula, t) = (t^C.θ + (1 - t)^C.θ)^(1/C.θ) # This is the Pickands function of the Logistic (Gumbel) Copula
+```
+
+!!! info "Nomenclature information"
+    We have called `A()` the Pickands function, which is necessary for constructing the Extreme Value Copula. This binding is very generic and thus not exported from the package, you can use it through `Copulas.A()` and/or by importing it.
+
+# Advanced Concepts
+
+Here, we present some important concepts from the theory of extreme value copulas that are useful for the development of this package.
+
+Let $(X,Y) \sim C$ where $C$ is a bivariate extreme value copula. We have the following results:
+
+> **Proposition 1 (Ghoudi 1998 [ghoudi1998proprietes](@cite)):** Let $(X, Y) \sim C$, where $C$ is an extreme value copula. The joint distribution of $X$ and $Z = \frac{\log(X)}{\log(XY)}$ is given by:
+>
+> $$P(Z \leq z, X \leq x) =G(z,x)=\left(z + z(1-z)\frac{A'(z)}{A(z)}\right)x^{A(z)/z}, \quad 0\leq x,z \leq 1$$ 
+>
+> where $A'(z)$ denotes the derivate of function $A(z)$ at point $z.$
+
+Since $A$ is a convex function defined on $[0, 1]$ and satisfies $-1 \leq A'(z) \leq 1$, by extension, we define $A'(1)$ as the supremum of $A'(z)$ over $(0, 1)$. By setting $x = 1$ in the previous result, we obtain the marginal distribution of $Z$:
+$$P(Z \leq z) = G_Z(z) = z + z(1 - z) \frac{A'(z)}{A(z)}, \quad 0 \leq z \leq 1.$$
+
+This result was demonstrated by Deheuvels (1991) [deheuvels1991limiting](@cite) in the case where $A$ admits a second derivative.
+
+
+## Simulation of Bivariate Extreme Value Distributions
+
+To simulate a bivariate extreme value distribution $C(x, y)$, remark that if $F_1$ and $F_2$ are univariate extreme value distributions, then the pair $( F_1^{-1}(X), F_2^{-1}(Y) )$ is distributed according to a bivariate extreme value distribution. The proposed algorithm in Ghoudi,1998, [ghoudi1998proprietes](@cite) allows simulating such a distribution.
+
+Assume $A$ has a second derivative, making the distribution absolutely continuous. In this case, $Z$ is also absolutely continuous and has a density $g_Z(z)$ given by:
+
+$$g_Z(z) = \frac{d}{dz} G_Z(z) = 1 + (1 - z)^{-1} \left(A(z) - z A'(z)\right)$$
+
+The conditional distribution of $W$ given $Z$ is:
+
+$$F(w|z) = \frac{1}{g_Z(z)} \frac{d}{dz} F(z, w),$$ 
+
+which simplifies to:
+
+$$F(w|z) = w \frac{z(1 - z) A'(z)}{A(z) g_Z(z)} + (w - w \log w) \left(1 - \frac{z(1 - z) A''(z)}{A(z) g_Z(z)} \right)$$
+
+Given $Z$, the distribution of $W$ is uniform on $(0, 1)$ with probability $p(Z)$ and equals the product of two independent uniforms on $(0, 1)$ with probability $1 - p(Z)$, where:
+
+$$p(z) = \frac{z(1 - z) A'(z)}{A(z) g_Z(z)}$$
+
+Since $g_Z(z)$ is the derivative of the cumulative distribution function of $Z$, it holds that $0 \leq p(z) \leq 1$.
+
+For the class of Extreme Value Copulas, We follow the methodology proposed by Ghoudi,1998. page 191. [ghoudi1998proprietes](@cite). Here, is a detailed algorithm for sampling from bivariate Extreme Value Copulas:
+
+> **Algotithm 1: Bivariate Extreme Value Copulas**
+> 
+> *(1)* Simulate $U_1,U_2 \sim \mathcal{U}[0,1]$
+>
+> *(2)* Simulate $Z \sim G_Z(z)$ 
+>
+> *(3)* Select $W=U_1$ with probability $p(Z)$ and $W=U_1U_2$ with probability $1-p(Z)$
+> 
+> *(4)* Return $X=W^{Z/A(Z)}$ and $Y=W^{(1-Z)/A(Z)}$  
+
+Note that all functions present in the algorithm were previously defined in previous sections to ensure that the implemented methodology has a solid theoretical basis.
+
+```@docs
+ExtremeValueCopula
+```

src/Copulas.jl

@@ -7,6 +7,7 @@ module Copulas
     import Roots
     import Distributions
     import StatsBase
+    import StatsFuns
     import TaylorSeries
     import ForwardDiff
     import Cubature
@@ -49,6 +50,7 @@ module Copulas
     include("UnivariateDistribution/AlphaStable.jl")
     include("UnivariateDistribution/ClaytonWilliamsonDistribution.jl")
     include("UnivariateDistribution/WilliamsonFromFrailty.jl")
+    include("UnivariateDistribution/ExtremeDist.jl")
 
     # Archimedean generators
     include("Generator.jl")
@@ -80,6 +82,33 @@ module Copulas
            InvGaussianCopula,
            JoeCopula
 
+    # bivariate Extreme Value Copulas
+    include("ExtremeValueCopula.jl")
+    include("ExtremeValueCopulas/AsymGalambosCopula.jl")
+    include("ExtremeValueCopulas/AsymLogCopula.jl")
+    include("ExtremeValueCopulas/AsymMixedCopula.jl")
+    include("ExtremeValueCopulas/BC2Copula.jl")
+    include("ExtremeValueCopulas/CuadrasAugeCopula.jl")
+    include("ExtremeValueCopulas/GalambosCopula.jl")
+    include("ExtremeValueCopulas/HuslerReissCopula.jl")
+    include("ExtremeValueCopulas/LogCopula.jl")
+    include("ExtremeValueCopulas/MixedCopula.jl")
+    include("ExtremeValueCopulas/MOCopula.jl")    
+    include("ExtremeValueCopulas/tEVCopula.jl")
+
+    export AsymGalambosCopula,
+           AsymLogCopula,
+           AsymMixedCopula,
+           BC2Copula,
+           CuadrasAugeCopula,
+           GalambosCopula,
+           HuslerReissCopula,
+           LogCopula,
+           MixedCopula,
+           MOCopula,   
+           tEVCopula
+
+
     # Subsetting
     include("SubsetCopula.jl") # not exported yet.