From 372e94a26a67b1b8bdc39468bae3c330e6fa13e5 Mon Sep 17 00:00:00 2001 From: Oskar Laverny Date: Sun, 4 Feb 2024 13:07:25 +0100 Subject: [PATCH] Fixes a few typos (#124) * Noted typos in the review * moar typooos * Small typos everywhere. --- docs/make.jl | 2 +- docs/src/Liouville.md | 2 +- docs/src/Vines.md | 2 +- docs/src/archimedean/generalities.md | 16 ++++++++-------- docs/src/dependence_measures.md | 20 ++++++++++---------- docs/src/dev_roadmap.md | 6 +++--- docs/src/elliptical/generalities.md | 2 +- docs/src/empirical/available_models.md | 12 ++++++------ docs/src/empirical/generalities.md | 20 ++++++++++---------- docs/src/exemples/fitting_sklar.md | 6 +++--- docs/src/exemples/turing.md | 10 +++++----- docs/src/getting_started.md | 10 +++++----- docs/src/index.md | 2 +- joss/paper.md | 8 ++++---- 14 files changed, 59 insertions(+), 59 deletions(-) diff --git a/docs/make.jl b/docs/make.jl index f66c89a5..19f07b10 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -41,7 +41,7 @@ makedocs(; "empirical/available_models.md", ], "Dependence measures" => "dependence_measures.md", - "Exemples" => [ + "Examples" => [ "exemples/fitting_sklar.md", "exemples/turing.md", ], diff --git a/docs/src/Liouville.md b/docs/src/Liouville.md index 9b68c850..23b92b07 100644 --- a/docs/src/Liouville.md +++ b/docs/src/Liouville.md @@ -5,7 +5,7 @@ CurrentModule = Copulas ## Liouville Copulas !!! note "Not merged yet !" - Liouville copulas are comming in this PR : https://github.com/lrnv/Copulas.jl/pull/83, but this is not merged yet. + Liouville copulas are coming in this PR : https://github.com/lrnv/Copulas.jl/pull/83, but this is not merged yet. 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. diff --git a/docs/src/Vines.md b/docs/src/Vines.md index 6e73151d..7bb5b31a 100644 --- a/docs/src/Vines.md +++ b/docs/src/Vines.md @@ -1,5 +1,5 @@ -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. \ No newline at end of file diff --git a/docs/src/archimedean/generalities.md b/docs/src/archimedean/generalities.md index 249a3200..fa926cf8 100644 --- a/docs/src/archimedean/generalities.md +++ b/docs/src/archimedean/generalities.md @@ -59,7 +59,7 @@ In this package, we implemented it through the [`WilliamsonGenerator`](@ref) cla `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. +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" 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. @@ -76,13 +76,13 @@ WilliamsonGenerator ## [Inverse Williamson d-transform](@id w_trans_section) -The Williamson d-transform is a bijective transformation[^1] from the set of positive random variables to the set of generators, and therefore has an inverse transformation (called, suprisingly, the inverse Williamson $d$-transform) that construct the a positive random variable *R* from a generator $\phi$. +The Williamson d-transform is a bijective transformation[^1] from the set of positive random variables to the set of generators. It therefore has an inverse transformation (called, surprisingly, the inverse Williamson $d$-transform) that construct the positive random variable *R* from a generator $\phi$. [^1]: - This bijection is to be taken carefully: the bijection is between random variables *with unit scales* and generators *with common value at 1*, sicne on both rescaling does not change the underlying copula. + This bijection is to be taken carefuly: the bijection is between random variables *with unit scales* and generators *with common value at 1*, sicne on both rescaling does not change the underlying copula. -This transformation is implemented through one method in the Generator interface that is worth talking a bit about : `williamson_dist(G::Generator, d)`. This function computes the inverse Williamson d-transform of the d-monotone archimedean generator ϕ, still using the [WilliamsonTransforms.jl](https://github.com/lrnv/WilliamsonTransforms.jl) package. See [williamson1955multiply, mcneil2009](@cite) +This transformation is implemented through one method in the Generator interface that is worth talking a bit about : `williamson_dist(G::Generator, d)`. This function computes the inverse Williamson d-transform of the d-monotone archimedean generator ϕ, still using the [`WilliamsonTransforms.jl`](https://github.com/lrnv/WilliamsonTransforms.jl) package. See [williamson1955multiply, mcneil2009](@cite). To put it in a nutshell, for ``\phi`` a ``d``-monotone archimedean generator, the inverse Williamson-d-transform of ``\\phi`` is the cumulative distribution function ``F`` of a non-negative random variable ``R``, defined by : @@ -90,10 +90,10 @@ To put it in a nutshell, for ``\phi`` a ``d``-monotone archimedean generator, th F(x) = 𝒲_{d}^{-1}(\phi)(x) = 1 - \frac{(-x)^{d-1} \phi_+^{(d-1)}(x)}{k!} - \sum_{k=0}^{d-2} \frac{(-x)^k \phi^{(k)}(x)}{k!} ``` -The [WilliamsonTransforms.jl](https://github.com/lrnv/WilliamsonTransforms.jl) package implements this transformation (and its inverse, the Williamson d-transfrom) in all generality. It returns this cumulative distribution function in the form of the corresponding random variable `<:Distributions.ContinuousUnivariateDistribution` from `Distributions.jl`. You may then compute : +The [`WilliamsonTransforms.jl`](https://github.com/lrnv/WilliamsonTransforms.jl) package implements this transformation (and its inverse, the Williamson d-transfrom) in all generality. It returns this cumulative distribution function in the form of the corresponding random variable `<:Distributions.ContinuousUnivariateDistribution` from `Distributions.jl`. You may then compute : * The cdf via `Distributions.cdf` * The pdf via `Distributions.pdf` and the logpdf via `Distributions.logpdf` -* Samples from the distribution via `rand(X,n)` +* Samples from the distribution via `rand(X,n)`. ## Archimedean copulas @@ -104,7 +104,7 @@ Let's first define formally archimedean copulas: > >$$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 familiies: +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$. * [`ClaytonGenerator`](@ref): $\phi_{\theta}(t) = \left(1+t\theta\right)^{-\theta^{-1}}$ generates the $\mathrm{Clayton}(\theta)$ copula. * [`GumbelGenerator`](@ref): $\phi_{\theta}(t) = \exp\{-t^{\theta^{-1}}\}$ generates the $\mathrm{Gumbel}(\theta)$ copula. @@ -114,7 +114,7 @@ There are a lot of others implemented in the package, see our [large list of imp Archimedean copulas have a nice decomposition, called the Radial-simplex decomposition: -> **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 +> **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$. diff --git a/docs/src/dependence_measures.md b/docs/src/dependence_measures.md index d53eaff6..a5390d16 100644 --- a/docs/src/dependence_measures.md +++ b/docs/src/dependence_measures.md @@ -1,7 +1,7 @@ -# Mesures of dependency +# Measures of dependency -Although the copula is an object that summarizes completely the dependence structure of any random vector, it is an infinite dimensional object and the interpretation of its properties can be difficult when the dimension gets high. Therefore, the literature has come up with some quantifications of the dependence structure that might be used as univariate summaries, of course imperfect, of certain properties of the copula at hand. +Although the copula is an object that summarizes completely the dependence structure of any random vector, it is an infinite dimensional object and the interpretation of its properties can be difficult when the dimension gets high. Therefore, the literature has come up with some quantification of the dependence structure that might be used as univariate summaries, of course imperfect, of certain properties of the copula at hand. ## Kendall's Tau @@ -12,31 +12,31 @@ Although the copula is an object that summarizes completely the dependence struc Kendall's tau can be obtained through `τ(C::Copula)`. Its value only depends on the dependence structure and not the marginals. !!! warn "Multivariate case" - There exists several multivariate extensions of Kendall's tau. The one implemented here is the one we just defined what ever the dimension $d$, be carefull ad the normalisation might differ from other places in the litterature. + There exists several multivariate extensions of Kendall's tau. The one implemented here is the one we just defined what ever the dimension $d$, be careful as the normalization might differ from other places in the literature. ## Spearman's Rho -> **Definition (Sperman's ρ):** For a copula $C$ with a density $c$, the Sperman's ρ is defined as: +> **Definition (Spearman's ρ):** For a copula $C$ with a density $c$, the Spearman's ρ is defined as: > > $$\rho = 12 \int C(\bm u) d\bm u -3.$$ -Spearman's Rho can be obtained through `ρ(C::Copula)`. Its value only depends on the dependence structure and not the marginals. +Spearman's Rho can be obtained through `ρ(C::Copula)`. Its value only depends on the dependence structure and not the marginals. !!! warn "Multivariate case" - There exists several multivariate extensions of Spearman's rho. The one implemented here is the one we just defined what ever the dimension $d$, be carefull ad the normalisation might differ from other places in the litterature. + There exists several multivariate extensions of Spearman's rho. The one implemented here is the one we just defined what ever the dimension $d$, be careful as the normalization might differ from other places in the literature. !!! note "Specific values of tau and rho" Kendall's $\tau$ and Spearman's $\rho$ have values between -1 and 1, and are -1 in case of complete anticonomotony and 1 in case of comonotony. Moreover, they are 0 in case of independence. This is why we say that they measure the 'strength' of the dependency. !!! tip "More-that-bivariate cases" - 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. Many copula estimators are based on these coefficients, see e.g. [genest2011,fredricks2007,derumigny2017](@cite). + 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. Many copula estimators are based on these coefficients, see e.g., [genest2011,fredricks2007,derumigny2017](@cite). ## Tail dependency -Many people are interested in the tail beahvior of their dependence structures. Tail coefficients summarize this tail behavior. +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 @@ -50,10 +50,10 @@ Many people are interested in the tail beahvior 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. -All these coefficients are useful to quantify the behavior of the dependence structure, both generally and in the extremes, and are therefore widely used in the literature either as verification tools to assess the quality of fits, or even as parameters. Many parametric copulas families have simple surjections, injections, or even bijections between these coefficients and their parametrizations, allowing matching procedures of estimation (a lot like moments matching algorithm for fitting standard random variables). +All these coefficients quantify the behavior of the dependence structure, generally or in the extremes, and are therefore widely used in the literature either as verification tools to assess the quality of fits, or even as parameters. Many parametric copulas families have simple surjections, injections, or even bijections between these coefficients and their parametrization, allowing matching procedures of estimation (a lot like moments matching algorithm for fitting standard random variables). !!! note "Unfinished work" - Unfortunately these coefficients are not yet well-specified in the package and implemented for all depndence structure, there is wtill work to do. + Unfortunately these coefficients are not yet well-specified in the package and implemented for all dependence structure, there is still work to do. ```@bibliography diff --git a/docs/src/dev_roadmap.md b/docs/src/dev_roadmap.md index dcfd4825..caa408a1 100644 --- a/docs/src/dev_roadmap.md +++ b/docs/src/dev_roadmap.md @@ -6,7 +6,7 @@ CurrentModule = Copulas We hope to implement a few more copula models into this package. The next ones to be implemented will probably be: - Extreme values copulas. -- Nested archimedeans (for any generators, with automatic nesting conditions checking). +- 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`) @@ -14,10 +14,10 @@ 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. +- 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 checking of generator d-monotony ? Dunno if it is even possible. +- Automatic checks of generator d-monotony ? Dunno if it is even possible. **Maybe later:** - `NestedArchimedean`, with automatic checking of nesting conditions for generators. diff --git a/docs/src/elliptical/generalities.md b/docs/src/elliptical/generalities.md index cfe923ef..91372f7e 100644 --- a/docs/src/elliptical/generalities.md +++ b/docs/src/elliptical/generalities.md @@ -26,7 +26,7 @@ which is still a function of only the norm of $\bm t$. To fix ideas, for Gaussia ## Elliptical copulas -Elliptical copulas are simply copulas of elliptical distributions. This simplicity of definition is paid for in the expression of the copulas itself: the obtained function has usually no better expression than +Elliptical copulas are simply copulas of elliptical distributions. This simplicity of definition is paid for in the expression of the copulas itself: the obtained function has usually no better expression than: ```math C = F \circ (F_1^{-1},...,F_d^{-1}), ``` diff --git a/docs/src/empirical/available_models.md b/docs/src/empirical/available_models.md index 7e273ced..078a9ebb 100644 --- a/docs/src/empirical/available_models.md +++ b/docs/src/empirical/available_models.md @@ -12,15 +12,15 @@ EmpiricalCopula ## `BernsteinCopula` -!!! note "Not implemeted yet!" - Do not hesitate to come talk on [our github](https://github.com/lrnv/Copulas.jl) ! +!!! note "Not implemented yet!" + Do not hesitate to come talk on [our GitHub](https://github.com/lrnv/Copulas.jl) ! ## `CheckerboardCopula` -!!! note "Not implemeted yet!" - Do not hesitate to come talk on [our github](https://github.com/lrnv/Copulas.jl) ! +!!! note "Not implemented yet!" + Do not hesitate to come talk on [our GitHub](https://github.com/lrnv/Copulas.jl) ! ## `BetaCopula` -!!! note "Not implemeted yet!" - Do not hesitate to come talk on [our github](https://github.com/lrnv/Copulas.jl) ! +!!! note "Not implemented yet!" + Do not hesitate to come talk on [our GitHub](https://github.com/lrnv/Copulas.jl) ! diff --git a/docs/src/empirical/generalities.md b/docs/src/empirical/generalities.md index eea6e686..5039bea6 100644 --- a/docs/src/empirical/generalities.md +++ b/docs/src/empirical/generalities.md @@ -9,7 +9,7 @@ CurrentModule = Copulas Through the statistical process leading to the estimation of copulas, one usually observes the data and information on the marginals scale and not on the copula scale. This discrepancy between the observed information and the modeled distribution must be taken into account. A key concept is that of pseudo-observations. ->**Definition (Pseudo-observations):** If $\bm x \in \mathbb R^{N\times d}$ is an $N$-sample of a $d$-variate real-valued random vector $\bm X$, then the pseudo-observations are the normalized ranks of the marginals of $\bm x$, defined as : +>**Definition (Pseudo-observations):** If $\bm x \in \mathbb R^{N\times d}$ is a $N$-sample of a $d$-variate real-valued random vector $\bm X$, then the pseudo-observations are the normalized ranks of the marginals of $\bm x$, defined as : > > $$\bm u \in \mathbb [0,1]^{N\times d}:\; u_{i,j} = \frac{\mathrm{Rank}(x_{i,j},\,\bm x_{\cdot,j})}{N+1} = \frac{1}{N+1}\sum_{k=1}^N \mathbb 1_{x_{k,j} \le x_{i,j}},$$ > @@ -37,7 +37,7 @@ From these pseudo-observations, an empirical copula is defined as follows: $\hat{C}_N$ then converges (weakly) to $C$, the true copula of the random vector $\bm X$, when the number of observations $N$ goes to infinity. !!! note "The empirical copula is not a true copula" - Despite its name, $\hat{C}_N$ is not a copula since it does not have uniform marginals. Be carrefull. + Despite its name, $\hat{C}_N$ is not a copula since it does not have uniform marginals. Be careful. In the package, this copula is implemented as the `EmpiricalCopula`: @@ -59,15 +59,15 @@ The empirical copula function is not a copula. An easy way to fix this problem i > > $$\sup\limits_{\bm u \in [0,1]^d} \lvert \hat{C}_N(\bm u) - \hat{C}_N^\beta(\bm u) \rvert \le d\left(\sqrt{\frac{\ln n}{n}} + \sqrt{\frac{1}{n}} + \frac{1}{n}\right)$$ -!!! note "Not implemeted yet!" - Do not hesitate to come talk on [our github](https://github.com/lrnv/Copulas.jl) ! +!!! note "Not implemented yet!" + Do not hesitate to come talk on [our GitHub](https://github.com/lrnv/Copulas.jl) ! ## Bernstein Copula Bernstein copula are simply another smoothing of the empirical copula using Bernstein polynomials. -!!! note "Not implemeted yet!" - Do not hesitate to come talk on [our github](https://github.com/lrnv/Copulas.jl) ! +!!! note "Not implemented yet!" + Do not hesitate to come talk on [our GitHub](https://github.com/lrnv/Copulas.jl) ! ## Checkerboard Copulas @@ -86,7 +86,7 @@ Furthermore, for any copula $C$ (or more generally distribution function $F$), w >is a genuine copula as soon as $m_1,...,m_d$ all divide $N$. ->**Property (Consistency of $\hat{C}_{N,\bm m}$ [cuberos2019](@cite):** If all $m_1,..,m_d$ divide $N$, +>**Property (Consistency of $\hat{C}_{N,\bm m}$ [cuberos2019](@cite)):** If all $m_1,..,m_d$ divide $N$, > > $$\sup\limits_{\bm u \in [0,1]^d} \lvert \hat{C}_{N,\bm m}(\bm u) - C(\bm u) \rvert \le \frac{d}{2m} + \mathcal O_{\mathbb P}\left(n^{-\frac{1}{2}}\right).$$ @@ -108,7 +108,7 @@ where we intend $\bm m ]\bm a, \bm b] = ] \bm m \bm a, \bm m \bm b]$ (products b This allows for an easy generalization in the framework of patchwork copulas: -> **Definition (Patchwork copulas [durante2012,durante2013,durante2015](@cite):**) Let $\bm m \in \mathbb N^d$ all divide $N$, and let $\mathcal C = \{C_{\bm i}, \bm i < \bm m\}$ be a given collection of copulas. The distribution function +> **Definition (Patchwork copulas [durante2012,durante2013,durante2015](@cite):**) Let $\bm m \in \mathbb N^d$ all divide $N$, and let $\mathcal C = \{C_{\bm i}, \bm i < \bm m\}$ be a given collection of copulas. The distribution function: > >$$\hat{C}_{N,\bm m, \mathcal C}(\bm x) = \sum_{\bm i < \bm m} \mu_{\hat{C}_N}(B_{\bm i, \bm m}) \mu_{C_{\bm i}}(\bm m B_{\bm i, \bm m}(\bm x))$$ >is a copula. @@ -117,8 +117,8 @@ In fact, replacing $\hat{C}_N$ by any copula in the patchwork construct still yi Convergence results for this kind of copulas can be found in [durante2015](@cite), with a slightly different parametrization. -!!! note "Not implemeted yet!" - Do not hesitate to come talk on [our github](https://github.com/lrnv/Copulas.jl) ! +!!! note "Not implemented yet!" + Do not hesitate to come talk on [our GitHub](https://github.com/lrnv/Copulas.jl) ! ```@bibliography diff --git a/docs/src/exemples/fitting_sklar.md b/docs/src/exemples/fitting_sklar.md index 36b6b341..c5545e88 100644 --- a/docs/src/exemples/fitting_sklar.md +++ b/docs/src/exemples/fitting_sklar.md @@ -1,6 +1,6 @@ # Fitting compound distributions -Through the SklarDist interface, there is the possiiblity to fit directly distributions that are constructed from a copula and some marginals: +Through the `SklarDist` interface, there is the possibility to fit directly distributions that are constructed from a copula and some marginals: ```julia using Copulas @@ -25,6 +25,6 @@ fitted_model = fit(MyD,data) other_fitted_model = fit(SklarDist{EmpiricalCopula,MyMargs},data) ``` -This simple interface leverages indeed the `fit` functon from Distributions.jl. From their documentation, this function is not supposed to use a particular method but to fit "dirt and quick" some distributions. +This simple interface leverages indeed the `fit` function from `Distributions.jl`. From their documentation, this function is not supposed to use a particular method but to fit "dirt and quick" some distributions. -So you have to be carefull : the fit method might not be the same for different copulas or different marginals. For exemples, the archimedean copulas are fitted through an inversion of the kendall tau function, while the gaussian copula is fitted by maximum likelyhood. \ No newline at end of file +So you have to be careful: the fit method might not be the same for different copulas or different marginals. For example, the Archimedean copulas are fitted through an inversion of the Kendall tau function, while the Gaussian copula is fitted by maximum likelihood. \ No newline at end of file diff --git a/docs/src/exemples/turing.md b/docs/src/exemples/turing.md index 48818ecd..198b807b 100644 --- a/docs/src/exemples/turing.md +++ b/docs/src/exemples/turing.md @@ -1,14 +1,14 @@ -# Bayesian inference with Turing.jl +# Bayesian inference with `Turing.jl` -The compatibility with the broader `Distributions.jl`'s API allows a lot of interactions with the broader eco-system. One of the firsts examples that we discovered was the possibility to do bayesian inference of model parameters with [`Turing.jl`](https://turing.ml/). +The compatibility with the broader `Distributions.jl`'s API allows a lot of interactions with the broader ecosystem. One of the firsts examples that we discovered was the possibility to do Bayesian inference of model parameters with [`Turing.jl`](https://turing.ml/). Consider that we have a model with : - A given parametric dependence structure, say a Clayton Copula. - A few given parametric marginals. -Then we can use Turing's `@addlogprob!` to compute the loglikelyhood of our model and maximize it around th eparameters alongside the chain as folows: +Then we can use Turing's `@addlogprob!` to compute the loglikelihood of our model and maximize it around the parameters alongside the chain as follows: ```julia using Copulas @@ -48,9 +48,9 @@ chain = sample(copula(draws), sampler, MCMCThreads(), 100, 4) plot(chain) ``` -This kind of model could be used to do a lot of stuff. here we use it for a parametric estimation of a sampling model, but it could be used for other things such as, e.g., a bayesian regression with an error structure given by a parmaetric copula. +This kind of model could be used to do a lot of stuff. here we use it for a parametric estimation of a sampling model, but it could be used for other things such as, e.g., a Bayesian regression with an error structure given by a parametric copula. -Note that we truncated the θ parameter at -1/3 and not 0 as the ClaytonCopula can handle negative dependence structures. +Note that we truncated the θ parameter at -1/3 and not 0 as the `ClaytonCopula` can handle negative dependence structures. diff --git a/docs/src/getting_started.md b/docs/src/getting_started.md index f6bd7c9f..f0e5d038 100644 --- a/docs/src/getting_started.md +++ b/docs/src/getting_started.md @@ -11,7 +11,7 @@ The interested theoretical reader can take a look at the standard books on the s 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" +!!! info "Constructing random variables in Julia via `Distributions.jl`" Recall that you can construct random variables in Julia by the following code : ```julia @@ -85,21 +85,21 @@ MyDistribution = SklarDist(Π, (X₁,X₂,X₃,X₄)) Copulas are bounded functions -> **Property (Fréchet-Hoeffding bounds [lux2017](@cite):** For all $\bm x \in [0,1]^d$, every copula $C$ satisfies : +> **Property (Fréchet-Hoeffding bounds [lux2017](@cite)):** For all $\bm x \in [0,1]^d$, every copula $C$ satisfies : > >$\langle \bm 1, \bm x - 1 + d^{-1}\rangle_{+} \le C(\bm x) \le \min \bm x,$ >where $y_{+} = \max(0,y)$. -> **Example (Fréchet-Hoeffding bounds [lux2017](@cite):** The function $M : \bm x \mapsto \min\bm x$, called the upper Fréchet-Hoeffding bound, is a copula. The function $W : \bm x \mapsto \langle \bm 1, \bm x - 1 + d^{-1}\rangle_{+}$, called the lower Fréchet-Hoeffding bound, is on the other hand a copula only when $d=2$. +> **Example (Fréchet-Hoeffding bounds [lux2017](@cite)):** The function $M : \bm x \mapsto \min\bm x$, called the upper Fréchet-Hoeffding bound, is a copula. The function $W : \bm x \mapsto \langle \bm 1, \bm x - 1 + d^{-1}\rangle_{+}$, called the lower Fréchet-Hoeffding bound, is on the other hand a copula only when $d=2$. These two copulas can be constructed through [`MCopula(d)`](@ref MGenerator) and [`WCopula(2)`](@ref WGenerator). The upper Fréchet-Hoeffding bound corresponds to the case of comonotone random vector: a random vector $\bm X$ is said to be comonotone, i.e., to have copula $M$, when each of its marginals can be written as a non-decreasing transformation of the same random variable (say with $\mathcal U\left([0,1]\right)$ distribution). This is a simple but important dependence structure. See e.g.,[kaas2002,hua2017](@cite) on this particular copula. -Since copulas are distribution functions, like distribution functions of real-valued random variables and random vectors, there exists classical and useful parametric families of copulas. This is mostly the content of this package, and we refer to the rest of the documentaiton for more details on the models and their implementations. +Since copulas are distribution functions, like distribution functions of real-valued random variables and random vectors, there exists classical and useful parametric families of copulas. This is mostly the content of this package, and we refer to the rest of the documentation for more details on the models and their implementations. ## Fitting copulas and compound distributions. -`Distributions.jl` proposes the `fit` function in their API for random ve tors and random variables. We used it to implement fitting of multivariate models (copulas, of course, but also comppound distributions). It can be used as follows: +`Distributions.jl` proposes the `fit` function in their API for random ve tors and random variables. We used it to implement fitting of multivariate models (copulas, of course, but also compound distributions). It can be used as follows: ```julia diff --git a/docs/src/index.md b/docs/src/index.md index a15e9395..a042dd6b 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -36,7 +36,7 @@ The package is available on Julia's general registry, and can be installed as fo ## Cite this work -Please use the following bibtex if you want to cite this work: +Please use the following BibTeX if you want to cite this work: ```bibtex @software{oskar_laverny_2023_10084669, diff --git a/joss/paper.md b/joss/paper.md index 7302b1cf..e1c60f7b 100644 --- a/joss/paper.md +++ b/joss/paper.md @@ -35,7 +35,7 @@ The Julia package `Copulas.jl` brings most standard copula-related features into The R package `copula` [@r_copula_citation1; @r_copula_citation2; @r_copula_citation3; @r_copula_citation4] is the gold standard when it comes to sampling, estimating, or simply working around dependence structures. However, in other languages, the available tools are not as developped and/or not as recognised. We bridge the gap in the Julian ecosystem with this Julia-native implementation. Due to the very flexible type system in Julia, our code expressiveness and tidyness will increase its usability and maintenability in the long-run. Type-stability allows sampling in arbitrary precision without requiering more code, and Julia's multiple dispatch yields most of the below-described applications. -There are competing packages in Julia, such as [`BivariateCopulas.jl`](https://github.com/AnderGray/BivariateCopulas.jl) [@BivariateCopulas] which only deals with a few models in bivariate settings but has very nice graphs, or [`DatagenCopulaBased.jl`](https://github.com/iitis/DatagenCopulaBased.jl) [@DatagenCopulaBased_1; @DatagenCopulaBased_2; @DatagenCopulaBased_3; @DatagenCopulaBased_4], which only provides sampling and does not have exactly the same models as `Copulas.jl`. While not fully covering out both of these package's functionality (mostly because the three projects chose different copulas to implement), `Copulas.jl` is clearly the must fully featured, and brings, as a key feature, the complience with the broader ecosystem. +There are competing packages in Julia, such as [`BivariateCopulas.jl`](https://github.com/AnderGray/BivariateCopulas.jl) [@BivariateCopulas] which only deals with a few models in bivariate settings but has very nice graphs, or [`DatagenCopulaBased.jl`](https://github.com/iitis/DatagenCopulaBased.jl) [@DatagenCopulaBased_1; @DatagenCopulaBased_2; @DatagenCopulaBased_3; @DatagenCopulaBased_4], which only provides sampling and does not have exactly the same models as `Copulas.jl`. While not fully covering out both of these package's functionality (mostly because the three projects chose different copulas to implement), `Copulas.jl` is clearly the most fully featured, and brings, as a key feature, the compliance with the broader ecosystem. # Examples @@ -61,7 +61,7 @@ D̂ = fit(SklarDist{FrankCopula,Tuple{Gamma,Normal,Binomial}}, x) # Although you'll probbaly get a bad fit ! ``` -The API does not fix the fitting procedure, and only loosely specify it, thus the implemented default might vary on the copula. If you want more control, you may turn to bayesian estimation using `Turing.jl` [@turing]: +The API does not fix the fitting procedure, and only loosely specifies it, thus the implemented default might vary on the copula. If you want more control, you may turn to bayesian estimation using `Turing.jl` [@turing]: ```julia using Turing @@ -88,7 +88,7 @@ end Archimedean copulas are a huge family of copulas that has seen a lot of theoretical work. Among others, you may take a look at [@mcneilMultivariateArchimedeanCopulas2009b]. We use [`WilliamsonTransformations.jl`](https://github.com/lrnv/WilliamsonTransforms.jl/)'s implementation of the Williamson $d$-transfrom to sample from any archimedean copula, including for example the `ClaytonCopula` with negative dependence parameter in any dimension, which is a first to our knowledge. -The API is consisting of the folloiwng functions: +The API consists of the following functions: ```julia ϕ(C::MyArchimedean, t) # Generator @@ -127,7 +127,7 @@ fit(::Type{MyArchimedean},data) # fitting. The package is starting to get used in several other places of the ecosystem. Among others, we noted: -- The package [`GlobalSensitivity.jl`](https://github.com/SciML/GlobalSensitivity.jl) exploit `Copulas.jl` to provide Shapley effects implementation, see [this documentation](https://docs.sciml.ai/GlobalSensitivity/stable/tutorials/shapley/). +- The package [`GlobalSensitivity.jl`](https://github.com/SciML/GlobalSensitivity.jl) exploits `Copulas.jl` to provide Shapley effects implementation, see [this documentation](https://docs.sciml.ai/GlobalSensitivity/stable/tutorials/shapley/). - [`EconomicScenarioGenerators.jl`](https://github.com/JuliaActuary/EconomicScenarioGenerators.jl) uses depndence structures between financial assets.