diff --git a/docs/src/archimedean/generalities.md b/docs/src/archimedean/generalities.md index 9616e931..77ab1387 100644 --- a/docs/src/archimedean/generalities.md +++ b/docs/src/archimedean/generalities.md @@ -23,8 +23,12 @@ where the notion of $d$-monotone function is defined (see e.g. [mcneil2009](@cit A function that is $d$-monotone for all $d$ is called **completely monotone**. +In this package, there is an abstract class [`Generator`](@ref) that contains those generators. -In this package, there is an abstract class [`Generator`](@ref) that contains those generators. Many Archimedean generators are already implemented for you ! See [the list of implemented archimedean generator](@ref available_archimedean_models) to get an overview. +!!! tip "Available Archimedean generators" + The package covers every archimedean generators that exists through a generic implementation of the Williamson d-transform, see the next section. + + On the other hand, many parametric Archimedean generators are specifically implemented, see [this list of implemented archimedean generator](@ref available_archimedean_models) to get an overview of which ones are availiable. If you do not find the one you need, you may define it yourself by subtyping `Generator`. The API does not ask for much information, which is really convenient. Only the two following methods are required: @@ -74,8 +78,6 @@ Generator Note that the rate at which these functions are reaching 0 (and their inverse reaching infinity on the left boundary) can vary a lot from one to the other. Note also that the difference between each of them is easier to grasp on the inverse plot. - - ## Williamson d-transform An easy way to construct new $d$-monotonous generators is the use of the Williamson $d$-transform. @@ -93,7 +95,7 @@ In this package, we implemented it through the [`WilliamsonGenerator`](@ref) cla This function computes the Williamson d-transform of the provided random variable $X$ using the [`WilliamsonTransforms.jl`](https://github.com/lrnv/WilliamsonTransforms.jl) package. See [williamson1955multiply, mcneil2009](@cite) for the literature. -!!! warning "`max_monotony` of Williamson generators" +!!! note "`max_monotony` of Williamson generators" The $d$-transform of a positive random variable is $d$-monotonous but not $k$-monotonous for any $k > d$. Its max monotony is therefore $d$. This has a few implications, one of the biggest one is that the $d$-variate Archimedean copula that corresponds has no density. More genrally, if you want your Archimedean copula to have a density, you have to use a generator that is more-monotonous that the dimension of your model. @@ -149,7 +151,7 @@ plot!(x -> ϕ⁻¹(G2,x), xlims=(0.1,0.9), label="G2") As obvious from the definition of the Williamson transform, using a discrete distribution produces piecewise-linear generators, where the number of pieces is dependent on the order of the transformation. -## Archimedean copulas +## Archimedean Copulas Let's first define formally archimedean copulas: diff --git a/docs/src/dependence_measures.md b/docs/src/dependence_measures.md index 1bfd2d7e..89edf74c 100644 --- a/docs/src/dependence_measures.md +++ b/docs/src/dependence_measures.md @@ -66,7 +66,7 @@ Many people are interested in the tail behavior of their dependence structures. The graph of $u \to \chi(u)$ over $[\frac{1}{2},1]$ is an interesting tool to assess the existence and strength of the tail dependency. The same kind of tools can be constructed for the lower tail. -!!! note "Tail dependencies: WIP" +!!! note "Tail dependencies: work in progress" The formalization of an interface for obtaining the tail dependence coefficients of copulas is still a work a in progress in the package. Do not hesitate to reach us on github if you want to discuss it! diff --git a/docs/src/extremevalue/generalities.md b/docs/src/extremevalue/generalities.md index 54b4ea5a..a45680ba 100644 --- a/docs/src/extremevalue/generalities.md +++ b/docs/src/extremevalue/generalities.md @@ -6,6 +6,8 @@ CurrentModule = Copulas *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. +!!! note "Only Bivariate" + The implementation we propose here only deals with bivariate extreme value copulas. Multivariate cases are more tedious to implement, but not impossible: if you want to propose an implementation, we can provide guidance on how to merge it here, do not hesitate to reach us on github. A bivariate extreme value copula [gudendorf2010extreme](@cite) $C$ is a copula that has the following caracteristic property: @@ -23,9 +25,10 @@ In the context of bivariate extreme value copulas, the functions $\ell$ and $A$ $$\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. +!!! tip "Only `A` is needed" + In our implementation, it is sufficient to provide the Pickands dependence function $A$ to construct the extreme value copula and have it work correctly. Providing the other functions would, of course, improve performances. -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. +In this package, there is an abstract type [`ExtremeValueCopula`](@ref) that provides a foundation for defining bivariate 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: @@ -37,16 +40,13 @@ 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 result from [ghoudi1998proprietes](@cite): -!!! property "Property (Ghoudi 1998): +!!! property "Property (Ghoudi 1998):" 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$$ diff --git a/docs/src/getting_started.md b/docs/src/getting_started.md index cafdb691..687462b4 100644 --- a/docs/src/getting_started.md +++ b/docs/src/getting_started.md @@ -2,12 +2,14 @@ CurrentModule = Copulas ``` -## Multivariate random vectors - This section gives some general definitions and tools about dependence structures, multivariate random vectors and copulas. Along this journey through the mathematical theory of copulas, we link to the rest of the documentation for more specific and detailed arguments on particular points, or simply to the technical documentation of the actual implementation. -The interested theoretical reader can take a look at the standard books on the subject [joe1997,cherubini2004,nelsen2006,joe2014](@cite) or more recently [mai2017, durante2015a, czado2019,grosser2021](@cite). +The interested reader can take a look at the standard books on the subject [joe1997,cherubini2004,nelsen2006,joe2014](@cite) or more recently [mai2017, durante2015a, czado2019,grosser2021](@cite). + +We start here by defining a few concepts about multivariate random vectors, dependence structures and copulas. + +## Reminder on multivariate random vectors + -We start here by defining a few concepts about dependence structures and copulas. Consider a real valued random vector $\bm X = \left(X_1,...,X_d\right): \Omega \to \mathbb R^d$. The random variables $X_1,...,X_d$ are called the marginals of the random vector $\bm X$. !!! info "Constructing random variables in Julia via `Distributions.jl`" @@ -71,7 +73,7 @@ u = rand(C,10) cdf(C,u) ``` -One of the reasons that makes copulas so useful is discovered by Sklar [sklar1959](@cite) in 1959: +One of the reasons that makes copulas so useful is the bijective map discovered by Sklar [sklar1959](@cite) in 1959: !!! theorem "Theorem (Sklar):" For every random vector $\bm X$, there exists a copula $C$ such that @@ -94,7 +96,7 @@ The independence copula can be constructed using the [`IndependentCopula(d)`](@r nothing # hide ``` -We leverage the Sklar theorem to construct multivariate random vectors from a copula-marginals specification. This can be used as follows: +We can then leverage the Sklar theorem to construct multivariate random vectors from a copula-marginals specification. This can be used as follows: ```@example 1 MyDistribution = SklarDist(Π, (X₁,X₂,X₃,X₄)) @@ -110,12 +112,11 @@ rand(MyDistribution,10) rand(MyOtherDistribution,10) ``` - -On the other hand, the [`pseudo()`](@ref Pseudo-observations) function computes ranks, effectively using Sklar's theorem the other way around (from the marginal space to the unit hypercube). +Sklar's theorem can be used the otehr way around (from the marginal space to the unit hypercube): this is e.g. what the [`pseudo()`](@ref Pseudo-observations) function does, computing ranks. !!! note "Independent random vectors" - Distributions.jl proposes the [`product_distribution`](https://juliastats.org/Distributions.jl/stable/multivariate/#Product-distributions) function to create those independent random vectors with given marginals. But you can already see that our approach generalizes to other dependence structres, and is thus much powerfull. + Distributions.jl proposes the [`product_distribution`](https://juliastats.org/Distributions.jl/stable/multivariate/#Product-distributions) function to create those independent random vectors with given marginals. `product_distribution(args...)` is basically equivalent to `SklarDist(Π, args)`, but you can already see that our approach generalizes to other dependence structres, and is thus much powerfull. Copulas are bounded functions with values in [0,1] since they correspond to probabilities. But their range can be bounded more precisely, and [lux2017](@cite) gives us: @@ -171,13 +172,12 @@ We see on the output that the parameters were correctly estimated from this samp ## Going further -There are a lot of available copula families in the package, that can be regrouped into a few classes: -- [Elliptical Copulas](@ref elliptical_copulas_header), including the Gaussian and Student cases. -- [Archimedean Copulas](@ref archimedean_copulas_header), leveraging their [Archimedean Generators](@ref archimedean_copulas_header) -- [Fréchet-Hoeffding bounds](https://en.wikipedia.org/wiki/Copula_(probability_theory)#Fr%C3%A9chet%E2%80%93Hoeffding_copula_bounds), -- [Other Copulas](@ref) +This documentation tries to join theoretical information and links to the literature with practical how-tos related to our specific implementation. It can be read as a lecture, or pin-pointed to check the specific feature you need through the search function. We hope that you'll enjoy using it! -Each of these classes more-or-less correspond to an abstract type in our type hierarchy, and to a section of this documentation. +!!! tip "Explore the bestiary!" + The package contains *a lot* of copula families. Classifying them is basically impossible, since the lcass is infinite dimensional, but the package proposes a few standard classes: elliptical, archimedeans, extreme values, empirical, vines... + + Each of these classes more-or-less correspond to an abstract type in our type hierarchy, and to a section of this documentation. Do not hesitate to explore the bestiary ! ```@bibliography