Internal API (for reference)

These are non-public implementation details. They can change without notice. Use at your own risk.

Copulas.AMHGenerator Type

AMHGenerator{T}

Fields:

• θ::Real - parameter

Constructor

AMHGenerator(θ)
AMHCopula(d,θ)

The AMH copula in dimension $d$ is parameterized by $\theta \in [-1,1)$. It is an Archimedean copula with generator:

$$\varphi (t)=1-\frac{1-\theta }{e^{-t}-\theta }.$$

Special cases:

• When θ = 0, it is the IndependentCopula

References:

• [3] Nelsen, Roger B. An introduction to copulas. Springer, 2006.

source

Copulas.AsymGalambosTail Type

AsymGalambosTail{T}

Fields:

• α::Real — dependence parameter

• θ₁::Real — asymmetry weight in [0,1]

• θ₂::Real — asymmetry weight in [0,1]

Constructor

AsymGalambosCopula(α, θ₁, θ₂)
ExtremeValueCopula(2, AsymGalambosTail(α, θ₁, θ₂))

The (bivariate) asymmetric Galambos extreme-value copula is parameterized by $\alpha \in [0,\mathrm{\infty })$ and ${\theta }_1,{\theta }_2\in [0,1]$. It is an EV copula with Pickands function

$$A(t)=1-(({\theta }_{1}t{)}^{-\alpha }+({\theta }_2(1-t){)}^{-\alpha }{)}^{-1/\alpha },t\in [0,1].$$

Special cases:

• α = 0 ⇒ IndependentCopula

• θ₁ = θ₂ = 0 ⇒ IndependentCopula

• θ₁ = θ₂ = 1 ⇒ GalambosCopula

References:

• [49] Families of min-stable multivariate exponential and multivariate extreme value distributions. Statist. Probab, 1990.

source

Copulas.AsymLogTail Type

AsymLogTail{T}

Fields:

• α::Real — dependence parameter (α ≥ 1)

• θ₁::Real — asymmetry weight in [0,1]

• θ₂::Real — asymmetry weight in [0,1]

Constructor

AsymLogCopula(α, θ₁, θ₂)
ExtremeValueCopula(2, AsymLogTail(α, θ₁, θ₂))

The (bivariate) asymmetric logistic extreme–value copula is parameterized by α ∈ [1, ∞) and θ₁, θ₂ ∈ [0,1]. Its Pickands dependence function is

$$A(t)=({\theta }_1^{\alpha }(1-t{)}^{\alpha }+{\theta }_2^{\alpha }{t}^{\alpha }{)}^{1/\alpha }+({\theta }_1-{\theta }_2)t+1-{\theta }_1,t\in [0,1].$$

Special cases:

• θ₁ = θ₂ = 1 ⇒ symmetric Logistic (Gumbel) copula

• θ₁ = θ₂ = 0 ⇒ independence (A(t) ≡ 1)

References:

• [50] : Tawn, Jonathan A. "Bivariate extreme value theory: models and estimation." Biometrika 75.3 (1988): 397-415.

source

Copulas.AsymMixedTail Type

AsymMixedTail{T}

Fields:

• θ₁::Real — parameter

• θ₂::Real — parameter

Constructor

AsymMixedCopula(θ₁, θ₂) ExtremeValueCopula(2, AsymMixedTail(θ₁, θ₂))

The (bivariate) asymmetric Mixed extreme-value copula is parameterized by two parameters ${\theta }_1$, ${\theta }_2$ subject to the following constraints:

• θ₁ ≥ 0

• θ₁ + θ₂ ≤ 1

• θ₁ + 2θ₂ ≤ 1

• θ₁ + 3θ₂ ≥ 0

Its Pickands dependence function is

$$A(t)={\theta }_2{t}^3+{\theta }_1{t}^2-({\theta }_1+{\theta }_2)t+1,t\in [0,1].$$

Special cases:

• θ₁ = θ₂ = 0 ⇒ IndependentCopula

• θ₂ = 0 ⇒ symmetric Mixed copula

References:

• [50] : Tawn, Jonathan A. "Bivariate extreme value theory: models and estimation." Biometrika 75.3 (1988): 397-415.

source

Copulas.BB10Generator Type

BB10Generator{T}

Fields:

• θ::Real - parameter

• δ::Real - parameter

Constructor

BB10Generator(θ, δ)
BB10Copula(d, θ, δ)

The BB10 copula has parameters $\theta \in (0,\mathrm{\infty })$ and $\delta \in [0,1]$. It is an Archimedean copula with generator:

$$\varphi (t)=(\frac{1-\delta }{e^t-\delta }{)}^{1/\theta },$$

References:

• [4] Joe, H. (2014). Dependence modeling with copulas. CRC press, Page.206-207

source

Copulas.BB1Generator Type

BB1Generator{T}

Fields:

• θ::Real - parameter

• δ::Real - parameter

Constructor

BB1Generator(θ, δ)
BB1Copula(d, θ, δ)

The BB1 copula is parameterized by $\theta \in (0,\mathrm{\infty })$ and $\delta \in [1,\mathrm{\infty })$. It is an Archimedean copula with generator:

$$\varphi (t)=(1+t^{1/\delta }{)}^{-1/\theta },$$

Special cases:

• When δ = 1, it is the ClaytonCopula with parameter $\theta$.

References:

• [4] Joe, H. (2014). Dependence modeling with copulas. CRC press, Page.190-192

source

Copulas.BB2Generator Type

BB2Generator{T}

Fields:

• θ::Real - parameter

• δ::Real - parameter

Constructor

BB2Generator(θ, δ)
BB2Copula(d, θ, δ)

The BB2 copula has parameters $\theta ,\delta \in (0,\mathrm{\infty })$. It is an Archimedean copula with generator:

$$\varphi (t)=[1+{\delta }^{-1}log(1+t){]}^{-\frac{1}{\theta }},$$

References:

• [4] Joe, H. (2014). Dependence modeling with copulas. CRC press, Page.193-194

source

Copulas.BB3Generator Type

BB3Generator{T}

Fields:

• θ::Real - parameter

• δ::Real - parameter

Constructor

BB3Generator(θ, δ)
BB3Copula(d, θ, δ)

The BB3 copula has parameters $\theta \in [1,\mathrm{\infty })$ and $\delta \in (0,\mathrm{\infty })$. It is an Archimedean copula with generator:

$$\varphi (t)=\exp (-[{\delta }^{-1}\log (1+t){]}^{\frac{1}{\theta }}),$$

References:

• [4] Joe, H. (2014). Dependence modeling with copulas. CRC press, Page.195-196

source

Copulas.BB6Generator Type

BB6Generator{T}

Fields:

• θ::Real - parameter

• δ::Real - parameter

Constructor

BB6Generator(θ, δ)
BB6Copula(d, θ, δ)

The BB6 copula has parameters $\theta ,\delta \in [1,\mathrm{\infty })$. It is an Archimedean copula with generator:

$$\varphi (t)=1-[1-\exp (-t^{\frac{1}{\delta }}){]}^{\frac{1}{\theta }}$$

References:

• [4] Joe, H. (2014). Dependence modeling with copulas. CRC press, Page.200-201

source

Copulas.BB7Generator Type

BB7Generator{T}

Fields:

• θ::Real - parameter

• δ::Real - parameter

Constructor

BB7Generator(θ, δ)
BB7Copula(d, θ, δ)

The BB7 copula is parameterized by $\theta \in [1,\mathrm{\infty })$ and $\delta \in (0,\mathrm{\infty })$. It is an Archimedean copula with generator:

$$\varphi (t)=1-[1-(1+t{)}^{-1/\delta }{]}^{1/\theta }.$$

References:

• [4] Joe, H. (2014). Dependence modeling with copulas. CRC press, Page.202-203

source

Copulas.BB8Generator Type

BB8Generator{T}

Fields:

• ϑ::Real - parameter

• δ::Real - parameter

Constructor

BB8Generator(ϑ, δ)
BB8Copula(d, ϑ, δ)

The BB8 copula has parameters $\vartheta \in [1,\mathrm{\infty })$ and $\delta \in (0,1]$. It is an Archimedean copula with generator:

$$\varphi (t)={\delta }^{-1}[1-(1-\eta \exp (-t){)}^{\frac{1}{\vartheta }}],$$

where $\eta =1-(1-\delta {)}^{\vartheta }$.

References:

• [4] Joe, H. (2014). Dependence modeling with copulas. CRC press, Page.204-205

source

Copulas.BB9Generator Type

BB9Generator{T}

Fields:

• ϑ::Real - parameter

• δ::Real - parameter

Constructor

BB9Generator(ϑ, δ)
BB9Copula(d, ϑ, δ)

The BB9 copula has parameters $\vartheta \in [1,\mathrm{\infty })$ and $\delta \in (0,\mathrm{\infty })$. It is an Archimedean copula with generator:

$$\varphi (t)=\exp (-({\delta }^{-\vartheta }+t{)}^{\frac{1}{\vartheta }}+{\delta }^{-1}),$$

References:

• [4] Joe, H. (2014). Dependence modeling with copulas. CRC press, Page.205-206

source

Copulas.BC2Tail Type

BC2Tail{T}

Fields:

• a::Real — parameter (a ∈ [0,1])

• b::Real — parameter (b ∈ [0,1])

Constructor

BC2Copula(a, b)
ExtremeValueCopula(2, BC2Tail(a, b))

The bivariate BC2 extreme-value copula is parameterized by two parameters $a,b\in [0,1]$. Its Pickands dependence function is

$$A(t)=max\{at,b(1-t)\}+max\{(1-a)t,(1-b)(1-t)\},t\in [0,1].$$

References:

• [51] Mai, J. F., & Scherer, M. (2011). Bivariate extreme-value copulas with discrete Pickands dependence measure. Extremes, 14, 311-324. Springer, 2011.

source

Copulas.ClaytonGenerator Type

ClaytonGenerator{T}

Fields:

• θ::Real - parameter

Constructor

ClaytonGenerator(θ)
ClaytonCopula(d, θ)

The Clayton copula in dimension $d$ is parameterized by $\theta \in [-1/(d-1),\mathrm{\infty })$ (with the independence case as the limit $\theta \to 0$). It is an Archimedean copula with generator

$$\varphi (t)={(1+\theta t)}^{-1/\theta }$$

with the continuous extension $\varphi (t)=e^{-t}$ at $\theta =0$.

Special cases (for the copula in dimension $d$):

• When $\theta =-1/(d-1)$, it is the WCopula (Lower Fréchet–Hoeffding bound)

• When $\theta \to 0$, it is the IndependentCopula

• When $\theta \to \mathrm{\infty }$, it is the MCopula (Upper Fréchet–Hoeffding bound)

References:

• [3] Nelsen, Roger B. An introduction to copulas. Springer, 2006.

source

Copulas.ConditionalCopula Type

ConditionalCopula{d} <: Copula{d}

Copula of the conditioned random vector U_I | U_J = u_J.

source

Copulas.CuadrasAugeTail Type

CuadrasAugeTail{T}

Fields:

• θ::Real — dependence parameter, θ ∈ [0,1]

Constructor

CuadrasAugeCopula(θ)
ExtremeValueCopula(2, CuadrasAugeTail(θ))

The (bivariate) Cuadras-Augé extreme-value copula is parameterized by $\theta \in [0,1]$. Its Pickands dependence function is

$$A(t)=max\{t,1-t\}+(1-\theta )min\{t,1-t\},t\in [0,1].$$

Special cases:

• θ = 0 ⇒ IndependentCopula

• θ = 1 ⇒ MCopula (comonotone copula)

References:

• [52] Mai, J. F., & Scherer, M. (2012). Simulating copulas: stochastic models, sampling algorithms, and applications (Vol. 4). World Scientific.

source

Copulas.DistortedDist Type

DistortedDist{Disto,Distrib} <: Distributions.UnivariateDistribution

Push-forward of a base marginal by a Distortion.

source

Copulas.Distortion Type

Distortion <: Distributions.ContinuousUnivariateDistribution

Abstract super-type for objects describing the (uniform-scale) conditional marginal transformation U_i | U_J = u_J of a copula.

Subtypes implement cdf/quantile on [0,1]. They are not full arbitrary distributions; they model how a uniform variable is distorted by conditioning. They can be applied as a function to a base marginal distribution to obtain the conditional marginal on the original scale: if D::Distortion and X::UnivariateDistribution, then D(X) is the distribution of X_i | U_J = u_J.

source

Copulas.DistortionFromCop Type

DistortionFromCop{TC,p,T} <: Distortion

Generic, uniform-scale conditional marginal transformation for a copula.

This is the default fallback (based on mixed partial derivatives computed via automatic differentiation) used when a faster specialized Distortion is not available for a given copula family.

Parameters

• TC: copula type

• p: length of the conditioned index set J (static)

• T: element type for the conditioned values u_J

Construction

• DistortionFromCop(C::Copula, js::NTuple{p,Int}, ujs::NTuple{p,<:Real}, i::Int) builds the distortion for the conditional marginal of index i given U_js = ujs.

Notes

• A convenience method DistortionFromCop(C, j::Int, uj::Real, i::Int) exists for the common p = 1 case.

source

Copulas.EllipticalCopula Type

EllipticalCopula{d,MT}

This is an abstract type. It implements an interface for all Elliptical copulas. We construct internally elliptical copulas using the sklar's theorem, by considering the copula $C$ to be defined as :

$$C=F\circ (F_1^{-1},...,F_d^{-1}),$$

where $F$ and $F_1,...,F_d$ are respectively the multivariate distribution function of some elliptical random vector and the univariate distribution function of its marginals. For a type MyCop <: EllipitcalCopula, it is necessary to implement the following methods:

• N(::Type{MyCOp}), returning the constructor of the elliptical random vector from its correlation matrix. For example, N(GaussianCopula) simply returns MvNormal from Distributions.jl.

• U(::Type{MyCOp}), returning the constructor for the univariate marginal, usually in standardized form. For example, U(GaussianCopula) returns Normal from Distributions.jl.

From these two functions, the abstract type provides a fully functional copula.

Details

Recall the definition of spherical random vectors:

Definition: Spherical and elliptical random vectors

A random vector $\mathit{X}$ is said to be spherical if for all orthogonal matrix $\mathit{A}\in O_d(\mathbb{R})$, $\mathit{A}\mathit{X}\sim \mathit{X}$.

For every matrix $\mathit{B}$ and vector $\mathit{c}$, the random vector $\mathit{B}\mathit{X}+\mathit{c}$ is then said to be elliptical.

Recall that spherical random vectors are random vectors which characteristic functions (c.f.) only depend on the norm of their arguments. Indeed, for any $\mathit{A}\in O_d(\mathbb{R})$,

$$\varphi (\mathit{t})=\mathbb{E}\left(e^{⟨\mathit{t},\mathit{X}⟩}\right)=\mathbb{E}\left(e^{⟨\mathit{t},\mathit{A}\mathit{X}⟩}\right)=\mathbb{E}\left(e^{⟨\mathit{A}\mathit{t},\mathit{X}⟩}\right)=\varphi (\mathit{A}\mathit{t}).$$

We can therefore express this characteristic function as $\varphi (\mathit{t})=\psi (\Vert \mathit{t}{\Vert }_2^2)$, where $\psi$ is a function that characterizes the spherical family, called the generator of the family. Any characteristic function that can be expressed as a function of the norm of its argument is the characteristic function of a spherical random vector, since $\Vert \mathit{A}\mathit{t}{\Vert }_2=\Vert \mathit{t}{\Vert }_2$ for any orthogonal matrix $\mathit{A}$.

However, note that this is not how the underlying code is working, we do not check for validity of the proposed generator (we dont even use it). You can construct such an elliptical family using simply Sklar:

struct MyElliptical{d,T} <: EllipticalCopula{d,T}
    θ:T
end
U(::Type{MyElliptical{d,T}}) where {d,T} # Distribution of the univaraite marginals, Normal() for the Gaussian case. 
N(::Type{MyElliptical{d,T}}) where {d,T} # Distribution of the mutlivariate random vector, MvNormal(C.Σ) for the Gaussian case.

These two functions are enough to implement the rest of the interface.

References:

• [3] Nelsen, Roger B. An introduction to copulas. Springer, 2006.

source

Copulas.EmpiricalEVTail Type

EmpiricalEVTail

Fields:

• tgrid::Vector{Float64} — evaluation grid in (0,1)

• Ahat::Vector{Float64} — estimated Pickands function values on tgrid

• slope::Vector{Float64} — per-segment slopes for linear interpolation

Constructor

EmpiricalEVTail(u; method=:ols, grid=401, eps=1e-3, pseudo_values=true) ExtremeValueCopula(2, EmpiricalEVTail(u; ...))

The empirical extreme-value (EV) copula (bivariate) is defined from pseudo-observations u = (U₁, U₂) and a nonparametric estimator of the Pickands dependence function. Supported estimators are:

• :pickands — classical Pickands estimator

• :cfg — Capéraà–Fougères–Genest (CFG) estimator

• :ols — OLS-intercept estimator

For stability, the estimated function is always projected onto the class of valid Pickands functions (convex, bounded between max(t,1-t) and 1, with endpoints fixed at 1).

Its Pickands function is

Â(t),  t ∈ (0,1),

evaluated via piecewise linear interpolation on the grid tgrid.

References

• [caperaa1997nonparametric] Capéraà, Fougères, Genest (1997) Biometrika

• [gudendorf2011nonparametric] Gudendorf, Segers (2011) Journal of Multivariate Analysis

source

Copulas.EmpiricalEVTail Method

EmpiricalEVTail(u; kwargs...)

Construct the empirical Pickands tail from data (2×N).

source

Copulas.ExtremeValueCopula Type

ExtremeValueCopula{d, TT}

Constructor

ExtremeValueCopula(d, tail::Tail)

Extreme-value copulas model tail dependence via a stable tail dependence function (STDF) $\ell$ or, equivalently, via a Pickands dependence function $A$. In any dimension $d$, the copula cdf is

For $d=2$, write $x=-\log u$, $y=-\log v$, $s=x+y$, and $t=x/s$. The relation between $\ell$ and $A$ is

$$\ell (x,y)=sA(t),A:[0,1]\to [1/2,1],A(0)=A(1)=1,A\text{ convex}.$$

Usage

• Provide any valid tail tail::Tail (which implements A and/or ℓ) to construct the copula.

• Sampling, cdf, and logpdf follow the standard Distributions.jl API.

Example

C = ExtremeValueCopula(2, GalambosTail(θ))
U = rand(C, 1000)
logpdf.(Ref(C), eachcol(U))

References:

• [45] G., & Segers, J. (2010). Extreme-value copulas. In Copula Theory and Its Applications (pp. 127-145). Springer.

• [4] Joe, H. (2014). Dependence Modeling with Copulas. CRC Press.

• [48] Mai, J. F., & Scherer, M. (2014). Financial engineering with copulas explained (p. 168). London: Palgrave Macmillan.

source

Copulas.FrailtyGenerator Type

FrailtyGenerator<:AbstractFrailtyGenerator<:Generator

methods: - frailty(::FrailtyGenerator) gives the frailty - ϕ and the rest of generators are automatically defined from the frailty.

Constructor

FrailtyGenerator(D)

A Frailty generator can be defined by a positive random variable that happens to have a mgf() function to compute its moment generating function. The generator is simply:

$$\varphi (t)=mgf(frailty(G),-t)$$

https://www.uni-ulm.de/fileadmin/website_uni_ulm/mawi.inst.zawa/forschung/2009-08-16_hofert.pdf

References:

• [44] M. Hoffert (2009). Efficiently sampling Archimedean copulas

source

Copulas.FrankGenerator Type

FrankGenerator{T}

Fields:

• θ::Real - parameter

Constructor

FrankGenerator(θ)
FrankCopula(d,θ)

The Frank copula in dimension $d$ is parameterized by $\theta \in (-\mathrm{\infty },\mathrm{\infty })$ (with independence as the limit $\theta \to 0$). It is an Archimedean copula with generator

$$\varphi (t)=-\frac{1}{\theta }\log (1-(1-e^{-\theta })e^{-t}).$$

Special cases:

• When $\theta \to -\mathrm{\infty }$, it is the WCopula (Lower Fréchet–Hoeffding bound)

• When $\theta \to 0$, it is the IndependentCopula

• When $\theta \to \mathrm{\infty }$, it is the MCopula (Upper Fréchet–Hoeffding bound)

References:

• [3] Nelsen, Roger B. An introduction to copulas. Springer, 2006.

source

Copulas.GalambosTail Type

GalambosTail{T}

Fields:

• θ::Real — dependence parameter, θ ≥ 0

Constructor

GalambosCopula(θ)
ExtremeValueCopula(2, GalambosTail(θ))

The (bivariate) Galambos extreme-value copula is parameterized by $\theta \in [0,\mathrm{\infty })$. Its Pickands dependence function is

$$A(t)=1-(t^{-\theta }+(1-t{)}^{-\theta }{)}^{-1/\theta },t\in (0,1).$$

Special cases:

• θ = 0 ⇒ IndependentCopula

• θ = ∞ ⇒ MCopula (upper Fréchet-Hoeffding bound)

References:

• [53] Galambos, J. (1975). Order statistics of samples from multivariate distributions. Journal of the American Statistical Association, 70(351a), 674-680.

source

Copulas.Generator Type

Generator

Abstract type. Implements the API for archimedean generators.

An Archimedean generator is simply a function $\varphi :{\mathbb{R}}_{+}\to [0,1]$ such that $\varphi (0)=1$ and $\varphi (+\mathrm{\infty })=0$.

To generate an archimedean copula in dimension $d$, the function also needs to be $d$-monotone, that is :

• $\varphi$ is $d-2$ times derivable.

• $(-1{)}^k{\varphi }^{(k)}\ge 0\mathrm{\forall }k\in \{1,..,d-2\},$ and if $(-1{)}^{d-2}{\varphi }^{(d-2)}$ is a non-increasing and convex function.

The access to the function $\varphi$ itself is done through the interface:

ϕ(G::Generator, t)

We do not check algorithmically that the proposed generators are d-monotonous. Instead, it is up to the person implementing the generator to tell the interface how big can $d$ be through the function

max_monotony(G::MyGenerator) = # some integer, the maximum d so that the generator is d-monotonous.

More methods can be implemented for performance, althouhg there are implement defaults in the package :

• ϕ⁻¹( G::Generator, x) gives the inverse function of the generator.

• ϕ⁽¹⁾(G::Generator, t) gives the first derivative of the generator

• ϕ⁽ᵏ⁾(G::Generator, k::Int, t) gives the kth derivative of the generator

• ϕ⁻¹⁽¹⁾(G::Generator, t) gives the first derivative of the inverse generator.

• williamson_dist(G::Generator, d::Int) gives the Wiliamson d-transform of the generator.

References:

• [14] McNeil, A. J., & Nešlehová, J. (2009). Multivariate Archimedean copulas, d-monotone functions and ℓ 1-norm symmetric distributions.

source

Copulas.GumbelBarnettGenerator Type

GumbelBarnettGenerator{T}

Fields:

• θ::Real - parameter

Constructor

GumbelBarnettGenerator(θ)
GumbelBarnettCopula(d,θ)

The Gumbel-Barnett copula is an archimdean copula with generator:

$$\varphi (t)=\exp ({\theta }^{-1}(1-e^t)),0\le \theta \le 1.$$

Special cases:

• When θ = 0, it is the IndependentCopula

References:

• [4] Joe, H. (2014). Dependence modeling with copulas. CRC press, Page.437

• [3] Nelsen, Roger B. An introduction to copulas. Springer, 2006.

source

Copulas.GumbelGenerator Type

GumbelGenerator{T}

Fields:

• θ::Real - parameter

Constructor

GumbelGenerator(θ)
GumbelCopula(d,θ)

The Gumbel copula in dimension $d$ is parameterized by $\theta \in [1,\mathrm{\infty })$. It is an Archimedean copula with generator :

$$\varphi (t)=\exp (-t^{1/\theta }).$$

It has a few special cases:

• When θ = 1, it is the IndependentCopula

• When θ → ∞, it is the MCopula (Upper Fréchet–Hoeffding bound)

References:

• [3] Nelsen, Roger B. An introduction to copulas. Springer, 2006.

source

Copulas.HuslerReissTail Type

HuslerReissTail{T}

Fields:

• θ::Real — dependence parameter, θ ≥ 0

Constructor

HuslerReissCopula(θ)
ExtremeValueCopula(2, HuslerReissTail(θ))

The (bivariate) Hüsler-Reiss extreme-value copula is parameterized by $\theta \in [0,\mathrm{\infty })$. Its Pickands dependence function is

$$A(t)=t\mathrm{\Phi }({\theta }^{-1}+\frac{1}{2}\theta \log (\frac{t}{1-t}))+(1-t)\mathrm{\Phi }({\theta }^{-1}+\frac{1}{2}\theta \log (\frac{1-t}{t}))$$

where $\mathrm{\Phi }$ is the standard normal cdf.

Special cases:

• θ = 0 ⇒ IndependentCopula

• θ = ∞ ⇒ MCopula (upper Fréchet-Hoeffding bound)

References:

• [54] Hüsler, J., & Reiss, R. D. (1989). Maxima of normal random vectors: between independence and complete dependence. Statistics & Probability Letters, 7(4), 283-286.

source

Copulas.InvGaussianGenerator Type

InvGaussianGenerator{T}

Fields:

• θ::Real - parameter

Constructor

InvGaussianGenerator(θ)
InvGaussianCopula(d,θ)

The Inverse Gaussian copula in dimension $d$ is parameterized by $\theta \in [0,\mathrm{\infty })$. It is an Archimedean copula with generator:

$$\varphi (t)=\exp \left(\frac{1-\sqrt{1+2{\theta }^{2}t}}{\theta }\right).$$

More details about Inverse Gaussian Archimedean copula are found in :

Mai, Jan-Frederik, and Matthias Scherer. Simulating copulas: stochastic models, sampling algorithms, and applications. Vol. 6. # N/A, 2017. Page 74.

Special cases:

• When θ = 0, it is the IndependentCopula

References:

• [3] Nelsen, Roger B. An introduction to copulas. Springer, 2006.

source

Copulas.JoeGenerator Type

JoeGenerator{T}

Fields:

• θ::Real - parameter

Constructor

JoeGenerator(θ)
JoeCopula(d,θ)

The Joe copula in dimension $d$ is parameterized by $\theta \in [1,\mathrm{\infty })$. It is an Archimedean copula with generator:

$$\varphi (t)=1-(1-e^{-t}{)}^{1/\theta }.$$

It has a few special cases:

• When θ = 1, it is the IndependentCopula

• When θ = ∞, it is the MCopula (Upper Fréchet–Hoeffding bound)

References:

• [3] Nelsen, Roger B. An introduction to copulas. Springer, 2006.

source

Copulas.LogTail Type

LogTail{T}

Fields:

• θ::Real — dependence parameter, θ ∈ [0,1]

Constructor

LogCopula(θ)
ExtremeValueCopula(2, LogTail(θ))

The (bivariate) Mixed extreme-value copula is parameterized by $\theta \in [0,1]$. Its Pickands dependence function is

$$A(t)=\theta t^2-\theta t+1,t\in [0,1].$$

Special cases:

• θ = 0 ⇒ IndependentCopula

References:

• [50] : Tawn, Jonathan A. "Bivariate extreme value theory: models and estimation." Biometrika 75.3 (1988): 397-415.

source

Copulas.MOTail Type

MOTail{T}

Fields:

• λ₁::Real — parameter ≥ 0

• λ₂::Real — parameter ≥ 0

• λ₁₂::Real — parameter ≥ 0

Constructor

MOCopula(λ₁, λ₂, λ₁₂)
ExtremeValueCopula(2, MOTail(λ₁, λ₂, λ₁₂))

The (bivariate) Marshall-Olkin extreme-value copula is parameterized by ${\lambda }_i\in [0,\mathrm{\infty }),i=1,2,\{1,2\}$ Its Pickands dependence function is

$$A(t)=\frac{{\lambda }_1(1-t)}{{\lambda }_1+{\lambda }_{1,2}}+\frac{{\lambda }_{2}t}{{\lambda }_2+{\lambda }_{1,2}}+{\lambda }_{1,2}max\{\frac{1-t}{{\lambda }_1+{\lambda }_{1,2}},\frac{t}{{\lambda }_2+{\lambda }_{1,2}}\}$$

Special cases:

• If λ₁₂ = 0, reduces to an asymmetric independence-like form.

• If λ₁ = λ₂ = 0, degenerates to complete dependence.

References:

• [52] Mai, J. F., & Scherer, M. (2012). Simulating copulas: stochastic models, sampling algorithms, and applications (Vol. 4). World Scientific.

source

Copulas.MTail Type

MTail

Corresponds to the MCopula viewed as an etreme value copula.

source

Copulas.MixedTail Type

MixedTail{T}

Fields:

• θ::Real — dependence parameter, θ ∈ [0,1]

Constructor

MixedCopula(θ)
ExtremeValueCopula(2, MixedTail(θ))

The (bivariate) Mixed extreme-value copula is parameterized by $\theta \in [0,1]$. Its Pickands dependence function is

$$A(t)=\theta t^2-\theta t+1,t\in [0,1].$$

Special cases:

• θ = 0 ⇒ IndependentCopula

References:

• [50] : Tawn, Jonathan A. "Bivariate extreme value theory: models and estimation." Biometrika 75.3 (1988): 397-415.

source

Copulas.NoTail Type

NoTail

Corresponds to the case where the pickads function is identically One, which means no particular tail behavior.

source

Copulas.SubsetCopula Type

SubsetCopula{d,CT}

Fields:

• C::CT - The copula

• dims::Tuple{Int} - a Tuple representing which dimensions are used.

Constructor

SubsetCopula(C::Copula,dims)

This class allows to construct a random vector corresponding to a few dimensions of the starting copula. If $(X_1,...,X_n)$ is the random vector corresponding to the copula C, this returns the copula of ( $X_i$ for i in dims). The dependence structure is preserved. There are specialized methods for some copulas.

source

Copulas.Tail Type

Tail

Abstract type. Implements the API for stable tail dependence functions (STDFs) of extreme-value copulas in dimension d.

A STDF is a function $\ell :{\mathbb{R}}_{+}^d\to [0,\mathrm{\infty })$ that is 1-homogeneous ($\ell (t·x)=t·\ell (x)$ for all $t\ge 0$), convex, and satisfies the bounds $max(x_1,\dots ,x_d)\le \ell (x)\le x_1+\cdots +x_d$ (in particular $\ell (e_i)=1$).

Pickands representation. By homogeneity, for $x\ne 0$ let ${\Vert x\Vert }_1=x_1+\cdots +x_d$ and $\omega =x/{\Vert x\Vert }_1\in {\mathrm{\Delta }}_{d-1}$. There exists a Pickands dependence function $A:{\mathrm{\Delta }}_{d-1}\to [0,1]$ (convex, $max({\omega }_i)\le A(\omega )\le 1$) such that $\ell (x)={\Vert x\Vert }_1·A(\omega )$. For $d=2$, $A$ reduces to a convex function on $[0,1]$ with $max(t,1-t)\le A(t)\le 1$ and $A(0)=A(1)=1$.

Interface.

• A(tail::Tail, ω::NTuple{d,Real}) — Pickands function on the simplex \Delta_{d-1}. (For d=2, a convenience A(tail::Tail{2}, t::Real) may be provided.)

• ℓ(tail::Tail, x::NTuple{d,Real}) — STDF. By default the package defines ℓ(tail, x) = ‖x‖₁ * A(tail, x/‖x‖₁) when A is available.

We do not algorithmically verify convexity/bounds; implementers are responsible for validity.

Additional helpers (with defaults).

• For d=2: dA, d²A via AD; stable logpdf/rand (Ghoudi sampler).

• In any d: cdf(u) = exp(-ℓ(-log.(u))).

References:

• Pickands (1981); Gudendorf & Segers (2010); Ghoudi, Khoudraji & Rivest (1998); de Haan & Ferreira (2006).

• Rasell

source

Copulas.tEVTail Type

tEVTail{Tdf,Tρ}

Fields:

• ν::Real — degrees of freedom (ν > 0)

• ρ::Real — correlation parameter (ρ ∈ (-1,1])

Constructor

tEVCopula(ν, ρ)
ExtremeValueCopula(2, tEVTail(ν, ρ))

The (bivariate) extreme-t copula is parameterized by $\nu >0$ and \rho \in (-1,1]``. Its Pickands dependence function is

$$A(x)=x{t}_{\nu +1}(Z_x)+(1-x)t_{\nu +1}(Z_{1-x})$$

Where $t_{\nu +1}$ is the cumulative distribution function (CDF) of the standard t distribution with $\nu +1$ degrees of freedom and

$$Z_x=\sqrt{\frac{1+\nu }{1-{\rho }^2}}({\left(\frac{x}{1-x}\right)}^{1/\nu }-\rho )$$

Special cases:

• ρ = 0 ⇒ IndependentCopula

• ρ = 1 ⇒ M Copula (upper Fréchet-Hoeffding bound)

References:

• [55] Nikoloulopoulos, A. K., Joe, H., & Li, H. (2009). Extreme value properties of multivariate t copulas. Extremes, 12, 129-148.

source

Copulas.𝒲 Type

𝒲(X,d)(x)

Computes the Williamson d-transform of the random variable X, taken at point x.

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,\mathrm{\infty }[$ given by:

$$\varphi (t)={𝒲}_d(X)(t)={\int }_t^{\mathrm{\infty }}{(1-\frac{t}{x})}^{d-1}dF(x)=\mathbb{E}((1-\frac{t}{X}{)}_{+}^{d-1}){\mathbb{1}}_{t>0}+(1-F(0)){\mathbb{1}}_{t<0}$$

This function has several properties: - We have that $\varphi (0)=1$ and $\varphi (Inf)=0$ - $\varphi$ is $d-2$ times derivable, and the signs of its derivatives alternates : $\mathrm{\forall }k\in 0,...,d-2,(-1{)}^k{\varphi }^{(k)}\ge 0$. - ${\varphi }^{(d-2)}$ is convex.

These properties makes this function what is called an archimedean generator, able to generate archimedean copulas in dimensions up to $d$.

References:

• Williamson, R. E. (1956). Multiply monotone functions and their Laplace transforms. Duke Math. J. 23 189–207. MR0077581

• McNeil, Alexander J., and Johanna Nešlehová. "Multivariate Archimedean copulas, d-monotone functions and ℓ 1-norm symmetric distributions." (2009): 3059-3097.

source

Copulas.𝒲₋₁ Type

𝒲₋₁(ϕ,d)

Computes the inverse Williamson d-transform of the d-monotone archimedean generator ϕ.

A $d$-monotone archimedean generator is a function $\varphi$ on ${\mathbb{R}}_{+}$ that has these three properties:

• $\varphi (0)=1$ and $\varphi (Inf)=0$

• $\varphi$ is $d-2$ times derivable, and the signs of its derivatives alternates : $\mathrm{\forall }k\in 0,...,d-2,(-1{)}^k{\varphi }^{(k)}\ge 0$.

• ${\varphi }^{(d-2)}$ is convex.

For such a function $\varphi$, the inverse Williamson-d-transform of $\varphi$ is the cumulative distribution function $F$ of a non-negative random variable $X$, defined by :

$$F(x)={𝒲}_d^{-1}(\varphi )(x)=1-\frac{(-x{)}^{d-1}{\varphi }_{+}^{(d-1)}(x)}{k!}-\sum _{k=0}^{d-2}\frac{(-x{)}^k{\varphi }^{(k)}(x)}{k!}$$

We return 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)

References: - Williamson, R. E. (1956). Multiply monotone functions and their Laplace transforms. Duke Math. J. 23 189–207. MR0077581 - McNeil, Alexander J., and Johanna Nešlehová. "Multivariate Archimedean copulas, d-monotone functions and ℓ 1-norm symmetric distributions." (2009): 3059-3097.

source

Copulas._available_fitting_methods Method

_available_fitting_methods(::Type{<:Copula}, d::Int)

Return the tuple of fitting methods available for a given copula family in a given dimension.

This is used internally by Distributions.fit to check validity of the method argument and to select a default method when method=:default.

Example

_available_fitting_methods(GumbelCopula, 3)
# → (:mle, :itau, :irho, :ibeta)

source

Copulas._copula_of Method

_copula_of(M::CopulaModel)

Returns the copula object contained in the model, even if the result is a SklarDist.

source

Copulas._fit Method

_fit(::Type{<:BernsteinCopula}, U, ::Val{:bernstein};
     m::Union{Int,Tuple,Nothing}=nothing, pseudo_values::Bool=true, kwargs...) -> (C, meta)

Empirical plug-in fitting of BernsteinCopula based on U, using the empirical copula and (optionally) a degree m per dimension.

Arguments

• U::AbstractMatrix: d×n pseudo-observations (if pseudo_values=true) or raw data.

• m: integer (same degree in all coordinates), tuple of degrees per dimension,

or nothing for automatic selection.

• pseudo_values: if false, pseudo-observations are constructed with pseudos(U).

• kwargs...: forwarded to the BernsteinCopula constructor.

Returns

• (C, meta) where C::BernsteinCopula and

meta = (; emp_kind = :bernstein, pseudo_values, m = C.m).

Note: Method with no free parameters (dof=0).

source

Copulas._fit Method

_fit(::Type{<:BetaCopula}, U, ::Val{:beta}; kwargs...) -> (C, meta)

(Empirical) plug-in adjustment of BetaCopula to U pseudo-observations.

Constructs C = BetaCopula(U; kwargs...) and also returns a NamedTuple with metadata for printing and auditing.

Arguments

• U::AbstractMatrix: d×n matrix of pseudo-observations in [0,1].

• kwargs...: Arguments passed back to the BetaCopula constructor.

Returns

• (C, meta) where C::BetaCopula and meta = (; emp_kind = :beta).

Note: Method with no free parameters (dof=0).

source

Copulas._fit Method

_fit(::Type{<:CheckerboardCopula}, U, ::Val{:exact};
     m=nothing, pseudo_values::Bool=true, kwargs...) -> (C, meta)

Empirical checkerboard-type plug-in fitting based on U. If m is nothing, m = (n, …, n) is used; otherwise, it must divide by the sample size.

Arguments

• U::AbstractMatrix: d×n pseudo-observations (or raw data if pseudo_values=false).

• m: integer or vector of integers (one per dimension), or nothing for the default case.

• pseudo_values: if false, internal pseudo-observations are applied.

• kwargs...: forwarded to the constructor.

Returns

• (C, meta) where C::CheckerboardCopula and

meta = (; emp_kind = :exact, pseudo_values, m = C.m).

Note: Method without free parameters (dof=0).

source

Copulas._fit Method

_fit(::Type{<:Copula}, U, ::Val{method}; kwargs...)

Internal entry point for fitting routines.

Each copula family implements _fit methods specialized on Val{method}. They must return a pair (copula, meta) where:

• copula is the fitted copula instance,

• meta::NamedTuple holds method–specific metadata to be stored in method_details.

This is not intended for direct use by end–users. Use [Distributions.fit(CopulaModel, ...)] instead.

source

Copulas._fit Method

_fit(::Type{<:EmpiricalCopula}, U, ::Val{:deheuvels};
     pseudo_values::Bool=true, kwargs...) -> (C, meta)

Constructs the empirical Deheuvels copula from U.

Arguments

• U::AbstractMatrix: d×n pseudo-observations if pseudo_values=true; otherwise, they are computed internally with pseudo(U).

• kwargs...: forwarded to the EmpiricalCopula constructor.

Returns

• (C, meta) where C::EmpiricalCopula and

meta = (; emp_kind = :deheuvels, pseudo_values).

Note: Method with no free parameters (dof=0).

source

Copulas._fit Method

_fit(::Type{<:EmpiricalEVCopula}, U, method::Union{Val{:ols}, Val{:cfg}, Val{:pickands}};
     grid::Int=401, eps::Real=1e-3, pseudo_values::Bool=true, kwargs...) -> (C, meta)

Empirical bivariate extreme value copula fitting via the Pickands function (:ols, :cfg, :pickands).

Arguments

• U::AbstractMatrix: 2×n matrix. If pseudo_values=false, pseudo-observations are applied.

• method: estimator of the Pickands function (:ols/:cfg/:pickands).

• grid: number of grid points in t∈(ε,1−ε).

• eps: extreme trimming for numerical stability.

• kwargs...: forwarded to EmpiricalEVTail/EmpiricalEVCopula.

Returns

• (C, meta) where C::EmpiricalEVCopula and

meta = (; emp_kind = :ev_tail, pseudo_values, method = :ols|:cfg|:pickands, grid, eps).

Note: Method with no free parameters (dof=0).

source

Copulas._hr Method

Small horizontal rule for section separation.

source

Copulas._kendall_sample Method

_kendall_sample(u::AbstractMatrix)

Compute the empirical Kendall sample W with entries W[i] = C_n(U[:,i]), where C_n is the Deheuvels empirical copula built from the same u.

Input and tie handling

• u is expected as a d×n matrix (columns are observations). This routine first applies per-margin ordinal ranks (same policy as pseudos) so that the result is invariant under strictly increasing marginal transformations and robust to ties. Consequently, _kendall_sample(u) ≡ _kendall_sample(pseudos(u)) (same tie policy).

Returns

• Vector{Float64} of length n with values in (0,1).

source

Copulas._kv Method

Key-value aligned printing for header lines.

source

Copulas._print_dependence_metrics Method

Print dependence metrics if available/supported by the copula C.

source

Copulas._print_marginals_section Method

Print the Marginals section for a SklarDist using precomputed Vm if available.

source

Copulas._print_param_section Method

Print a standardized parameter section with optional covariance matrix and vcov method note.

source

Copulas._pstr Method

Pretty p-value formatting: show very small values as inequalities.

source

Copulas._section Method

Render a section header with optional suffix, surrounded by horizontal rules.

source

Copulas.taylor Method

taylor(f::F, x₀, d::Int) where {F}

Compute the Taylor series expansion of the function f around the point x₀ up to order d, and gives you back the derivatives as a vector of length d+1. (first value is f(x₀)).

Arguments

• f: A function to be expanded.

• x₀: The point around which to expand the Taylor series.

• d: The order up to which the Taylor series is computed.

Returns

A tuple with value $(f(x₀),f^{\prime }(x₀),...,f^{(d)}(x₀))$.

source

StatsAPI.aic Method

aic(M::CopulaModel) -> Float64

Akaike information criterion for the fitted model.

source

StatsAPI.bic Method

bic(M::CopulaModel) -> Float64

Bayesian information criterion for the fitted model.

source

StatsAPI.coef Method

coef(M::CopulaModel) -> Vector{Float64}

Vector with the estimated parameters of the copula.

source

StatsAPI.coefnames Method

coefnames(M::CopulaModel) -> Vector

Names of the estimated copula parameters.

source

StatsAPI.deviance Method

deviance(M::CopulaModel) -> Float64

Deviation of the fitted model (-2 * loglikelihood).

source

StatsAPI.fit Method

Distributions.fit(CT::Type{<:Copula}, U; kwargs...) -> CT

Quick fit: devuelve solo la cópula ajustada (atajo de Distributions.fit(CopulaModel, CT, U; kwargs...)).

source

StatsAPI.fit Method

fit(CopulaModel, CT::Type{<:Copula}, U; method=:default, kwargs...)

Fit a copula of type CT to pseudo-observations U.

Arguments

• U::AbstractMatrix — a d×n matrix of data (each column is an observation). If the input is raw data, use SklarDist fitting instead to estimate both margins and copula simultaneously.

• method::Symbol — fitting method; defaults to the first available one (see _available_fitting_methods).

• kwargs... — additional method-specific keyword arguments (e.g. pseudo_values=true, grid=401 for extreme-value tails, etc.).

Returns

A CopulaModel containing the fitted copula and metadata.

Examples

U = rand(GumbelCopula(2, 3.0), 500)

M = fit(CopulaModel, GumbelCopula, U; method=:mle)
println(M)

# Quick fit: returns only the copula
C = fit(GumbelCopula, U; method=:itau)

source

StatsAPI.fit Method

fit(CopulaModel, SklarDist{CT, TplMargins}, X; copula_method=:default, sklar_method=:default,
                                       margins_kwargs=NamedTuple(), copula_kwargs=NamedTuple())

Joint margin and copula adjustment (Sklar approach). sklar_method ∈ (:ifm, :ecdf) controls whether parametric CDFs (:ifm) or pseudo-observations (:ecdf) are used.

source

StatsAPI.nobs Method

nobs(M::CopulaModel) -> Int

Number of observations used in the model fit.

source

StatsAPI.params Method

Distributions.params(C::Copula)
Distributions.params(S::SklarDist)

Return the parameters of the given distribution C. Our extension gives these parameters in a named tuple format.

Arguments

• C::Distributions.Distribution: The distribution object whose parameters are to be retrieved. Copulas.jl implements particular bindings for SklarDist and Copula objects.

Returns

• A named tuple containing the parameters of the distribution in the order they are defined for that distribution type.

source

StatsAPI.predict Method

StatsBase.predict(M::CopulaModel; newdata=nothing, what=:cdf, nsim=0)

Predict or simulate from a fitted copula model.

Keyword arguments

• newdata — matrix of points in [0,1]^d at which to evaluate (what=:cdf or :pdf).

• what — one of :cdf, :pdf, or :simulate.

• nsim — number of samples to simulate if what=:simulate.

Returns

• Vector or matrix of predicted probabilities/densities, or simulated samples.

source

StatsAPI.residuals Method

StatsBase.residuals(M::CopulaModel; transform=:uniform)

Compute Rosenblatt residuals of a fitted copula model.

Arguments

• transform = :uniform → returns Rosenblatt residuals in [0,1].

• transform = :normal → applies Φ⁻¹ to obtain pseudo-normal residuals.

Notes

The residuals should be i.i.d. Uniform(0,1) under a correctly specified model.

source

StatsAPI.vcov Method

vcov(M::CopulaModel) -> Union{Nothing, Matrix{Float64}}

Variance and covariance matrix of the estimators. Can be nothing if not available.

source

References

1. R. B. Nelsen. An Introduction to Copulas. 2nd ed Edition, Springer Series in Statistics (Springer, New York, 2006).

2. H. Joe. Dependence Modeling with Copulas (CRC press, 2014).

3. A. J. McNeil and J. Nešlehová. Multivariate Archimedean Copulas, d -Monotone Functions and L1 -Norm Symmetric Distributions. The Annals of Statistics 37, 3059–3097 (2009).

4. M. Hofert. Efficiently sampling Archimedean copulas (2009).

5. G. Gudendorf and J. Segers. Extreme-value copulas. In: Copula Theory and Its Applications: Proceedings of the Workshop Held in Warsaw, 25-26 September 2009 (Springer, 2010); pp. 127–145.

6. J.-F. Mai and M. Scherer. Financial engineering with copulas explained (Springer, 2014).

7. H. Joe. Families of min-stable multivariate exponential and multivariate extreme value distributions. Statistics & probability letters 9, 75–81 (1990).

8. J. A. Tawn. Bivariate extreme value theory: models and estimation. Biometrika 75, 397–415 (1988).

9. J.-F. Mai and M. Scherer. Bivariate extreme-value copulas with discrete Pickands dependence measure. Extremes 14, 311–324 (2011).

10. J.-F. Mai and M. Scherer. Simulating copulas: stochastic models, sampling algorithms, and applications. Vol. 4 (World Scientific, 2012).

11. J. Galambos. Order statistics of samples from multivariate distributions. Journal of the American Statistical Association 70, 674–680 (1975).

12. J. Hüsler and R.-D. Reiss. Maxima of normal random vectors: between independence and complete dependence. Statistics & Probability Letters 7, 283–286 (1989).

13. A. K. Nikoloulopoulos, H. Joe and H. Li. Extreme value properties of multivariate t copulas. Extremes 12, 129–148 (2009).