Merge branch 'main' of https://github.com/Santymax98/Copulas.jl

Santymax98 · Jun 15, 2024 · 8dde1f5 · 8dde1f5
2 parents d142f2b + cec1fab
commit 8dde1f5
Show file tree

Hide file tree

Showing 96 changed files with 4,354 additions and 3,450 deletions.
diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml
@@ -19,31 +19,34 @@ jobs:
       matrix:
         version:
           - '1.6'
-          - 'nightly'
+          - '1'
         os:
           - ubuntu-latest
         arch:
           - x64
           - x86
     steps:
       - uses: actions/checkout@v4
-      - uses: julia-actions/setup-julia@v1
+      - uses: julia-actions/setup-julia@v2
         with:
           version: ${{ matrix.version }}
           arch: ${{ matrix.arch }}
-      - uses: julia-actions/cache@v1
+      - uses: julia-actions/cache@v2
       - uses: julia-actions/julia-buildpkg@v1
       - uses: julia-actions/julia-runtest@v1
       - uses: julia-actions/julia-processcoverage@v1
-      - uses: codecov/codecov-action@v3
+      - uses: codecov/codecov-action@v4
         with:
           files: lcov.info
   docs:
     name: Documentation
     runs-on: ubuntu-latest
+    if: >-
+        !contains(github.event.head_commit.message, '[skip docs]')
+        && github.event_name != 'pull_request'
     steps:
       - uses: actions/checkout@v4
-      - uses: julia-actions/setup-julia@v1
+      - uses: julia-actions/setup-julia@v2
         with:
           version: '1'
       - uses: julia-actions/julia-buildpkg@v1

diff --git a/.github/workflows/draft_paper.yml b/.github/workflows/draft_paper.yml
@@ -1,4 +1,7 @@
-on: [push]
+on:
+  push:
+    paths:
+      - joss/**
 
 jobs:
   paper:
@@ -14,7 +17,7 @@ jobs:
           # This should be the path to the paper within your repo.
           paper-path: joss/paper.md
       - name: Upload
-        uses: actions/upload-artifact@v1
+        uses: actions/upload-artifact@v4
         with:
           name: paper
           # This is the output path where Pandoc will write the compiled

diff --git a/.gitignore b/.gitignore
@@ -3,3 +3,4 @@
 *.jl.mem
 /docs/build/
 Manifest.toml
+.vscode/*
diff --git a/CITATION.bib b/CITATION.bib
@@ -1,10 +1,11 @@
-@software{copulas_jl,
-  author       = {Oskar Laverny},
-  title        = {lrnv/Copulas.jl: v0.1.6},
-  month        = aug,
-  year         = 2022,
-  publisher    = {Zenodo},
-  version      = {v0.1.6},
-  doi          = {10.5281/zenodo.7010221},
-  url          = {https://doi.org/10.5281/zenodo.7010221}
+@article{Laverny2024, 
+    doi = {10.21105/joss.06189}, 
+    url = {https://doi.org/10.21105/joss.06189}, 
+    year = {2024}, 
+    publisher = {The Open Journal}, 
+    volume = {9}, 
+    number = {94}, 
+    pages = {6189}, 
+    author = {Oskar Laverny and Santiago Jimenez}, 
+    title = {Copulas.jl: A fully Distributions.jl-compliant copula package}, journal = {Journal of Open Source Software}
 }
diff --git a/CITATION.cff b/CITATION.cff
@@ -0,0 +1,36 @@
+cff-version: "1.2.0"
+authors:
+- family-names: Laverny
+  given-names: Oskar
+  orcid: "https://orcid.org/0000-0002-7508-999X"
+- family-names: Jimenez
+  given-names: Santiago
+  orcid: "https://orcid.org/0000-0002-8198-3656"
+contact:
+- family-names: Laverny
+  given-names: Oskar
+  orcid: "https://orcid.org/0000-0002-7508-999X"
+doi: 10.5281/zenodo.6652672
+message: If you use this software, please cite our article in the
+  Journal of Open Source Software.
+preferred-citation:
+  authors:
+  - family-names: Laverny
+    given-names: Oskar
+    orcid: "https://orcid.org/0000-0002-7508-999X"
+  - family-names: Jimenez
+    given-names: Santiago
+    orcid: "https://orcid.org/0000-0002-8198-3656"
+  date-published: 2024-02-29
+  doi: 10.21105/joss.06189
+  issn: 2475-9066
+  issue: 94
+  journal: Journal of Open Source Software
+  publisher:
+    name: Open Journals
+  start: 6189
+  title: "Copulas.jl: A fully Distributions.jl-compliant copula package"
+  type: article
+  url: "https://joss.theoj.org/papers/10.21105/joss.06189"
+  volume: 9
+title: "Copulas.jl: A fully Distributions.jl-compliant copula package"
diff --git a/Project.toml b/Project.toml
@@ -1,16 +1,19 @@
 name = "Copulas"
 uuid = "ae264745-0b69-425e-9d9d-cf662c5eec93"
 authors = ["Oskar Laverny"]
-version = "0.1.18"
+version = "0.1.23"
 
 [deps]
 Combinatorics = "861a8166-3701-5b0c-9a16-15d98fcdc6aa"
 Cubature = "667455a9-e2ce-5579-9412-b964f529a492"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210"
-GSL = "92c85e6c-cbff-5e0c-80f7-495c94daaecd"
+InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 LogExpFunctions = "2ab3a3ac-af41-5b50-aa03-7779005ae688"
 MvNormalCDF = "37188c8d-bc69-4638-b057-733e744175ec"
+PrecompileTools = "aea7be01-6a6a-4083-8856-8a6e6704d82a"
+QuadGK = "1fd47b50-473d-5c70-9696-f719f8f3bcdc"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 Roots = "f2b01f46-fcfa-551c-844a-d8ac1e96c665"
 SpecialFunctions = "276daf66-3868-5448-9aa4-cd146d93841b"
@@ -24,18 +27,19 @@ Combinatorics = "1"
 Cubature = "1.5"
 Distributions = "0.25"
 ForwardDiff = "0.10"
-GSL = "1"
 HypothesisTests = "v0.11"
 InteractiveUtils = "1.6"
 LinearAlgebra = "1.6"
 LogExpFunctions = "0.3"
 MvNormalCDF = "0.2, 0.3"
+PrecompileTools = "1"
+QuadGK = "2"
 Random = "1.6"
 Roots = "1, 2"
 SpecialFunctions = "2"
 StableRNGs = "1"
 StatsBase = "0.33, 0.34"
-TaylorSeries = "0.12, 0.13, 0.14, 0.15"
+TaylorSeries = "0.12, 0.13, 0.14, 0.15, 0.16, 0.17"
 Test = "1.6"
 TestItemRunner = "v0.2"
 WilliamsonTransforms = "0.1"

diff --git a/README.md b/README.md
@@ -1,20 +1,19 @@
-<h1 align=center>Copulas.jl</h1>
+<h1 align=center><img src="https://cdn.rawgit.com/lrnv/Copulas.jl/main/docs/src/assets/logo.svg" width="30px" height="30px"/> Copulas.jl</h1>
 <p align=center><i>A fully `Distributions.jl`-compliant copula package</i></p>
 
 <p align=center>
     <a href="https://lrnv.github.io/Copulas.jl/stable"><img src="https://img.shields.io/badge/docs-stable-blue.svg" alt="Stable" /></a>
     <a href="https://lrnv.github.io/Copulas.jl/dev"><img src="https://img.shields.io/badge/docs-dev-blue.svg" alt="Dev" /></a>
+    <a href="https://joss.theoj.org/papers/98fa5d88d0d8f27038af2da00f210d45"><img src="https://joss.theoj.org/papers/98fa5d88d0d8f27038af2da00f210d45/status.svg"></a>
+<!--     <a href="https://zenodo.org/badge/latestdoi/456485213"><img src="https://zenodo.org/badge/456485213.svg" alt="DOI" /></a> -->
 <br />
     <a href="https://www.repostatus.org/#active"><img src="https://www.repostatus.org/badges/latest/active.svg" alt="Project Status: Active – The project has reached a stable, usable state and is being actively developed." /></a>
      <a href="https://github.com/lrnv/Copulas.jl/actions/workflows/CI.yml?query=branch%3Amain"><img src="https://github.com/lrnv/Copulas.jl/actions/workflows/CI.yml/badge.svg?branch=main" alt="Build Status" /></a>
-<br />
      <a href="https://codecov.io/gh/lrnv/Copulas.jl"><img src="https://codecov.io/gh/lrnv/Copulas.jl/branch/main/graph/badge.svg"/></a>
      <a href="https://github.com/JuliaTesting/Aqua.jl"><img src="https://raw.githubusercontent.com/JuliaTesting/Aqua.jl/master/badge.svg" alt="Aqua QA" /></a>
     <!-- <a href="https://benchmark.tansongchen.com/TaylorDiff.jl"><img src="https://img.shields.io/buildkite/2c801728055463e7c8baeeb3cc187b964587235a49b3ed39ab/main.svg?label=benchmark" alt="Benchmark Status" /></a> -->
 <br />
     <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT" /></a>
-    <a href="https://zenodo.org/badge/latestdoi/456485213"><img src="https://zenodo.org/badge/456485213.svg" alt="DOI" /></a>
-<br />
     <a href="https://github.com/SciML/ColPrac"><img src="https://img.shields.io/badge/contributor's%20guide-ColPrac-blueviolet" alt="ColPrac: Contributor's Guide on Collaborative Practices for Community Packages" /></a>
     <a href="https://github.com/invenia/BlueStyle"><img src="https://img.shields.io/badge/code%20style-blue-4495d1.svg" alt="Code Style: Blue" /></a>
 </p>
@@ -23,28 +22,27 @@
   <a href="https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=563952901&machine=standardLinux32gb&devcontainer_path=.devcontainer%2Fdevcontainer.json&location=EastUshttps://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=563952901&machine=standardLinux32gb&devcontainer_path=.devcontainer%2Fdevcontainer.json&location=EastUs"><img src="https://github.com/codespaces/badge.svg" alt="Open in GitHub Codespaces" /></a>
 </p> -->
 
-`Copulas.jl` brings most standard [copula](https://en.wikipedia.org/wiki/Copula_(probability_theory)) features into native Julia: random number generation, pdf and cdf, fitting, copula-based multivariate distributions through Sklar's theorem, etc. Since copulas are distribution functions, we fully comply with the [`Distributions.jl`](https://github.com/JuliaStats/Distributions.jl) API. This complience allows interoperability with other packages based on this API such as, e.g., [`Turing.jl`](https://github.com/TuringLang/Turing.jl).
+`Copulas.jl` brings most standard [copula](https://en.wikipedia.org/wiki/Copula_(probability_theory)) features into native Julia: random number generation, pdf and cdf, fitting, copula-based multivariate distributions through Sklar's theorem, etc. Since copulas are distribution functions, we fully comply with the [`Distributions.jl`](https://github.com/JuliaStats/Distributions.jl) API. This allows interoperability with the broader ecosystem, based on this API, such as, e.g., [`Turing.jl`](https://github.com/TuringLang/Turing.jl).
 
-Usually, people that use and work with copulas turn to R, because of the amazing `R` package [`copula`](https://cran.r-project.org/web/packages/copula/copula.pdf).
-While it is still well maintained and regularly updated, the `R` poackage `copula` is a mixture of obscure, heavily optimized `C` code and more standard `R` cde, which makes it a complicated code base for readability, extensibility, reliability and maintenance.
+Usually, people that use and work with copulas turn to R, because of the amazing package [`R::copula`](https://cran.r-project.org/web/packages/copula/copula.pdf). While well-maintained and regularly updated, `R::copula` is a mixture of obscure, heavily optimized `C` code and more standard `R` code, which makes it a complicated code base for readability, extensibility, reliability and maintenance.
 
-This is an attempt to provide a very light, fast, reliable and maintainable copula implementation in native Julia. Among others, one of the notable benefits of such a native implementatioon is the floating point type agnosticity, i.e. compatibility with `BigFloat`, [`DoubleFloats`](https://github.com/JuliaMath/DoubleFloats.jl), [`MultiFloats`](https://github.com/dzhang314/MultiFloats.jl) and other kind of numbers.
+This is an attempt to provide a very light, fast, reliable and maintainable copula implementation in native Julia. One of the notable benefits of such a native implementation (among others) is the floating point type agnosticity, i.e. compatibility with `BigFloat`, [`DoubleFloats`](https://github.com/JuliaMath/DoubleFloats.jl), [`MultiFloats`](https://github.com/dzhang314/MultiFloats.jl), etc.
 
 The package revolves around two main types: 
 
 - `Copula`, an abstract mother type for all the copulas in the package
 - `SklarDist`, a distribution type that allows construction of a multivariate distribution by specifying the copula and the marginals through [Sklar's theorem](https://en.wikipedia.org/wiki/Copula_(probability_theory)#Sklar's_theorem). 
 
-**Warning: This is fairly untested and experimental work and the API might change without notice.**
+**Warning: This is fairly experimental work, use with caution.**
+
+## Getting started
 
-## Instalation
+The package is registered in Julia's General registry so you may simply install the package by running : 
 
 ```julia
 ] add Copulas
 ```
 
-## Usage 
-
 The API contains random number generation, cdf and pdf evaluation, and the `fit` function from `Distributions.jl`. A typical use case might look like this: 
 
 ```julia
@@ -55,78 +53,53 @@ X₃ = LogNormal(0,1)
 C = ClaytonCopula(3,0.7) # A 3-variate Clayton Copula with θ = 0.7
 D = SklarDist(C,(X₁,X₂,X₃)) # The final distribution
 
-# This generates a (3,1000)-sized dataset from the multivariate distribution D
-simu = rand(D,1000)
+simu = rand(D,1000) # Generate a dataset
 
-# While the following estimates the parameters of the model from a dataset: 
-D̂ = fit(SklarDist{FrankCopula,Tuple{Gamma,Normal,LogNormal}}, simu)
-# Increase the number of observations to get a beter fit (or not?)  
+# You may estimate a copula using the `fit` function:
+D̂ = fit(SklarDist{ClaytonCopula,Tuple{Gamma,Normal,LogNormal}}, simu)
 ```
 
-Available copula families are:
-- `EllipticalCopulas`: `GaussianCopula` and `TCopula`
-- `ArchimedeanCopula`: `WilliamsonCopula` (for any generator), but also `ClaytonCopula`,`FrankCopula`, `AMHCopula`, `JoeCopula`, `GumbelCopula`, supporting the full ranges in every dimensions (e.g. ClaytonCopula can be sampled with negative dependence in any dimension, not just d=2). 
-- `WCopula`, `IndependentCopula` and `MCopula`, which are [Fréchet-Hoeffding bounds](https://en.wikipedia.org/wiki/Copula_(probability_theory)#Fr%C3%A9chet%E2%80%93Hoeffding_copula_bounds),
-- `PlackettCopula`, see ref?
-- `EmpiricalCopula` to follow closely a given dataset.
-
-The next ones to be implemented will probably be: 
-- Extreme values copulas. 
-- Nested archimedeans (for any generators, with automatic nesting conditions checking). 
-- Bernstein copula and more general Beta copula as smoothing of the Empirical copula. 
-- `CheckerboardCopula` (and more generally `PatchworkCopula`)
+The list of availiable copula models is *very* large, check it out on our [documentation](https://lrnv.github.io/Copulas.jl/stable) ! 
 
-Adding a new `ArchimedeanCopula` is very easy. The `Clayton` implementation is as short as: 
+The general implementation philosophy is for the code to follow the mathematical boundaries of the implemented concepts. For example, this is the only implementation we know (in any language) that allows for **all** Archimedean copulas to be sampled: we use the Williamson transformation for non-standard generators, including user-provided black-box ones.
 
-```julia
-struct ClaytonCopula{d,T} <: Copulas.ArchimedeanCopula{d}
-    θ::T
-end
-ClaytonCopula(d,θ)            = ClaytonCopula{d,typeof(θ)}(θ)     # Constructor
-ϕ(C::ClaytonCopula, t)        = (1+sign(C.θ)*t)^(-1/C.θ)          # Generator
-ϕ⁻¹(C::ClaytonCopula,t)       = sign(C.θ)*(t^(-C.θ)-1)            # Inverse Generator
-τ(C::ClaytonCopula)           = C.θ/(C.θ+2)                       # θ -> τ
-τ⁻¹(::Type{ClaytonCopula},τ)  = 2τ/(1-τ)                          # τ -> θ
-williamson_dist(C::ClaytonCopula{d,T}) where {d,T} = WilliamsonFromFrailty(Distributions.Gamma(1/C.θ,1),d) # Radial distribution
-```
-The Archimedean API is modular: 
-
-- To sample an archimedean, only `ϕ` is required. Indeed, the `williamson_dist` has a generic fallback that uses [WilliamsonTransforms.jl](https://www.github.com/lrnv/WilliamsonTransforms.jl) for any generator. Note however that providing the `williamson_dist` yourself if you know it will allow sampling to be an order of magnitude faster.
-- To evaluate the cdf and (log-)density in any dimension, only `ϕ` and `ϕ⁻¹` are needed.
-- Currently, to fit the copula `τ⁻¹` is needed as we use the inverse tau moment method. But we plan on also implementing inverse rho and MLE (density needed). 
-- Note that the generator `ϕ` follows the convention `ϕ(0)=1`, while others (e.g., https://en.wikipedia.org/wiki/Copula_(probability_theory)#Archimedean_copulas) use `ϕ⁻¹` as the generator.
+## Feature comparison
 
-Please take a look at the [documentation](https://lrnv.github.io/Copulas.jl/dev) for more details. 
 
-## Dev Roadmap
+There are competing packages in Julia, such as [`BivariateCopulas.jl`](https://github.com/AnderGray/BivariateCopulas.jl) which only deals with a few models in bivariate settings but has very nice graphs, or [`DatagenCopulaBased.jl`](https://github.com/iitis/DatagenCopulaBased.jl), 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 implementation paths), `Copulas.jl` brings, as a key feature, the compliance with the broader ecosystem. The following table provides a feature comparison between the three: 
 
-**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 generarator
-- [ ] Automatic checking of generator d-monotonicity ? Dunno if it is even possible. 
+|  | `Copulas.jl` | `DatagenCopulaBased.jl` | `BivariateCopulas.jl` |
+|----------------|--------------|-------------------------|-----------------------|
+| `Distributions.jl`'s API | ✔️ | ❌ | ✔️ |
+| Fitting                  | ✔️ | ❌ | ❌ |
+| Plotting                 | ❌ | ❌ | ✔️ |
+| Available copulas        |     |     |    |
+| - Classic Bivariate      | ✔️ | ✔️ | ✔️ |
+| - Classic Multivariate   | ✔️ | ✔️ | ❌ |
+| - Archimedeans           | ✔️ (All of them) | ⚠️ Selected ones | ⚠️Selected ones |
+| - Obscure Bivariate      | ✔️ | ❌ | ❌ |
+| - Archimedean Chains     | ❌ | ✔️ | ❌ |
 
-**Maybe later:**
-- [ ] `NestedArchimedean`, with automatic checking of nesting conditions for generators. 
-- [ ] `Vines`?
-- [ ] `Archimax` ?
-- [ ] `BernsteinCopula` and `BetaCopula` could also be implemented. 
-- [ ] `PatchworkCopula` and `CheckerboardCopula`: could be nice things to have :)
-- [ ] Goodness of fits tests ?
+Since our primary target is maintainability and readability of the implementation, we did not consider the efficiency and the performance of the code yet. Proper benchmarks will come in the near future. 
 
 ## Contributions are welcome
 
-If you want to contribute to the package, found a bug in it or simply want to chat, do not hesitate to open an issue on this repo. 
-
+If you want to contribute to the package, ask a question, found a bug or simply want to chat, do not hesitate to open an issue on this repo. General guidelines on collaborative practices (colprac) are available at https://github.com/SciML/ColPrac.
 ## Citation 
 
+Do not hesitate to star this repository to show support. If you use this package in your researches, please cite it with the following bibtex code:
+
 ```bibtex
-@software{oskar_laverny_2023_10084669,
-  author       = {Oskar Laverny},
-  title        = {Copulas.jl: A fully `Distributions.jl`-compliant copula package},
-  year         = 2022+,
-  doi          = {10.5281/zenodo.6652672},
-  url          = {https://doi.org/10.5281/zenodo.6652672}
+@article{Laverny2024,
+    author = {Oskar Laverny and Santiago Jimenez}, 
+    title = {Copulas.jl: A fully Distributions.jl-compliant copula package},
+    journal = {Journal of Open Source Software},
+    doi = {10.21105/joss.06189}, 
+    url = {https://doi.org/10.21105/joss.06189}, 
+    year = {2024}, 
+    publisher = {The Open Journal}, 
+    volume = {9}, 
+    number = {94}, 
+    pages = {6189}
 }
 ```