[docs] Housekeeping of the docs

docs/make.jl

@@ -26,10 +26,10 @@ makedocs(;
             "Getting Started" => "getting_started.md",
             "Sklar's Distributions" => "sklar.md",
             "Elliptical Copulas" => "elliptical/generalities.md",
-            "Archimedean Copulas" => "archimedean/generalities.md",
-            "Liouville Copulas" => "Liouville.md",
+            "Archimedean Generators" => "archimedean/generalities.md",
             "Extreme Value Copulas" => "extremevalue/generalities.md",
             "Empirical Copulas" => "empirical/generalities.md",
+            "Vines Copulas" => "Vines.md",
             "Dependence measures" => "dependence_measures.md",
         ],
 

docs/src/Vines.md

@@ -1,5 +1,20 @@
+```@meta
+CurrentModule = Copulas
+```
+
+# Vines Copulas
+
+!!! todo "Not implemented yet!"
+    Do not hesitate to come talk on [our GitHub](https://github.com/lrnv/Copulas.jl) !
+
+One more noticeable class of copulas are the Vines copulas. These distributions use a graph of conditional distributions to encode the distribution of the random vector. To define such a model, working with conditional densities, and given any ordered partition $\bm i_1,...\bm i_p$ of $1,...d$, we write:
 
-One more noticeable class of copulas are the Vines copulas. These distributions use a graph of conditional distributions to encode the distribution of the random vector. To define such a model, working with conditional densities, and given any ordered partition $\bm i_1,...\bm i_p$ of $1,...d$, we write: 
 $$f(\bm x) = f(x_{\bm i_1}) \prod\limits_{j=1}^{p-1} f(x_{\bm i_{j+1}} | x_{\bm i_j}).$$
 
-Of course, the choice of the partition, of its order, and of the conditional models is left to the practitioner. The goal when dealing with such dependency graphs is to tailor the graph to reduce the error of approximation, which can be a tricky task. There exists simplifying assumptions that help with this matter, and we refer to ~\cite{durante2017a,nagler2016,nagler2018,czado2013,czado2019,graler2014} for a deep dive into the vine theory, along with some nice results and extensions. 
+Of course, the choice of the partition, of its order, and of the conditional models is left to the practitioner. The goal when dealing with such dependency graphs is to tailor the graph to reduce the error of approximation, which can be a tricky task. There exists simplifying assumptions that help with this matter, and we refer to [durante2017a,nagler2016,nagler2018,czado2013,czado2019,graler2014](@cite) for a deep dive into the vine theory, along with some nice results and extensions. 
+
+
+```@bibliography
+Pages = [@__FILE__]
+Canonical = false
+```

docs/src/archimedean/available_models.md

@@ -58,9 +58,7 @@ GumbelBarnettGenerator
 InvGaussianGenerator
 ```
 
-
-
 ```@bibliography
-Pages = ["available_models.md"]
+Pages = [@__FILE__]
 Canonical = false
 ```

docs/src/archimedean/generalities.md

@@ -9,20 +9,26 @@ An important parametric class of copulas is the class of Archimedean copulas. To
 ## Generators and d-monotony
 
 Archimedean generators can be defined as follows:
-> **Definition (Archimedean generator):** A $d$-Archimedean generator is a $d$-monotone function 
->
->$\phi :\mathbb R_+ \to [0,1]$ such that $\phi(0) = 1$ and $\phi(+\infty) = 0$.
+!!! definition "Definition (Archimedean generator):" 
+    A $d$-Archimedean generator is a $d$-monotone function 
 
-where the notion of $d$-monotone function can be defined as follows: 
+    $\phi :\mathbb R_+ \to [0,1]$ such that $\phi(0) = 1$ and $\phi(+\infty) = 0$.
 
-> **Definition (d-monotony [mcneil2009](@cite)):** A function $\phi$ is said to be $d$-monotone if it has $d-2$ derivatives which satisfy 
->
-> $(-1)^k \phi^{(k)} \ge 0 \;\forall k \in \{1,..,d-2\},$ and if $(-1)^{d-2}\phi^{(d-2)}$ is a non-increasing and convex function. 
->
->A function that is $d$-monotone for all $d$ is called **completely monotone**.
+where the notion of $d$-monotone function is defined (see e.g. [mcneil2009](@cite)) as follows:
 
+!!! definition "Definition (d-monotony):"
+    A function $\phi$ is said to be $d$-monotone if it has $d-2$ derivatives which satisfy 
 
-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. 
+    $(-1)^k \phi^{(k)} \ge 0 \;\forall k \in \{1,..,d-2\},$ and if $(-1)^{d-2}\phi^{(d-2)}$ is a non-increasing and convex function. 
+
+    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.
+
+!!! 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:
 
@@ -72,25 +78,24 @@ 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.
 
-> **Definition (Williamson d-transformation):** For a univariate non-negative random variable ``X``, with cumulative distribution function ``F`` and an integer $d\ge 2$, the Williamson-d-transform of ``X`` is the real function supported on $[0,\infty[$ given by:
->
-> $\phi(t) = 𝒲_{d}(X)(t)$
-> $=\int_{t}^{\infty} \left(1 - \frac{t}{x}\right)^{d-1} dF(x)$
-> $= \mathbb E\left( (1 - \frac{t}{X})^{d-1}_+\right) \mathbb 1_{t > 0} + \left(1 - F(0)\right)\mathbb 1_{t <0}$
+!!! definition "Definition (Williamson d-transformation):"
+    For a univariate non-negative random variable ``X``, with cumulative distribution function ``F`` and an integer $d\ge 2$, the Williamson-d-transform of ``X`` is the real function supported on $[0,\infty[$ given by:
+
+    $\phi(t) = 𝒲_{d}(X)(t)$
+    $=\int_{t}^{\infty} \left(1 - \frac{t}{x}\right)^{d-1} dF(x)$
+    $= \mathbb E\left( (1 - \frac{t}{X})^{d-1}_+\right) \mathbb 1_{t > 0} + \left(1 - F(0)\right)\mathbb 1_{t <0}$
 
 In this package, we implemented it through the [`WilliamsonGenerator`](@ref) class. It can be used as follows: 
 
 `WilliamsonGenerator(X::UnivariateRandomVariable, d)`.
 
 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. 
 
-!!! warn "`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. 
@@ -146,13 +151,14 @@ 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: 
 
-> **Definition (Archimedean copula):** If $\phi$ is a $d$-monotonous Archimedean generator, then the function 
->
->$$C(\bm u) = \phi\left(\sum\limits_{i=1}^d \phi^{-1}(u_i)\right)$$ is a copula. 
+!!! definition "Definition (Archimedean copula):"
+    If $\phi$ is a $d$-monotonous Archimedean generator, then the function 
+
+    $$C(\bm u) = \phi\left(\sum\limits_{i=1}^d \phi^{-1}(u_i)\right)$$ is a copula. 
 
 There are a few archimedean generators that are worth noting since they correspond to known archimedean copulas families: 
 * [`IndependentGenerator`](@ref): $\phi(t) =e^{-t} \text{ generates } \Pi$.
@@ -162,12 +168,13 @@ There are a few archimedean generators that are worth noting since they correspo
 
 There are a lot of others implemented in the package, see our [large list of implemented archimedean generator](@ref available_archimedean_models). 
 
-Archimedean copulas have a nice decomposition, called the Radial-simplex decomposition: 
+Archimedean copulas have a nice decomposition, called the Radial-simplex decomposition, developed in [mcneil2008,mcneil2009](@cite): 
 
-> **Property (Radial-simplex decomposition [mcneil2008,mcneil2009](@cite)):** A $d$-variate random vector $\bm U$ following an Archimedean copula with generator $\phi$ can be decomposed into 
->
-> $\bm U = \phi.(\bm S R),$
-> where $\bm S$ is uniform on the $d$-variate simplex and $R$ is a non-negative random variable, independent form $\bm S$, defined as the inverse Williamson $d$-transform of $\phi$.  
+!!! property "Property (Radial-simplex decomposition ):"
+    A $d$-variate random vector $\bm U$ following an Archimedean copula with generator $\phi$ can be decomposed into 
+
+    $\bm U = \phi.(\bm S R),$
+    where $\bm S$ is uniform on the $d$-variate simplex and $R$ is a non-negative random variable, independent form $\bm S$, defined as the inverse Williamson $d$-transform of $\phi$.  
 
 
 This is why `williamson_dist(G::Generator,d)` is such an important function in the API: it allows to generator the radial part and sample the Archimedean copula. You may call this function directly to see what distribution will be used: 
@@ -187,11 +194,12 @@ williamson_dist(ClaytonCopula(3,-0.2))
 for which the corresponding distribution is known but has no particular name, thus we implemented it under the `ClaytonWilliamsonDistribution` name.
 
 !!! note "Frailty decomposition for completely monotonous generators"
-    It is well-known that completely monotone generators are Laplace transforms of non-negative random variables. This gives rise to another decomposition:
+    It is well-known that completely monotone generators are Laplace transforms of non-negative random variables. This gives rise to another decomposition in [hofert2013](@cite):
+
+    !!! property "Property (Frailty decomposition):"
+        When $\phi$ is completely monotone, it is the Laplace transform of a non-negative random variable $W$ such that
 
-    > **Property (Frailty decomposition [hofert2013](@cite):** When $\phi$ is completely monotone, it is the Laplace transform of a non-negative random variable $W$ such that
-    >
-    >$$\bm U = \phi(\bm Y / W),$$  where $\bm Y$ is a vector of independent and identically distributed (i.i.d.) exponential distributions.
+        $$\bm U = \phi(\bm Y / W),$$  where $\bm Y$ is a vector of independent and identically distributed (i.i.d.) exponential distributions.
 
     The link between the distribution of $R$ and the distribution of $W$ can be explicited. We exploit this link and provide the `WilliamsonFromFrailty()` constructor that construct the distribution of $R$ from the distribution of $W$ and returns the corresponding  `WilliamsonGenerator` from the frailty distribution itself. The corresponding ϕ is simply the laplace transform of $W$. This is another potential way of constructing new archimedean copulas !  
 
@@ -205,12 +213,27 @@ for which the corresponding distribution is known but has no particular name, th
 ArchimedeanCopula
 ```
 
-
 <!-- 
 TODO: Make a few graphs of bivariate archimedeans pdfs and cdfs. And provide a few more standard tools for these copulas ? 
 -->
 
+# Liouville Copulas
+
+!!! todo "Not merged yet !"
+    Liouville copulas are coming in this PR : https://github.com/lrnv/Copulas.jl/pull/83, but the work is not finished. 
+
+Archimedean copulas have been widely used in the literature due to their nice decomposition properties and easy parametrization. The interested reader can refer to the extensive literature [hofert2010,hofert2013a,mcneil2010,cossette2017,cossette2018,genest2011a,dibernardino2013a,dibernardino2013a,dibernardino2016,cooray2018,spreeuw2014](@cite) on Archimedean copulas, their nesting extensions and most importantly their estimation. 
+
+One major drawback of the Archimedean family is that these copulas have exchangeable marginals (i.e., $C(\bm u) = C(\mathrm{p}(\bm u))$ for any permutation $p(\bm u)$ of $u_1,...,u_d$): the dependence structure is symmetric, which might not be a wanted property. However, from the Radial-simplex expression, we can easily extrapolate a little and take for $\bm S$ a non-uniform distribution on the simplex. 
+
+Liouville's copulas share many properties with Archimedean copulas, but are not exchangeable anymore. This is an easy way to produce non-exchangeable dependence structures. See [cote2019](@cite) for a practical use of this property.
+
+Note that Dirichlet distributions are constructed as $\bm S = \frac{\bm G}{\langle \bm 1, \bm G\rangle}$, where $\bm G$ is a vector of independent Gamma distributions with unit scale (and potentially different shapes: taking all shapes equal yields the Archimedean case). 
+
+
+
+
 ```@bibliography
-Pages = ["generalities.md"]
+Pages = [@__FILE__]
 Canonical = false
 ```

docs/src/dependence_measures.md

@@ -1,3 +1,7 @@
+```@meta
+CurrentModule = Copulas
+```
+
 # Measures of dependency
 
 
@@ -8,13 +12,15 @@ We implement the few most known ones in this package.
 
 ## Kendall's τ and Spearman's ρ: bivariate and multivariate cases
 
-> **Definition (Kendall' τ):** For a copula $C$ with a density $c$, **whatever its dimension $d$**, its Kendall's τ is defined as: 
-> 
->$$\tau = 4 \int C(\bm u) \, c(\bm u) \;d\bm u -1$$
+!!! definition "Definition (Kendall' τ):"
+    For a copula $C$ with a density $c$, **whatever its dimension $d$**, its Kendall's τ is defined as: 
+
+    $$\tau = 4 \int C(\bm u) \, c(\bm u) \;d\bm u -1$$
 
-> **Definition (Spearman's ρ):** For a copula $C$ with a density $c$, **whatever its dimension $d$**, the Spearman's ρ is defined as: 
->
-> $$\rho = 12 \int C(\bm u) d\bm u -3.$$
+!!! definition "Definition (Spearman's ρ):"
+    For a copula $C$ with a density $c$, **whatever its dimension $d$**, the Spearman's ρ is defined as: 
+
+    $$\rho = 12 \int C(\bm u) d\bm u -3.$$
 
 These two dependence measures make more sense in the bivariate case than in other cases, and therefore we sometimes refer to the Kendall's matrix or the Spearman's matrix for the collection of bivariate coefficients associated to a multivariate copula. 
 We thus provide two different interfaces:
@@ -47,19 +53,20 @@ A few remarks on the state of the implementation:
 
 Many people are interested in the tail behavior of their dependence structures. Tail coefficients summarize this tail behavior.
 
->**Definition (Tail dependency):** For a copula $C$, we define (when they exist):
-> ```math
->  \begin{align}
->    \lambda &= \lim\limits_{u \to 1} \frac{1 - 2u - C(u,..,u)}{1- u} \in [0,1]\\
->    \chi(u) &= \frac{2 \ln(1-u)}{\ln(1-2u-C(u,...,u))} -1\\
->    \chi &= \lim\limits_{u \to 1} \chi(u) \in [-1,1]
->  \end{align}
->```
-> When $\lambda > 0$, we say that there is a strong upper tail dependency, and $\chi = 1$. When $\lambda = 0$, we say that there is no strong upper tail dependency, and if furthermore $\chi \neq 0$ we say that there is weak upper tail dependency.
+!!! definition "Definition (Tail dependency):"
+    For a copula $C$, we define (when they exist):
+    ```math
+     \begin{align}
+       \lambda &= \lim\limits_{u \to 1} \frac{1 - 2u - C(u,..,u)}{1- u} \in [0,1]\\
+       \chi(u) &= \frac{2 \ln(1-u)}{\ln(1-2u-C(u,...,u))} -1\\
+       \chi &= \lim\limits_{u \to 1} \chi(u) \in [-1,1]
+     \end{align}
+    ```
+    When $\lambda > 0$, we say that there is a strong upper tail dependency, and $\chi = 1$. When $\lambda = 0$, we say that there is no strong upper tail dependency, and if furthermore $\chi \neq 0$ we say that there is weak upper tail dependency.
 
 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!
 
 
@@ -68,6 +75,6 @@ Many parametric copulas families have simple surjections, injections, or even bi
 
 
 ```@bibliography
-Pages = ["dependence_measures.md"]
+Pages = [@__FILE__]
 Canonical = false
-```
+```

docs/src/dev_roadmap.md

@@ -5,19 +5,12 @@ CurrentModule = Copulas
 # Development roadmap
 
 We hope to implement a few more copula models into this package. The next ones to be implemented will probably be: 
-- Extreme values copulas. 
+- Liouville
 - Nested Archimedeans (for any generators, with automatic nesting conditions checks). 
 - Bernstein copula and more general Beta copula as smoothing of the Empirical copula. 
 - `CheckerboardCopula` (and more generally `PatchworkCopula`)
-
-More precisely, the following directions could be pursued:
-
-**Next:**
-- More documentation and tests for the current implementation. 
-- Docs: show how to use the `WilliamsonCopula` to implement generic Archimedeans.
 - Give the user the choice of fitting method via `fit(dist,data; method="MLE")` or `fit(dist,data; method="itau")` or `fit(dist,data; method="irho")`.
 - Fitting a generic archimedean with an empirically produced generator
-- Automatic checks of generator d-monotony ? Dunno if it is even possible. 
 
 **Maybe later:**
 - `NestedArchimedean`, with automatic checking of nesting conditions for generators.