Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
145 commits
Select commit Hold shift + click to select a range
f4670ae
first shot for add vcov
Santymax98 Oct 2, 2025
dd51a7c
first shot
lrnv Oct 3, 2025
62bf463
clear up archimedean too
lrnv Oct 3, 2025
2f419cd
clear up archimedans.
lrnv Oct 3, 2025
e857df6
refactor -- first pass
lrnv Oct 3, 2025
3aef744
simplified entropy and lower gaussian burden
lrnv Oct 3, 2025
3ae5c59
clear out gaussian and elliptical
lrnv Oct 3, 2025
ad339fe
add godambe_pairwise
lrnv Oct 3, 2025
62b4a5e
clear up EVC
lrnv Oct 3, 2025
c56e565
Refactor and simplify the code
lrnv Oct 3, 2025
1f38f66
clear out global diff
lrnv Oct 3, 2025
985ab30
debugging...
lrnv Oct 3, 2025
1b7c079
working!
lrnv Oct 4, 2025
c9b734a
enhance show function
lrnv Oct 4, 2025
c9c3ac9
first shot for add vcov
Santymax98 Oct 4, 2025
9aef2c7
first shot
lrnv Oct 4, 2025
375819d
clear up archimedean too
lrnv Oct 4, 2025
a3cd77c
clear up archimedans.
lrnv Oct 4, 2025
d4f071f
refactor -- first pass
lrnv Oct 4, 2025
a440c85
simplified entropy and lower gaussian burden
lrnv Oct 4, 2025
76d6bb0
clear out gaussian and elliptical
lrnv Oct 4, 2025
de38b3b
add godambe_pairwise
lrnv Oct 4, 2025
a7fc773
clear up EVC
lrnv Oct 4, 2025
e4cf3d8
Refactor and simplify the code
lrnv Oct 4, 2025
eb0a251
clear out global diff
lrnv Oct 4, 2025
af6cee4
debugging...
lrnv Oct 4, 2025
c08765d
working!
lrnv Oct 4, 2025
6879586
enhance show function
lrnv Oct 4, 2025
b5311e8
Merge branch 'add_vcov_clean' of https://github.com/santymax98/copula…
lrnv Oct 4, 2025
3cae77b
up
lrnv Oct 4, 2025
f544ae4
one typo
lrnv Oct 4, 2025
5689490
correct docs
lrnv Oct 4, 2025
923a956
typo...
lrnv Oct 4, 2025
0eb68ce
fix archimax typign issue
lrnv Oct 4, 2025
fa9fbde
add any test for vcov and inference...
Santymax98 Oct 5, 2025
482e8f6
adding test and new functions StatsBase
Santymax98 Oct 5, 2025
2aad887
up
Santymax98 Oct 5, 2025
e313efe
Comment out filter in runtests.jl
lrnv Oct 5, 2025
979752b
Fix Gaussian & Survival
lrnv Oct 5, 2025
cd18cf1
Merge branch 'add_vcov_clean' of https://github.com/santymax98/copula…
lrnv Oct 5, 2025
9e2b6be
typo
lrnv Oct 5, 2025
e75469e
Disable vcov for TCopula
lrnv Oct 5, 2025
dbfb071
remove interactiveutils cause unused ?
lrnv Oct 5, 2025
4980365
remove flay test
lrnv Oct 5, 2025
51ce740
fixing FGMCOPULA
Santymax98 Oct 5, 2025
35cf2a5
add a dimension parameter to _availiale_fitting_methods
lrnv Oct 5, 2025
9c931be
Specialize fitting methods for FGM
lrnv Oct 5, 2025
a381ce5
Disable :irho for Gumbel and FGM mle vcov
lrnv Oct 5, 2025
f6770f0
Merge branch 'add_vcov_clean' of https://github.com/santymax98/copula…
lrnv Oct 5, 2025
2e45b1a
restore previous constructor.
lrnv Oct 5, 2025
41b458d
typo...
lrnv Oct 5, 2025
b7bba4a
fu...
lrnv Oct 6, 2025
3e8c79c
fix FGM
lrnv Oct 6, 2025
aeff408
Remove soem Float64 enforcements.
lrnv Oct 6, 2025
0978647
Fix EV output of paramters
lrnv Oct 6, 2025
c39c3f6
fix vcov retrieving paramters
lrnv Oct 6, 2025
6e34de7
fixed mle evd
Santymax98 Oct 6, 2025
8e273e1
Robust hessian _vcov
Santymax98 Oct 6, 2025
629abe9
delete simlink
lrnv Oct 6, 2025
c636a0c
frank is very slow
Santymax98 Oct 6, 2025
bcf7276
Merge branch 'add_vcov_clean' of https://github.com/santymax98/copula…
lrnv Oct 6, 2025
4c9ea7d
fix a few things around
lrnv Oct 6, 2025
d1ac9e8
trying vcov with bootstrap
Santymax98 Oct 6, 2025
3316af8
try to implement kth derivatives for BBx
Santymax98 Oct 7, 2025
cc4ee21
relaxing tolerance
Santymax98 Oct 7, 2025
1fd1179
stable bivariate bbx for archimax
Santymax98 Oct 7, 2025
0afbb1e
Revise introduction in documentation for Copulas (#312)
lrnv Oct 7, 2025
1bdaf47
tolerance fixing...
Santymax98 Oct 7, 2025
9f35da2
[Internals] Back to TaylorSeries.jl (#313)
lrnv Oct 7, 2025
62f2f9f
restore removed changes sorry
lrnv Oct 7, 2025
31812d0
first shot for add vcov
Santymax98 Oct 7, 2025
8c9c19b
first shot
lrnv Oct 7, 2025
caf0181
clear up archimedean too
lrnv Oct 7, 2025
b374b8c
clear up archimedans.
lrnv Oct 7, 2025
c7779aa
refactor -- first pass
lrnv Oct 7, 2025
e0c9148
simplified entropy and lower gaussian burden
lrnv Oct 7, 2025
baedbad
clear out gaussian and elliptical
lrnv Oct 7, 2025
78382c9
add godambe_pairwise
lrnv Oct 7, 2025
820c563
clear up EVC
lrnv Oct 7, 2025
9b64698
Refactor and simplify the code
lrnv Oct 7, 2025
8c9ce26
clear out global diff
lrnv Oct 7, 2025
6ad2485
debugging...
lrnv Oct 7, 2025
ca0355a
working!
lrnv Oct 7, 2025
7850341
enhance show function
lrnv Oct 7, 2025
9b2f625
first shot for add vcov
Santymax98 Oct 7, 2025
495c79b
first shot
lrnv Oct 7, 2025
2971b7f
clear up archimedean too
lrnv Oct 7, 2025
00c2894
clear up archimedans.
lrnv Oct 7, 2025
0a1ef68
refactor -- first pass
lrnv Oct 7, 2025
44e129e
simplified entropy and lower gaussian burden
lrnv Oct 7, 2025
0ae36be
clear out gaussian and elliptical
lrnv Oct 7, 2025
e2ef403
add godambe_pairwise
lrnv Oct 7, 2025
7fbca10
clear up EVC
lrnv Oct 7, 2025
8b6b164
Refactor and simplify the code
lrnv Oct 7, 2025
2a546f2
clear out global diff
lrnv Oct 7, 2025
7fbff09
debugging...
lrnv Oct 7, 2025
9cbac6b
working!
lrnv Oct 7, 2025
1c1aac6
enhance show function
lrnv Oct 7, 2025
6fc677b
up
lrnv Oct 7, 2025
4dd2413
one typo
lrnv Oct 7, 2025
0aca73d
correct docs
lrnv Oct 7, 2025
2c5b7bd
typo...
lrnv Oct 7, 2025
f70c829
fix archimax typign issue
lrnv Oct 7, 2025
5ac7e88
Fix Gaussian & Survival
lrnv Oct 7, 2025
0678445
add any test for vcov and inference...
Santymax98 Oct 7, 2025
ace3bc7
adding test and new functions StatsBase
Santymax98 Oct 7, 2025
683f1c0
up
Santymax98 Oct 7, 2025
fafabe0
Comment out filter in runtests.jl
lrnv Oct 7, 2025
cbcb78c
typo
lrnv Oct 7, 2025
a1d5a90
Disable vcov for TCopula
lrnv Oct 7, 2025
1880fb6
remove interactiveutils cause unused ?
lrnv Oct 7, 2025
0ae8c98
remove flay test
lrnv Oct 7, 2025
870a68a
add a dimension parameter to _availiale_fitting_methods
lrnv Oct 7, 2025
b9e173e
Specialize fitting methods for FGM
lrnv Oct 7, 2025
14659cb
Disable :irho for Gumbel and FGM mle vcov
lrnv Oct 7, 2025
4172707
fixing FGMCOPULA
Santymax98 Oct 7, 2025
cec0660
restore previous constructor.
lrnv Oct 7, 2025
144ebf4
typo...
lrnv Oct 7, 2025
d50b0aa
fu...
lrnv Oct 7, 2025
1aed2b4
fix FGM
lrnv Oct 7, 2025
95a89ca
Remove soem Float64 enforcements.
lrnv Oct 7, 2025
bc74d9e
Fix EV output of paramters
lrnv Oct 7, 2025
7f05449
fix vcov retrieving paramters
lrnv Oct 7, 2025
b9ddb58
delete simlink
lrnv Oct 7, 2025
1ac52f9
fixed mle evd
Santymax98 Oct 7, 2025
95ec113
Robust hessian _vcov
Santymax98 Oct 7, 2025
d283ed8
frank is very slow
Santymax98 Oct 7, 2025
45d5df8
fix a few things around
lrnv Oct 7, 2025
2c882fa
trying vcov with bootstrap
Santymax98 Oct 7, 2025
d5ebb35
try to implement kth derivatives for BBx
Santymax98 Oct 7, 2025
47ae6d7
relaxing tolerance
Santymax98 Oct 7, 2025
a103a75
stable bivariate bbx for archimax
Santymax98 Oct 7, 2025
48a15d2
tolerance fixing...
Santymax98 Oct 7, 2025
7a81250
restore removed changes sorry
lrnv Oct 7, 2025
c11cbe2
Merge branch 'add_vcov_clean' of https://github.com/santymax98/copula…
lrnv Oct 7, 2025
95d40c5
fix a few Val{} still there
lrnv Oct 7, 2025
236e131
small changes
lrnv Oct 7, 2025
7965bfc
one first merging error
lrnv Oct 7, 2025
d1d13d0
Try to disable upper generator for BBs to see if it works.
lrnv Oct 7, 2025
fcb4c7e
typo
lrnv Oct 7, 2025
d617ae2
test everything now
lrnv Oct 7, 2025
0d27a2a
no vcov for tEV
lrnv Oct 7, 2025
3d28092
new dependence metrics tests
lrnv Oct 8, 2025
2844def
back to previous tests
lrnv Oct 8, 2025
fc12c12
avoid inverting zeros in sklardist
lrnv Oct 8, 2025
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion Copulas.jl
Submodule Copulas.jl deleted from 7c61c1
5 changes: 2 additions & 3 deletions Project.toml
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,6 @@ Combinatorics = "861a8166-3701-5b0c-9a16-15d98fcdc6aa"
Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210"
HCubature = "19dc6840-f33b-545b-b366-655c7e3ffd49"
InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
LambertW = "984bce1d-4616-540c-a9ee-88d1112d94c9"
LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
LogExpFunctions = "2ab3a3ac-af41-5b50-aa03-7779005ae688"
Expand All @@ -24,7 +23,7 @@ SpecialFunctions = "276daf66-3868-5448-9aa4-cd146d93841b"
Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
StatsFuns = "4c63d2b9-4356-54db-8cca-17b64c39e42c"
WilliamsonTransforms = "48feb556-9bdd-43a2-8e10-96100ec25e22"
TaylorSeries = "6aa5eb33-94cf-58f4-a9d0-e4b2c4fc25ea"

[weakdeps]
Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
Expand Down Expand Up @@ -59,9 +58,9 @@ StableRNGs = "1"
Statistics = "1"
StatsBase = "0.33, 0.34"
StatsFuns = "0.9, 1.3"
TaylorSeries = "0.20"
Test = "1"
TestItemRunner = "1"
WilliamsonTransforms = "0.2"
julia = "1"

[extras]
Expand Down
1 change: 0 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,6 @@
<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>
<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://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>
Expand Down
12 changes: 6 additions & 6 deletions docs/src/bestiary/archimedean.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,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$. See [williamson1955multiply, mcneil2009](@cite) for the literature.

!!! info "`max_monotony` of Williamson generators"
The $d$-transform of a positive random variable is $d$-monotone but not $k$-monotone for any $k > d$. Its max monotony is therefore $d$. This has a few implications, one of the biggest is that the $d$-variate Archimedean copula that corresponds has no density.
Expand All @@ -115,15 +115,15 @@ The Williamson d-transform is a bijective transformation[^1] from the set of pos

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 ϕ. 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 :

```math
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 :
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)`.
Expand Down Expand Up @@ -184,14 +184,14 @@ This is why `williamson_dist(G::Generator,d)` is such an important function in t

```@example
using Copulas: williamson_dist, FrankGenerator
williamson_dist(FrankGenerator(7), Val{3}())
williamson_dist(FrankGenerator(7), 3)
```

For the Frank Copula, as for many classic copulas, the distribution used is known. We pull some of them from `Distributions.jl` but implement a few more, as this Logarithmic one. Another useful example are negatively-dependent Clayton copulas:

```@example
using Copulas: williamson_dist, ClaytonGenerator
williamson_dist(ClaytonGenerator(-0.2), Val{3}())
williamson_dist(ClaytonGenerator(-0.2), 3)
```

for which the corresponding distribution is known but has no particular name, thus we implemented it under the `ClaytonWilliamsonDistribution` name.
Expand All @@ -209,7 +209,7 @@ for which the corresponding distribution is known but has no particular name, th
We use this fraily approach for several generators, since sometimes it is faster, including e.g. the Clayton one with positive dependence:
```@example
using Copulas: williamson_dist, ClaytonGenerator
williamson_dist(ClaytonGenerator(10), Val{3}())
williamson_dist(ClaytonGenerator(10), 3)
```


Expand Down
2 changes: 1 addition & 1 deletion docs/src/bestiary/empirical.md
Original file line number Diff line number Diff line change
Expand Up @@ -216,7 +216,7 @@ Usage:

- Build from data `u::d×n` (raw or pseudos): `Ĝ = EmpiricalGenerator(u; pseudo_values=true)`
- Use directly in an Archimedean copula: `Ĉ = ArchimedeanCopula(d, Ĝ)`
- Access the fitted radial law: `R̂ = williamson_dist(Ĝ, Val{d}())`
- Access the fitted radial law: `R̂ = williamson_dist(Ĝ, d)`

```@docs; canonical=false
EmpiricalGenerator
Expand Down
10 changes: 5 additions & 5 deletions docs/src/examples/archimedean_radial_estimation.md
Original file line number Diff line number Diff line change
Expand Up @@ -205,7 +205,7 @@ R = Dirac(1.0)
d, n = 3, 1000
u = spl_cop(R, d, n)
Ghat = EmpiricalGenerator(u)
Rhat = Copulas.williamson_dist(Ghat, Val{d}())
Rhat = Copulas.williamson_dist(Ghat, d)
diagnose_plots(u, Rhat; R=R)
```

Expand All @@ -216,7 +216,7 @@ R = DiscreteNonParametric([1.0, 4.0, 8.0], fill(1/3, 3))
d, n = 2, 1000
u = spl_cop(R, d, n)
Ghat = EmpiricalGenerator(u)
Rhat = Copulas.williamson_dist(Ghat, Val{d}())
Rhat = Copulas.williamson_dist(Ghat, d)
diagnose_plots(u, Rhat; R=R)
```

Expand All @@ -227,7 +227,7 @@ R = DiscreteNonParametric([1.0, 4.0, 8.0], fill(1/3, 3))
d, n = 3, 1000
u = spl_cop(R, d, n)
Ghat = EmpiricalGenerator(u)
Rhat = Copulas.williamson_dist(Ghat, Val{d}())
Rhat = Copulas.williamson_dist(Ghat, d)
diagnose_plots(u, Rhat; R=R)
```

Expand All @@ -238,7 +238,7 @@ R = LogNormal(1, 3)
d, n = 10, 1000
u = spl_cop(R, d, n)
Ghat = EmpiricalGenerator(u)
Rhat = Copulas.williamson_dist(Ghat, Val{d}())
Rhat = Copulas.williamson_dist(Ghat, d)
diagnose_plots(u, Rhat; R=R, logged=true)
```

Expand All @@ -249,7 +249,7 @@ R = Pareto(1.0, 1/2)
d, n = 10, 1000
u = spl_cop(R, d, n)
Ghat = EmpiricalGenerator(u)
Rhat = Copulas.williamson_dist(Ghat, Val{d}())
Rhat = Copulas.williamson_dist(Ghat, d)
diagnose_plots(u, Rhat; R=R, logged=true)
```

Expand Down
31 changes: 6 additions & 25 deletions docs/src/manual/fitting_interface.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ plot(Ĉ)
### Full Model (with metadata)

```@example fitting_interface
M = fit(CopulaModel, GumbelCopula, U; method=:default, summaries=true)
M = fit(CopulaModel, GumbelCopula, U; method=:default)
M
```

Expand All @@ -48,15 +48,15 @@ Returns a `CopulaModel` with:
* `result` (the fitted copula), `n`, `ll` (log-likelihood),
* `method`, `converged`, `iterations`, `elapsed_sec`,
* `vcov` (if available),
* `method_details` (a named tuple with method metadata and, if `summaries=true`, **pairwise summaries**: means, deviations, minima, and maxima of empirical τ/ρ/β/γ).
* `method_details` (a named tuple with method metadata).

---

## Behavior & conventions (important)

- fit operates on types, not on pre-constructed parameterized instances. Always pass a Copula or SklarDist *type* to `fit`, e.g. `fit(GumbelCopula, U)` or `fit(CopulaModel, SklarDist{ClaytonCopula,Tuple{Normal,LogNormal}}, X)`. If you already have a constructed instance `C0`, re-estimate its parameters by calling `fit(typeof(C0), U)`.

- Default method selection: each family exposes the list of available fitting strategies via `_available_fitting_methods(CT)`. When `method = :default` the first element of that tuple is used. Example: `Copulas._available_fitting_methods(MyCopula)`.
- Default method selection: each family exposes the list of available fitting strategies via `_available_fitting_methods(CT, d)`. When `method = :default` the first element of that tuple is used. Example: `Copulas._available_fitting_methods(MyCopula, d)`.

- `CopulaModel` is the full result object returned by the fits performed via `Distributions.fit(::Type{CopulaModel}, ...)`. The light-weight shortcut `fit(MyCopula, U)` returns only a copula instance; use `fit(CopulaModel, ...)` to get diagnostics and metadata.

Expand All @@ -80,26 +80,7 @@ The `CopulaModel{CT} <: StatsBase.StatisticalModel` type stores the result and s
| `hqc(M)` | Hannan–Quinn criterion |


Quick access to the contained copula: `_copula_of(M)` (returns the copula even if `result` is a `SklarDist`).


### Pairwise summaries and `method_details`

When you request `summaries=true` (default) the returned `CopulaModel` contains extra pre-computed pairwise statistics inside `M.method_details`. Typical keys are:

- `:tau_mean`, `:tau_sd`, `:tau_min`, `:tau_max`
- `:rho_mean`, `:rho_sd`, `:rho_min`, `:rho_max`
- `:beta_mean`, `:beta_sd`, `:beta_min`, `:beta_max`
- `:gamma_mean`, `:gamma_sd`, `:gamma_min`, `:gamma_max`

Access example:

```@example fitting_interface
M = fit(CopulaModel, GumbelCopula, U; summaries=true)
M.method_details.tau_mean # average pairwise Kendall's tau
```

If `summaries=false` these keys will be absent and `method_details` will be smaller.
By default, the returned `CopulaModel` contains a lot of extra statistics, that you can see by printing the model in the REPL.

### `vcov` and inference notes

Expand Down Expand Up @@ -143,7 +124,7 @@ plot(Ŝ.result)
The names and availiability of fitting methods depends on the model. You can check what is available with the following internal call :

```@example fitting_interface
Copulas._available_fitting_methods(ClaytonCopula)
Copulas._available_fitting_methods(ClaytonCopula, 3)
```

The first method in the list is the one used by default.
Expand All @@ -168,7 +149,7 @@ When you add a new copula family, implement the following so the generic `fit` f
1. `_example(CT, d)` — return a representative instance (used to obtain default params and initial values).
2. `_unbound_params(CT, d, params)` — transform the family `NamedTuple` parameters to an unconstrained `Vector{Float64}` used by optimizers.
3. `_rebound_params(CT, d, α)` — invert `_unbound_params`, returning a `NamedTuple` suitable for `CT(d, ...)` construction.
4. `_available_fitting_methods(::Type{<:YourCopula})` — declare supported methods (examples: `:mle, :itau, :irho, :ibeta, ...`).
4. `_available_fitting_methods(::Type{<:YourCopula}, d::Int)` — declare supported methods (examples: `:mle, :itau, :irho, :ibeta, ...`).
5. `_fit(::Type{<:YourCopula}, U, ::Val{:mle})` (and other `Val{}` methods) — implement the method and return `(fitted_copula, meta::NamedTuple)`; include keys such as `:θ̂`, `:optimizer`, `:converged`, `:iterations` and optionally `:vcov`.

Place this checklist and a minimal `_fit` skeleton in `docs/src/manual/developer_fitting.md` where contributors can copy/paste and adapt.
Expand Down
33 changes: 18 additions & 15 deletions docs/src/manual/intro.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,9 +61,9 @@ You may define a copula object in Julia by simply calling its constructor:

```@example 1
using Copulas
d = 4 # The dimension of the model
d = 3 # The dimension of the model
θ = 7 # Parameter
C = ClaytonCopula(4,7) # A 4-dimensional clayton copula with parameter θ = 7.
C = ClaytonCopula(d,7) # A 3-dimensional clayton copula with parameter θ = 7.
```

This object is a random vector, and behaves exactly as you would expect a random vector from `Distributions.jl` to behave: you may sample it with `rand(C,100)`, compute its pdf or cdf with `pdf(C,x)` and `cdf(C,x)`, etc:
Expand All @@ -84,6 +84,18 @@ plot(C, :logpdf)

See [the visualizations page](@ref viz_page) for details on the visualisations tools. It’s often useful to get an intuition by looking at scatter plots.

!!! example "Independence"
To give another example, the function

$\Pi : \boldsymbol x \mapsto \prod_{i=1}^d x_i = \boldsymbol x^{\boldsymbol 1}$ is a copula, corresponding to independent random vectors.

This copula can be constructed using the [`IndependentCopula(d)`](@ref IndependentCopula) syntax as follows:

```@example 1
Π = IndependentCopula(d) # A 4-variate independence structure.
nothing # hide
```

One of the reasons that makes copulas so useful is the bijective map from the Sklar Theorem [sklar1959](@cite):

!!! theorem "Sklar (1959)"
Expand All @@ -95,25 +107,14 @@ One of the reasons that makes copulas so useful is the bijective map from the Sk

This result allows to decompose the distribution of $\boldsymbol X$ into several components: the marginal distributions on one side, and the copula on the other side, which governs the dependence structure between the marginals. This object is central in our work, and therefore deserves a moment of attention.

!!! example "Independence"
The function

$\Pi : \boldsymbol x \mapsto \prod_{i=1}^d x_i = \boldsymbol x^{\boldsymbol 1}$ is a copula, corresponding to independent random vectors.

The independence copula can be constructed using the [`IndependentCopula(d)`](@ref IndependentCopula) syntax as follows:

```@example 1
Π = IndependentCopula(d) # A 4-variate independence structure.
nothing # hide
```

We can then leverage the Sklar theorem to construct multivariate random vectors from a copula-marginals specification. The implementation we have of this theorem allows building multivariate distributions by specifying separately their marginals and dependence structures as follows:


```@example 1
X₁, X₂, X₃ = Gamma(2,3), Pareto(), LogNormal(0,1) # Marginals
C = ClaytonCopula(3,0.7) # A 3-variate Clayton Copula with θ = 0.7
D = SklarDist(C, (X₁,X₂,X₃)) # The final distribution
D = SklarDist(C, (X₁,X₂,X₃)) # The final distribution, using the previous copula C.
plot(D, scale=:sklar)
nothing # hide
```
Expand All @@ -132,7 +133,7 @@ Sklar's theorem can be used the other way around (from the marginal space to the

!!! info "Independent random vectors"

`Distributions.jl` provides the [`product_distribution`](https://juliastats.org/Distributions.jl/stable/multivariate/#Product-distributions) function to create independent random vectors with given marginals. `product_distribution(args...)` is essentially equivalent to `SklarDist(Π, args)`, but our approach generalizes to other dependence structures.
`Distributions.jl` provides the [`product_distribution`](https://juliastats.org/Distributions.jl/stable/multivariate/#Product-distributions) function to create independent random vectors with given marginals. `product_distribution(args...)` is essentially equivalent to `SklarDist(IndependentCopula(d), args)`, but our approach generalizes to other dependence structures.

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:

Expand Down Expand Up @@ -309,3 +310,5 @@ The documentation of this package aims to combine theoretical information and re
Pages = [@__FILE__]
Canonical = false
```


6 changes: 3 additions & 3 deletions src/ArchimaxCopula.jl
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,7 @@ function _rebound_params(CT::Type{<:ArchimaxCopula{2, <:Generator, <:Tail}}, d,
NamedTuple{all_names}(all_vals)
end

_available_fitting_methods(::Type{<:ArchimaxCopula}) = (:mle,)
_available_fitting_methods(::Type{<:ArchimaxCopula}, d) = (:mle,)

# Fast conditional distortion binding (bivariate)
DistortionFromCop(C::ArchimaxCopula{2}, js::NTuple{1,Int}, uⱼₛ::NTuple{1,Float64}, ::Int) = BivArchimaxDistortion(C.gen, C.tail, Int8(js[1]), float(uⱼₛ[1]))
Expand All @@ -177,7 +177,7 @@ end

# --- log-PDF stable ---
function Distributions._logpdf(C::ArchimaxCopula{2, TG, TT}, u) where {TG, TT}
T = promote_type(Float64, eltype(u))
T = typeof(A(C.tail, one(ϕ(C.gen, one(eltype(u))))/2))
@assert length(u) == 2
u1, u2 = u
(0.0 < u1 ≤ 1.0 && 0.0 < u2 ≤ 1.0) || return T(-Inf)
Expand All @@ -201,7 +201,7 @@ function Distributions._logpdf(C::ArchimaxCopula{2, TG, TT}, u) where {TG, TT}

s = S * A0
φp = ϕ⁽¹⁾(C.gen, s) # < 0
φpp = ϕ⁽ᵏ⁾(C.gen, Val(2), s) # > 0
φpp = ϕ⁽ᵏ⁾(C.gen, 2, s) # > 0

base = su*sv + (φp/φpp)*suv
base > 0 || return T(-Inf)
Expand Down
Loading
Loading