Public API

This page lists all public docstrings exposed by the package.

Behavioural contract

The public API consists of documented symbols declared with export or public, together with the documented methods that Copulas.jl adds to adopted interfaces such as Distributions.jl and StatsBase.jl. These behaviours follow semantic versioning; implementation hooks described in the developer guide do not.

Area	Public operations	Guaranteed behaviour
Construction	Family{d}(parameters...), Family(d, parameters...)	Both forms select dimension d, validate their inputs and construct equivalent models of that family. Parameter values may represent simpler limiting copulas without changing the concrete family returned. A family may document an additional dimension-inferred form.
Distribution	length, eltype, params, cdf, logcdf, rand	Every copula is a multivariate distribution with uniform margins and support in the unit hypercube. Vector and matrix sampling preserve dimension and numeric type.
Density	pdf, logpdf, loglikelihood	Available for absolutely continuous components. Singular and mixed copulas follow their documented generalized-density semantics and need not possess a Lebesgue density.
Marginalization	subsetdims	Preserves the requested coordinates and their order. One coordinate yields its univariate marginal.
Conditioning	condition	Produces the conditional univariate distortion or lower-dimensional distribution, with generalized quantiles where atoms occur.
Transforms	rosenblatt, inverse_rosenblatt	Vector and matrix forms are supported. Round-trip bijectivity is guaranteed only for continuous models without atoms.
Dependence	τ, ρ, β, γ, ι, λₗ, λᵤ, their documented inverses, StatsBase.corkendall, StatsBase.corspearman	Results have the documented scalar or pairwise-matrix shape, bounds and symmetry. Closed forms and numerical fallbacks have the same contract.
Fitting	fit, CopulaModel and the StatsBase model interface	Documented family/method pairs return valid fitted models. CopulaModel exposes observations, coefficients, covariance when computed, information criteria, residuals and prediction.
Composition	SklarDist	Distribution operations, marginalization, conditioning and Rosenblatt transforms are expressed on the marginal scales.
Utilities	pseudos, measure, Nataf	Rank pseudo-observations, copula rectangle probability, and Nataf correlation correction respectively.

The mathematical primitives documented for public generators and extreme-value tails are also stable. Concrete internal wrappers, caches, samplers and fallback selection are deliberately outside this contract.

Copulas.AMHCopula Type

AMHGenerator{T}, AMHCopula{d, T}

Fields:

• θ::Real - parameter

Constructors:

AMHGenerator(θ)  # Constructs the generator.
AMHCopula(d,θ)   # Construct the copula

The AMH Copula in dimension d is parameterized by θ ∈ [-1,1). It is an Archimedean copula with generator:

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

Special cases:

• When θ = 0, it collapses to independence.

References:

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

source

Copulas.AMHGenerator Type

AMHGenerator{T}, AMHCopula{d, T}

Fields:

• θ::Real - parameter

Constructors:

AMHGenerator(θ)  # Constructs the generator.
AMHCopula(d,θ)   # Construct the copula

The AMH Copula in dimension d is parameterized by θ ∈ [-1,1). It is an Archimedean copula with generator:

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

Special cases:

• When θ = 0, it collapses to independence.

References:

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

source

Copulas.ArchimaxCopula Type

ArchimaxCopula{d, TG, TT}

Fields

• gen::TG Archimedean generator $\varphi$ (implements ϕ, ϕ⁻¹, derivatives)

• tail::TT Extreme-value tail (implements Pickands A / STDF ℓ)

Constructor

ArchimaxCopula(d, gen::Generator, tail::Tail)
ArchimaxCopula{d}(gen::Generator, tail::Tail)

Definition (bivariate shown). Let $x_i={\varphi }^{-1}(u_i)$ and denote the STDF by $\ell$. The cdf is

$$C(u_1,u_2)=\varphi (\ell (x_1,x_2)).$$

Reductions

• If $\ell (x)=x_1+x_2$ (i.e., tail = NoTail()), this is the Archimedean copula with generator gen.

• If $\varphi (s)=e^{-s}$ (i.e., gen = IndependentGenerator()), this is the extreme-value copula with tail tail.

params(::ArchimaxCopula) concatenates the parameter tuples of gen and tail.

References:

• [59] Capéraà, Fougères & Genest (2000), Bivariate Distributions with Given Extreme Value Attractor.

• [60] Charpentier, Fougères & Genest (2014), Multivariate Archimax Copulas.

• [56] Mai, J. F., & Scherer, M. (2012). Simulating copulas: stochastic models, sampling algorithms, and applications.

source

Copulas.ArchimedeanCopula Type

ArchimedeanCopula{d, TG}

Fields: - G::TG : the generator <: Generator.

Constructor:

ArchimedeanCopula(d::Int, G::Generator)
ArchimedeanCopula{d}(G::Generator)

For some Archimedean Generator G::Generator and some dimenson d, this class models the archimedean copula which has this generator. The constructor checks for validity by ensuring that max_monotony(G) ≥ d. The $d$-variate archimedean copula with generator $\varphi$ writes:

$$C(\mathbf{u})={\varphi }^{-1}(\sum _{i=1}^d\varphi (u_i))$$

The default sampling method is the Radial-simplex decomposition using the Williamson transformation of $\varphi$.

There exists several known parametric generators that are implement in the package. For every NamedGenerator <: Generator implemented in the package, we provide a type alias ``NamedCopula{d,...} = ArchimedeanCopula{d,NamedGenerator{...}}` to be able to manipulate the classic archimedean copulas without too much hassle for known and usefull special cases.

A generic archimedean copula can be constructed as follows:

struct MyGenerator <: Generator end
ϕ(G::MyGenerator,t) = exp(-t) # your archimedean generator, can be any d-monotonous function.
max_monotony(G::MyGenerator) = Inf # could depend on generators parameters.
C = ArchimedeanCopula(d,MyGenerator())

The obtained model can be used as follows:

spl = rand(C,1000)   # sampling
cdf(C,spl)           # cdf
pdf(C,spl)           # pdf
loglikelihood(C,spl) # llh

Bonus: If you know the Williamson d-transform of your generator and not your generator itself, you may take a look at WilliamsonGenerator that implements them. If you rather know the frailty distribution, take a look at WilliamsonFromFrailty.

References:

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

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

source

Copulas.AsymGalambosCopula Type

AsymGalambosTail{T}, AsymGalambosCopula{d,T}

AsymGalambosCopula{2}(α, θ₁, θ₂)
AsymGalambosCopula(2, α, θ₁, θ₂)
AsymGalambosCopula{d}(α, weights)
AsymGalambosCopula(d, α, weights)
AsymGalambosCopula{d}(dep, asy)
AsymGalambosCopula(d, dep, asy)

Asymmetric Galambos (negative-logistic) extreme-value family.

The family uses the subset-based negative-logistic/min-stable construction of Joe [46]. For nonempty subsets C,

$$\ell (x)=\sum _C{\ell }_{\mathrm{Galambos},{\alpha }_C}(({\beta }_{i,C}{x}_i{)}_{i\in C}),$$

with nonnegative asymmetry weights satisfying the marginal normalization constraints.

AsymGalambosCopula(d, dep, asy) exposes the full subset representation. AsymGalambosCopula{d}(α, weights) is a convenience parameterization with one full-set negative-logistic component and singleton remainders. In d=2, it is equivalent to the historical (α, θ₁, θ₂) parameterization and retains the specialized scalar Pickands formulas.

Literature model versus package parameterization

[46] supports the multivariate min-stable/negative-logistic construction. The one-full-set-plus-singletons weights constructor is a convenience parameterization introduced at the implementation level in Copulas.jl.

References:

• [48] Order statistics of samples from multivariate distributions. JASA, 1975.

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

source

Copulas.AsymGalambosTail Type

AsymGalambosTail{T}, AsymGalambosCopula{d,T}

AsymGalambosCopula{2}(α, θ₁, θ₂)
AsymGalambosCopula(2, α, θ₁, θ₂)
AsymGalambosCopula{d}(α, weights)
AsymGalambosCopula(d, α, weights)
AsymGalambosCopula{d}(dep, asy)
AsymGalambosCopula(d, dep, asy)

Asymmetric Galambos (negative-logistic) extreme-value family.

The family uses the subset-based negative-logistic/min-stable construction of Joe [46]. For nonempty subsets C,

$$\ell (x)=\sum _C{\ell }_{\mathrm{Galambos},{\alpha }_C}(({\beta }_{i,C}{x}_i{)}_{i\in C}),$$

with nonnegative asymmetry weights satisfying the marginal normalization constraints.

AsymGalambosCopula(d, dep, asy) exposes the full subset representation. AsymGalambosCopula{d}(α, weights) is a convenience parameterization with one full-set negative-logistic component and singleton remainders. In d=2, it is equivalent to the historical (α, θ₁, θ₂) parameterization and retains the specialized scalar Pickands formulas.

Literature model versus package parameterization

[46] supports the multivariate min-stable/negative-logistic construction. The one-full-set-plus-singletons weights constructor is a convenience parameterization introduced at the implementation level in Copulas.jl.

References:

• [48] Order statistics of samples from multivariate distributions. JASA, 1975.

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

source

Copulas.AsymLogCopula Type

AsymLogTail{T}, AsymLogCopula{d,T}

Fields:

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

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

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

Constructor

AsymLogCopula{2}(α, θ₁, θ₂)
AsymLogCopula(2, α, θ₁, θ₂)
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

• α = 1 or either asymmetry weight is zero ⇒ independence (A(t) ≡ 1)

References:

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

source

Copulas.AsymLogTail Type

AsymLogTail{T}, AsymLogCopula{d,T}

Fields:

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

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

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

Constructor

AsymLogCopula{2}(α, θ₁, θ₂)
AsymLogCopula(2, α, θ₁, θ₂)
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

• α = 1 or either asymmetry weight is zero ⇒ independence (A(t) ≡ 1)

References:

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

source

Copulas.AsymMixedCopula Type

AsymMixedTail{T}, AsymMixedCopula{d,T}

Fields:

• θ₁::Real — parameter

• θ₂::Real — parameter

Constructor

AsymMixedCopula{2}(θ₁, θ₂) AsymMixedCopula(2, θ₁, θ₂) 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:

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

source

Copulas.AsymMixedTail Type

AsymMixedTail{T}, AsymMixedCopula{d,T}

Fields:

• θ₁::Real — parameter

• θ₂::Real — parameter

Constructor

AsymMixedCopula{2}(θ₁, θ₂) AsymMixedCopula(2, θ₁, θ₂) 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:

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

source

Copulas.BB10Copula Type

BB10Generator{T}, BB10Copula{d, 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.BB10Generator Type

BB10Generator{T}, BB10Copula{d, 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.BB1Copula Type

BB1Generator{T}, BB1Copula{d, 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.BB1Generator Type

BB1Generator{T}, BB1Copula{d, 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.BB2Copula Type

BB2Generator{T}, BB2Copula{d, 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.BB2Generator Type

BB2Generator{T}, BB2Copula{d, 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.BB3Copula Type

BB3Generator{T}, BB3Copula{d, 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.BB3Generator Type

BB3Generator{T}, BB3Copula{d, 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.BB4Copula Type

BB4Copula{d,T}

Fields: - θ::Real - dependence parameter (θ ≥ 0) - δ::Real - shape parameter (δ > 0)

Constructor

BB4Copula(θ, δ)

The BB4 copula is a two-parameter Archimax copula constructed from the Galambos tail and the Clayton generator. Its distribution function is

$$C(u,v;\theta ,\delta )={(u^{-\theta }+v^{-\theta }-1-{[(u^{-\theta }-1{)}^{-\delta }+(v^{-\theta }-1{)}^{-\delta }]}^{-1/\delta })}^{-1/\theta },\theta \ge 0,\delta >0.$$

for $0\le u,v\le 1$.

Special cases:

• As δ → 0+, reduces to the Clayton Copula (Archimedean).

• As θ → 0+, reduces to the Galambos copula (extreme-value).

• As θ → ∞ or δ → ∞, approaches the M Copula.

References:

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

source

Copulas.BB5Copula Type

BB5Copula{d,T}

Fields: - θ::Real - dependence parameter (θ ≥ 1) - δ::Real - shape parameter (δ > 0)

Constructor

BB5Copula(θ, δ)

The BB5 copula is a two-parameter Archimax copula, constructed from the Galambos tail and the Gumbel generator. Its distribution function is

$$C(u,v;\theta ,\delta )=\exp \{-[x^{\theta }+y^{\theta }-(x^{-\theta \delta }+y^{-\theta \delta }{)}^{-1/\delta }{]}^{1/\theta }\},\theta \ge 1,\delta >0,$$

where $x=-\log (u)$ and $y=-\log (v)$.

Special cases:

• As δ → 0⁺, reduces to the Gumbel copula (extreme-value and Archimedean).

• As θ = 1, reduces to the Galambos copula.

• As θ → ∞ or δ → ∞, converges to the M copula.

References:

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

source

Copulas.BB6Copula Type

BB6Generator{T}, BB6Copula{d, 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.BB6Generator Type

BB6Generator{T}, BB6Copula{d, 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.BB7Copula Type

BB7Generator{T}, BB7Copula{d, 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.BB7Generator Type

BB7Generator{T}, BB7Copula{d, 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.BB8Copula Type

BB8Generator{T}, BB8Copula{d, 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.BB8Generator Type

BB8Generator{T}, BB8Copula{d, 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.BB9Copula Type

BB9Generator{T}, BB9Copula{d, 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.BB9Generator Type

BB9Generator{T}, BB9Copula{d, 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.BC2Copula Type

BC2Tail{T}, BC2Copula{d,T}

BC2Copula{2}(a, b)
BC2Copula(2, a, b)
BC2Copula{d}(a::AbstractVector)
BC2Copula(d, a::AbstractVector)
BC2Copula(a::AbstractVector)

BC2 extreme-value family with a finite two-atom spectral representation.

For the classical bivariate model [55],

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

Copulas.jl also accepts a vector a=(a₁,…,a_d) and uses the direct d-dimensional two-atom spectral extension

$$\ell (x)=\underset{i}{max}(a_i{x}_i)+\underset{i}{max}((1-a_i)x_i).$$

The vector length determines d; in dimension two the same representation activates the specialized Pickands methods.

Copulas.jl multivariate parameterization

The bivariate BC2 model is documented in [55]. The vector constructor is the direct higher-dimensional two-atom spectral construction used by Copulas.jl; general finite spectral constructions are discussed in [56].

source

Copulas.BC2Tail Type

BC2Tail{T}, BC2Copula{d,T}

BC2Copula{2}(a, b)
BC2Copula(2, a, b)
BC2Copula{d}(a::AbstractVector)
BC2Copula(d, a::AbstractVector)
BC2Copula(a::AbstractVector)

BC2 extreme-value family with a finite two-atom spectral representation.

For the classical bivariate model [55],

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

Copulas.jl also accepts a vector a=(a₁,…,a_d) and uses the direct d-dimensional two-atom spectral extension

$$\ell (x)=\underset{i}{max}(a_i{x}_i)+\underset{i}{max}((1-a_i)x_i).$$

The vector length determines d; in dimension two the same representation activates the specialized Pickands methods.

Copulas.jl multivariate parameterization

The bivariate BC2 model is documented in [55]. The vector constructor is the direct higher-dimensional two-atom spectral construction used by Copulas.jl; general finite spectral constructions are discussed in [56].

source

Copulas.BernsteinCopula Type

BernsteinCopula{d}

Fields:

• m::NTuple{d,Int} - polynomial degrees (smoothing parameters)

• weights::Array{Float64, d} - precomputed grid of box measures

Constructor

BernsteinCopula(C; m=10)
BernsteinCopula(data; m=10)

The Bernstein copula in dimension $d$ is defined as

$B_m(C)(u)=\sum _{s_1=0}^{m_1}\cdots \sum _{s_d=0}^{m_d}C(\frac{s_1}{m_1},\dots ,\frac{s_d}{m_d})\prod _{j=1}^d(\genfrac{}{}{0ex}{}{m_j}{s_j})u_j^{s_j}(1-u_j{)}^{m_j-s_j}.$

It is a polynomial approximation of the base copula $C$ using the multivariate Bernstein operator.

Implementation notes:

• The grid of box measures (weights) is fully precomputed and stored as an $n$-dimensional array at construction. This enables fast evaluation of the copula and its density, but can be memory-intensive for large $d$ or $m$.

• The choice of m controls the smoothness of the approximation: larger m yields finer approximation but exponentially increases memory and computation cost ($\prod _j{m}_j$ boxes).

• For high dimensions or large $m$, memory usage may become prohibitive; see documentation for scaling behavior.

• If $C$ is an EmpiricalCopula, the constructor produces the empirical Bernstein copula, a smoothed version of the empirical copula.

• Supports cdf, logpdf, and random generation via mixtures of beta distributions.

References:

• [63] Sancetta, A., & Satchell, S. (2004). The Bernstein copula and its applications to modeling and approximations of multivariate distributions. Econometric Theory, 20(3), 535-562.

• [62] Segers, J., Sibuya, M., & Tsukahara, H. (2017). The empirical beta copula. Journal of Multivariate Analysis, 155, 35-51.

source

Copulas.BetaCopula Type

BetaCopula{d, MT}

Fields:

• ranks::MT - ranks matrix (d × n), each row contains integers 1..n

Constructor

BetaCopula(u)

The empirical beta copula in dimension $d$ is defined as

$$C_n^{\beta }(u)=\frac{1}{n}\sum _{i=1}^n\prod _{j=1}^d{F}_{n,R_{ij}}(u_j),$$

where $R_{ij}$ is the rank of observation $i$ in margin $j$, and $U\sim Beta(r,n+1-r)$.

Notes:

• This is always a valid copula for any finite sample size n.

• Supports cdf, logpdf at observed points and random sampling.

References:

• [62] Segers, J., Sibuya, M., & Tsukahara, H. (2017). The empirical beta copula. Journal of Multivariate Analysis, 155, 35-51.

source

Copulas.CheckerboardCopula Type

CheckerboardCopula{d, T}

Fields:

• m::Vector{Int} — length d; number of partitions per dimension (grid resolution).

• boxes::Dict{NTuple{d,Int}, T} — dictionary-like mapping from grid box indices to empirical weights. Typically Dict{NTuple{d,Int}, Float64} built with StatsBase.proportionmap.

Constructor:

CheckerboardCopula(X; m=nothing, pseudo_values=true)

Builds a piecewise-constant (histogram) copula on a regular grid. The unit cube in each dimension i is partitioned into m[i] equal bins. Each observation is assigned to a box k ∈ ∏_i {0, …, m[i]-1}; the empirical box weights w_k sum to 1. The copula density is constant inside each box, with

c(u) = w_k × ∏_i m[i]  when u ∈ box k,  and  0 otherwise.

The CDF admits the multilinear overlap form

C(u) = ∑_k w_k × ∏_i clamp(m[i]·u_i − k_i, 0, 1),

which this type evaluates directly without storing all grid corners.

Notes:

• If m is nothing, we use m = fill(n, d) where n = size(X, 2).

• When pseudo_values=true (default), X must already be pseudo-observations in [0,1]. Otherwise pass raw data and set pseudo_values=false to convert via pseudos(X).

• Each m[i] must divide n to produce a valid checkerboard on the sample grid; this is enforced by the constructor.

References

• Neslehova (2007). On rank correlation measures for non-continuous random variables.

• Durante, Sanchez & Sempi (2013) Multivariate patchwork copulas: a unified approach with applications to partial comonotonicity.

• Segers, Sibuya & Tsukahara (2017). The empirical beta copula. J. Multivariate Analysis, 155, 35-51.

• Genest, Neslehova & Rémillard (2017) Asymptotic behavior of the empirical multilinear copula process under broad conditions.

• Cuberos, Masiello & Maume-Deschamps (2019) Copulas checker-type approximations: application to quantiles estimation of aggregated variables.

• Fredricks & Hofert (2025). On the checkerboard copula and maximum entropy.

source

Copulas.ClaytonCopula Type

ClaytonGenerator{T}, ClaytonCopula{d, 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 =0$, it is the IndependentCopula

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

References:

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

source

Copulas.ClaytonGenerator Type

ClaytonGenerator{T}, ClaytonCopula{d, 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 =0$, it is the IndependentCopula

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

References:

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

source

Copulas.CopulaModel Type

CopulaModel{CT, TM, TD} <: StatsBase.StatisticalModel

A fitted copula model.

This type stores the result of fitting a copula (or a Sklar distribution) to pseudo-observations or raw data, together with auxiliary information useful for statistical inference and model comparison.

Fields

• result::CT — the fitted copula (or SklarDist).

• n::Int — number of observations used in the fit.

• ll::Float64 — log-likelihood at the optimum.

• method::Symbol — fitting method used (e.g. :mle, :itau, :deheuvels).

• vcov::Union{Nothing, AbstractMatrix} — estimated covariance of the parameters, if available.

• converged::Bool — whether the optimizer reported convergence.

• iterations::Int — number of iterations used in optimization.

• elapsed_sec::Float64 — time spent in fitting.

• method_details::NamedTuple — additional method-specific metadata (grid size, pseudo-values, etc.).

CopulaModel implements the standard StatsBase.StatisticalModel interface: StatsBase.nobs, StatsBase.coef, StatsBase.coefnames, StatsBase.vcov, StatsBase.aic, StatsBase.bic, StatsBase.deviance, etc.

See also Distributions.fit.

source

Copulas.CuadrasAugeCopula Type

CuadrasAugeTail{T}, CuadrasAugeCopula{d,T}

CuadrasAugeCopula{d}(θ)
CuadrasAugeCopula(d, θ)

Cuadras-Augé extreme-value copula in dimension d ≥ 2, with θ ∈ [0,1]. Copulas.jl uses the stable tail dependence function

$$\ell (x)=(1-\theta )\sum _{i=1}^d{x}_i+\theta \underset{1\le i\le d}{max}{x}_i.$$

For d = 2 this yields the usual Pickands dependence function

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

The model has a finite discrete-spectral representation.

Special cases:

• θ = 0 represents IndependentCopula(d).

• θ = 1 represents MCopula(d).

References:

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

source

Copulas.CuadrasAugeTail Type

CuadrasAugeTail{T}, CuadrasAugeCopula{d,T}

CuadrasAugeCopula{d}(θ)
CuadrasAugeCopula(d, θ)

Cuadras-Augé extreme-value copula in dimension d ≥ 2, with θ ∈ [0,1]. Copulas.jl uses the stable tail dependence function

$$\ell (x)=(1-\theta )\sum _{i=1}^d{x}_i+\theta \underset{1\le i\le d}{max}{x}_i.$$

For d = 2 this yields the usual Pickands dependence function

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

The model has a finite discrete-spectral representation.

Special cases:

• θ = 0 represents IndependentCopula(d).

• θ = 1 represents MCopula(d).

References:

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

source

Copulas.DiscreteSpectralTail Type

DiscreteSpectralTail(B)

Finite discrete spectral representation of a multivariate extreme-value copula.

B is a nonnegative d × m matrix whose rows sum to one. Its stable tail dependence function is

ℓ(x) = sum(maximum(B[:, k] .* x) for k in 1:m).

Equivalently, if h[k] = sum(B[:,k]) and v[:,k] = B[:,k] / h[k], the associated spectral measure is sum(h[k] δ_{v[:,k]}).

The row-sum constraints are exactly the spectral moment constraints required for unit-Fréchet / uniform margins.

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.EmpiricalCopula Type

EmpiricalCopula{d, MT}

Fields:

• u::MT — pseudo-observation matrix of size (d, N).

Constructor

EmpiricalCopula(u; pseudo_values=true)

The empirical copula in dimension $d$ is defined from a matrix of pseudo-observations $\mathbf{u}=(u_{i,j}{)}_{1\le i\le d,1\le j\le N}$ with entries in $[0,1]$. Its distribution function is

$$C(\mathbf{x})=\frac{1}{N}\sum _{j=1}^N{\mathbf{1}}_{\{{\mathbf{u}}_{\cdot ,j}\le \mathbf{x}\}},$$

where the inequality is componentwise. If pseudo_values=false, the constructor first ranks the raw data into pseudo-observations; otherwise it assumes u already contains pseudo-observations in $[0,1]$.

Notes:

• This is an empirical object based on pseudo-observations; it is not necessarily a true copula for finite $N$ but is widely used for nonparametric inference.

• Supports cdf, logpdf at observed points, random sampling, and subsetting.

References:

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

source

Copulas.EmpiricalEVCopula Type

EmpiricalEVCopula{d}(u; kwargs...)
EmpiricalEVCopula(d, u; kwargs...)
EmpiricalEVCopula(u; kwargs...)

Construct a shape-valid multivariate empirical extreme-value copula from a d × n sample. The {d} form is canonical; the runtime-d and inferred forms are convenience constructors. The bivariate path preserves the historical Pickands estimator; dimensions d ≥ 3 use the shape-constrained spectral estimator internally.

source

Copulas.EmpiricalEVMultivariateTail Type

EmpiricalEVMultivariateTail(u; method=:ols, degree=nothing,
                            pseudo_values=true)

Shape-constrained nonparametric extreme-value tail in arbitrary dimension.

The pilot Pickands estimator is one of :ols, :cfg, or :pickands. The multivariate CFG/OLS construction follows Gudendorf and Segers [49].

For d ≥ 3, ordinary convexification is not sufficient to characterize a valid Pickands dependence function. The pilot is therefore projected by least squares onto a class generated by a finite spectral measure supported on a simplex grid, following the shape-constrained projection methodology of Gudendorf and Segers [50].

If the spectral grid has atoms v₁,…,vₘ and masses h₁,…,hₘ, the projected Pickands function is

$$A(w)=\sum _{k=1}^m{h}_k\underset{i}{max}(w_i{v}_{ik}),$$

subject to nonnegative masses and the spectral moment constraints. The resulting tail is stored as a DiscreteSpectralTail, so STDF validity and exact spectral simulation follow by construction.

degree controls the simplex-grid resolution. The automatic dimension-adaptive degree and the numerical projection details are Copulas.jl implementation choices; the statistical estimator and shape-constrained spectral projection are literature-based.

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

$${\displaystyle C(u)=\exp (-\ell (-\log u_1,\dots ,-\log u_d)).}$$

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:

• [53] 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.

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

source

Copulas.FGMCopula Type

FGMCopula{d,T}

Fields:

• θ::Real - parameter

Constructor

FGMCopula(d, θ)

The multivariate Farlie–Gumbel–Morgenstern (FGM) copula of dimension d has $2^d-d-1$ parameters $\theta$ and

$$C(\mathit{u})=\prod _{i=1}^d{u}_i[1+\sum _{k=2}^d\sum _{1\le j_1<\cdots <j_k\le d}{\theta }_{j_1\cdots j_k}{\overline{u}}_{j_1}\cdots {\overline{u}}_{j_k}],$$

where $\overline{u}=1-u$.

Special cases:

• When d=2 and θ = 0, it is the IndependentCopula.

More details about Farlie-Gumbel-Morgenstern (FGM) copula are found in [3]. We use the stochastic representation from [76] to obtain random samples.

References:

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

• [76] Blier-Wong, C., Cossette, H., & Marceau, E. (2022). Stochastic representation of FGM copulas using multivariate Bernoulli random variables. Computational Statistics & Data Analysis, 173, 107506.

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:

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

source

Copulas.FrankCopula Type

FrankGenerator{T}, FrankCopula{d, 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.FrankGenerator Type

FrankGenerator{T}, FrankCopula{d, 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.GalambosCopula Type

GalambosTail{T}, GalambosCopula{d,T}

GalambosCopula{d}(θ)
GalambosCopula(d, θ)

Galambos (negative-logistic) extreme-value copula in dimension d ≥ 2, with θ ∈ [0, ∞]. Its stable tail dependence function is

$$\ell (x)=\sum _{\varnothing \ne I\subseteq \{1,\dots ,d\}}(-1{)}^{|I|+1}{\left(\sum _{i\in I}{x}_i^{-\theta }\right)}^{-1/\theta }.$$

For d = 2, the equivalent Pickands dependence function is

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

and the implementation uses the native bivariate derivatives when beneficial.

Special cases:

• θ = 0 represents IndependentCopula(d).

• θ = ∞ represents MCopula(d).

References:

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

source

Copulas.GalambosTail Type

GalambosTail{T}, GalambosCopula{d,T}

GalambosCopula{d}(θ)
GalambosCopula(d, θ)

Galambos (negative-logistic) extreme-value copula in dimension d ≥ 2, with θ ∈ [0, ∞]. Its stable tail dependence function is

$$\ell (x)=\sum _{\varnothing \ne I\subseteq \{1,\dots ,d\}}(-1{)}^{|I|+1}{\left(\sum _{i\in I}{x}_i^{-\theta }\right)}^{-1/\theta }.$$

For d = 2, the equivalent Pickands dependence function is

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

and the implementation uses the native bivariate derivatives when beneficial.

Special cases:

• θ = 0 represents IndependentCopula(d).

• θ = ∞ represents MCopula(d).

References:

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

source

Copulas.GaussianCopula Type

GaussianCopula{d, MT}

Fields:

• Σ::MT — correlation matrix (the constructor coerces the input to a correlation matrix).

Constructors

GaussianCopula(Σ)
GaussianCopula(d, ρ)
GaussianCopula{d}(Σ)
GaussianCopula{d}(ρ)

Where Σ is a (symmetric) covariance or correlation matrix. The two-argument form with (d, ρ) builds the equicorrelation matrix with ones on the diagonal and constant off-diagonal correlation ρ:

Σ = fill(ρ, d, d); Σ[diagind(Σ)] .= 1
C = GaussianCopula(d, ρ)            # == GaussianCopula(Σ)

Validity domain (equicorrelated PD matrix): -1/(d-1) < ρ < 1. The boundary ρ = -1/(d-1) is singular and rejected. If ρ == 0, the resulting GaussianCopula represents independence, as it does for any diagonal matrix.

The Gaussian copula is the copula of a multivariate normal distribution. It is defined by

$$C(\mathbf{x};\mathbf{\Sigma })=F_{\mathrm{\Sigma }}(F_{\mathrm{\Sigma },1}^{-1}(x_1),\dots ,F_{\mathrm{\Sigma },d}^{-1}(x_d)),$$

where $F_{\mathrm{\Sigma }}$ is the cdf of a centered multivariate normal with covariance/correlation $\mathrm{\Sigma }$ and $F_{\mathrm{\Sigma },i}$ its i-th marginal cdf.

Example usage:

C = GaussianCopula(Σ)
u = rand(C, 1000)
pdf(C, u); cdf(C, u)
Ĉ = fit(GaussianCopula, u)

Special case:

• If isdiag(Σ), the GaussianCopula represents independence while retaining its concrete family type.

References:

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

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.

• 𝒲₋₁(G::Generator, d::Real) gives the inverse Williamson transform of the generator as a positive univariate distribution. Positive non-integer orders use an exact beta reduction from ceil(Int, d).

References:

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

source

Copulas.GumbelBarnettCopula Type

GumbelBarnettGenerator{T}, GumbelBarnettCopula{d, 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.GumbelBarnettGenerator Type

GumbelBarnettGenerator{T}, GumbelBarnettCopula{d, 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.GumbelCopula Type

GumbelGenerator{T}, GumbelCopula{d, 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.GumbelGenerator Type

GumbelGenerator{T}, GumbelCopula{d, 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.HuslerReissCopula Type

HuslerReissTail{T}, HuslerReissCopula{d,T}

HuslerReissCopula{d}(θ)
HuslerReissCopula(d, θ)
HuslerReissCopula{d}(Γ)
HuslerReissCopula(d, Γ)
HuslerReissCopula(Γ)

Hüsler-Reiss extreme-value copula.

HuslerReissCopula(d, θ) is the exchangeable representation with θ ∈ [0,∞]. For d > 2, it corresponds to a variogram with constant off-diagonal entry

$$\gamma ={\left(\frac{2}{\theta }\right)}^2.$$

HuslerReissCopula(Γ) is the general variogram representation. The square matrix Γ determines the dimension. It must be finite and symmetric, with zero diagonal, and must satisfy the Hüsler-Reiss variogram validity conditions. For a non-degenerate d ≥ 3 representation, off-diagonal entries are strictly positive and the variogram is strictly conditionally negative definite.

Scalar and matrix parameters are stored by the same HuslerReissTail type; its parameter type selects the exchangeable or general-variogram algorithms. A 2×2 variogram uses the specialized bivariate kernel after recovering $\theta =2/\sqrt{{\mathrm{\Gamma }}_{12}}$. In dimension two,

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

Special cases:

• θ = 0 represents IndependentCopula(d).

• θ = ∞, or an all-zero variogram, represents MCopula(d).

References:

• [57] 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.HuslerReissTail Type

HuslerReissTail{T}, HuslerReissCopula{d,T}

HuslerReissCopula{d}(θ)
HuslerReissCopula(d, θ)
HuslerReissCopula{d}(Γ)
HuslerReissCopula(d, Γ)
HuslerReissCopula(Γ)

Hüsler-Reiss extreme-value copula.

HuslerReissCopula(d, θ) is the exchangeable representation with θ ∈ [0,∞]. For d > 2, it corresponds to a variogram with constant off-diagonal entry

$$\gamma ={\left(\frac{2}{\theta }\right)}^2.$$

HuslerReissCopula(Γ) is the general variogram representation. The square matrix Γ determines the dimension. It must be finite and symmetric, with zero diagonal, and must satisfy the Hüsler-Reiss variogram validity conditions. For a non-degenerate d ≥ 3 representation, off-diagonal entries are strictly positive and the variogram is strictly conditionally negative definite.

Scalar and matrix parameters are stored by the same HuslerReissTail type; its parameter type selects the exchangeable or general-variogram algorithms. A 2×2 variogram uses the specialized bivariate kernel after recovering $\theta =2/\sqrt{{\mathrm{\Gamma }}_{12}}$. In dimension two,

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

Special cases:

• θ = 0 represents IndependentCopula(d).

• θ = ∞, or an all-zero variogram, represents MCopula(d).

References:

• [57] 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.IndependentCopula Type

IndependentCopula(d)

The independent copula in dimension $d$ has distribution function

$$C(\mathbf{x})=\prod _{i=1}^d{x}_i.$$

It is Archimedean with generator $\psi (s)=e^{-s}$.

References:

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

source

Copulas.InvGaussianCopula Type

InvGaussianGenerator{T}, InvGaussianCopula{d, 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.InvGaussianGenerator Type

InvGaussianGenerator{T}, InvGaussianCopula{d, 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.JoeCopula Type

JoeGenerator{T}, JoeCopula{d, 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.JoeGenerator Type

JoeGenerator{T}, JoeCopula{d, 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.LiouvilleCopula Type

LiouvilleCopula{d}(G::Generator, α)
LiouvilleCopula(G::Generator, α)

Liouville copula generated by G with positive Dirichlet parameters α. Writing α₀ = sum(α), its underlying Liouville vector is R * D, where R ∼ 𝒲₋₁(G, α₀) and D ∼ Dirichlet(α) are independent. The copula is the survival copula of R * D; in particular, α = ones(d) recovers the Archimedean copula generated by G.

For a general generator, every positive real parameter vector is supported when ceil(sum(α)) <= max_monotony(G). A 𝒲(R, source_order) generator directly supports every sum(α) <= source_order, without rounding. Integer-valued orders retain their specialized Williamson inverse methods; other orders use exact beta reductions. The radial R may be any supported non-negative univariate distribution. When α == ones(d), the resulting LiouvilleCopula is exactly the Archimedean copula generated by G; evaluation uses that identity while the concrete Liouville family type is retained.

Sampling uses the radial-Dirichlet representation. Density and distribution evaluation follow Distributions.jl; the bivariate CDF uses a one-dimensional radial/Beta expectation, while higher dimensions integrate a stick-breaking representation of the Dirichlet direction. Selecting dimensions keeps G and the corresponding entries of α, so the required lower order is recovered without changing the model representation.

Conditioning also preserves the Liouville family. When G has a frailty, both integer and non-integer conditioned orders use its exact power-exponentially tilted posterior distribution. Otherwise, integer-valued sums reuse TiltedGenerator and non-integer sums use an exact conditional-radial representation. These paths provide conditional distributions and the Rosenblatt and inverse Rosenblatt transforms without differentiating the Liouville CDF numerically.

See also the documentation example “Liouville copulas with real Dirichlet parameters”.

source

Copulas.LogCopula Type

LogTail{T}, LogCopula{d,T}

LogCopula{d}(θ)
LogCopula(d, θ)

Logistic (Gumbel-Hougaard) extreme-value copula in dimension d ≥ 2, with θ ∈ [1, ∞]. Its stable tail dependence function is

$$\ell (x_1,\dots ,x_d)={\left(\sum _{i=1}^d{x}_i^{\theta }\right)}^{1/\theta }.$$

For d = 2 this is the usual logistic extreme-value model and is equivalent to GumbelCopula(2, θ). The same mathematical tail is used in every supported dimension, while dimension two retains specialized analytic kernels.

Special cases:

• θ = 1 represents IndependentCopula(d).

• θ = ∞ represents MCopula(d).

References:

• [47] Tawn, J. A. (1988). Bivariate extreme value theory: models and estimation. Biometrika, 75(3), 397-415.

source

Copulas.LogTail Type

LogTail{T}, LogCopula{d,T}

LogCopula{d}(θ)
LogCopula(d, θ)

Logistic (Gumbel-Hougaard) extreme-value copula in dimension d ≥ 2, with θ ∈ [1, ∞]. Its stable tail dependence function is

$$\ell (x_1,\dots ,x_d)={\left(\sum _{i=1}^d{x}_i^{\theta }\right)}^{1/\theta }.$$

For d = 2 this is the usual logistic extreme-value model and is equivalent to GumbelCopula(2, θ). The same mathematical tail is used in every supported dimension, while dimension two retains specialized analytic kernels.

Special cases:

• θ = 1 represents IndependentCopula(d).

• θ = ∞ represents MCopula(d).

References:

• [47] Tawn, J. A. (1988). Bivariate extreme value theory: models and estimation. Biometrika, 75(3), 397-415.

source

Copulas.MCopula Type

MCopula(d)

The upper Fréchet–Hoeffding bound is the copula with the largest value among all copulas; it corresponds to comonotone random vectors. For any copula $C$ and all $\mathbf{u}\in [0,1{]}^d$,

$$W(\mathbf{u})\le C(\mathbf{u})\le M(\mathbf{u}).$$

Both Fréchet–Hoeffding bounds are Archimedean copulas.

References:

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

source

Copulas.MOCopula Type

MOTail{T}, MOCopula{d,T}

MOCopula{2}(λ₁, λ₂, λ₁₂)
MOCopula(2, λ₁, λ₂, λ₁₂)
MOCopula{d}(λ::AbstractVector)
MOCopula(d, λ::AbstractVector)
MOCopula(λ::AbstractVector)

Marshall-Olkin extreme-value family.

The bivariate parameterization uses private-shock intensities λ₁, λ₂ ≥ 0 and common-shock intensity λ₁₂ ≥ 0.

The multivariate representation assigns one nonnegative shock intensity λ_S to every nonempty subset S ⊆ {1,…,d}. Therefore λ has length 2^d-1, ordered by subset cardinality and then lexicographically. If only λ is supplied, the dimension is inferred from its length.

With

$$r_i=\sum _{S\ni i}{\lambda }_S,$$

the stable tail dependence function is

$$\ell (x)=\sum _{\varnothing \ne S}\underset{i\in S}{max}\left(\frac{{\lambda }_S}{r_i}{x}_i\right).$$

Every margin must have positive total shock rate. Multiplying all shock intensities by the same positive constant leaves the copula unchanged.

References:

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

source

Copulas.MOTail Type

MOTail{T}, MOCopula{d,T}

MOCopula{2}(λ₁, λ₂, λ₁₂)
MOCopula(2, λ₁, λ₂, λ₁₂)
MOCopula{d}(λ::AbstractVector)
MOCopula(d, λ::AbstractVector)
MOCopula(λ::AbstractVector)

Marshall-Olkin extreme-value family.

The bivariate parameterization uses private-shock intensities λ₁, λ₂ ≥ 0 and common-shock intensity λ₁₂ ≥ 0.

The multivariate representation assigns one nonnegative shock intensity λ_S to every nonempty subset S ⊆ {1,…,d}. Therefore λ has length 2^d-1, ordered by subset cardinality and then lexicographically. If only λ is supplied, the dimension is inferred from its length.

With

$$r_i=\sum _{S\ni i}{\lambda }_S,$$

the stable tail dependence function is

$$\ell (x)=\sum _{\varnothing \ne S}\underset{i\in S}{max}\left(\frac{{\lambda }_S}{r_i}{x}_i\right).$$

Every margin must have positive total shock rate. Multiplying all shock intensities by the same positive constant leaves the copula unchanged.

References:

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

source

Copulas.MixedCopula Type

MixedTail{T}, MixedCopula{d,T}

MixedCopula{d}(θ)
MixedCopula(d, θ)

Mixed extreme-value model with θ ∈ [0,1].

In dimension two its Pickands dependence function is

$$A(t)=1-\theta t(1-t).$$

The original bivariate model is described by Tawn [47].

For d ≥ 2, Copulas.jl uses the dimension-free extension

$${\ell }_{\mathrm{Mixed},\theta }(x)=(1-\theta )\sum _{i=1}^d{x}_i+\theta ,{\ell }_{\mathrm{Galambos},1}(x).$$

This is a convex combination of the independence STDF and the multivariate Galambos STDF with parameter one, hence it is a valid STDF in every supported dimension. In d=2 it reduces exactly to the historical Mixed Pickands model.

Copulas.jl implementation derivation

The cited Tawn paper supports the original bivariate Mixed family and [48] supports the negative-logistic component. The dimension-free convex-combination identity above is the extension derived and used in Copulas.jl; it is not attributed here as a formula from either source.

Special case:

• θ = 0 represents IndependentCopula(d).

source

Copulas.MixedTail Type

MixedTail{T}, MixedCopula{d,T}

MixedCopula{d}(θ)
MixedCopula(d, θ)

Mixed extreme-value model with θ ∈ [0,1].

In dimension two its Pickands dependence function is

$$A(t)=1-\theta t(1-t).$$

The original bivariate model is described by Tawn [47].

For d ≥ 2, Copulas.jl uses the dimension-free extension

$${\ell }_{\mathrm{Mixed},\theta }(x)=(1-\theta )\sum _{i=1}^d{x}_i+\theta ,{\ell }_{\mathrm{Galambos},1}(x).$$

This is a convex combination of the independence STDF and the multivariate Galambos STDF with parameter one, hence it is a valid STDF in every supported dimension. In d=2 it reduces exactly to the historical Mixed Pickands model.

Copulas.jl implementation derivation

The cited Tawn paper supports the original bivariate Mixed family and [48] supports the negative-logistic component. The dimension-free convex-combination identity above is the extension derived and used in Copulas.jl; it is not attributed here as a formula from either source.

Special case:

• θ = 0 represents IndependentCopula(d).

source

Copulas.NestedArchimedeanCopula Type

NestedArchimedeanCopula{d, TG}

A nested (hierarchical) Archimedean copula: an outer Archimedean Generator acting on a mix of bare coordinates and inner Archimedean sub-copulas, each occupying its own block of dimensions. With a single outer generator over inner copulas $C_1,\dots ,C_m$ on disjoint coordinate blocks $I_1,\dots ,I_m$ (and possibly some bare coordinates attached directly to the root), the CDF is

$$C(\mathbf{u})={\varphi }_0(\sum _{i\in \text{root leaves}}{\varphi }_0^{-1}(u_i)+\sum _{k=1}^m{\varphi }_0^{-1}(C_k({\mathbf{u}}_{I_k}))),$$

where ${\varphi }_0$ is the outer generator and each child $C_k$ is itself an Archimedean (or nested Archimedean) copula. The construction nests to arbitrary depth.

Constructor

NestedArchimedeanCopula(G::Generator; leaves = Int[], children = [])

• G — the outer generator ${\varphi }_0$.

• leaves — dimension indices of bare coordinates attached directly to G.

• children — inner sub-copulas. Each entry is either

  • a sub-copula (an ArchimedeanCopula or a NestedArchimedeanCopula, so trees nest to arbitrary depth), which is auto-placed on the next free block of dimensions in declaration order, or

  • a Pair sub_copula => dims, which places the child on the explicit dimension indices dims.

The bare leaves and the children's dimension blocks must together tile 1:d exactly (no gaps, no overlaps).

A purely flat declaration (only leaves, no children) returns the package's native ArchimedeanCopula so its fast specialised density is used; only genuinely nested declarations build a NestedArchimedeanCopula. The legacy positional form NestedArchimedeanCopula(G, children) (children in consecutive blocks, no root leaves) is also supported.

The constructor does not check the nesting condition: the caller is responsible for supplying a parameter combination for which the nested construction is a valid copula (for same-family nestings this means the inner generator is at least as dependent as the outer one).

Density and precision

The (log-)density is computed via Faà di Bruno's formula / partial Bell polynomials over the generator tree. The recursion is generic in the value type: logpdf on Float64 coordinates works out of the box, while passing BigFloat (or Double64) coordinates carries that precision through the whole recursion — recommended for adversarial high-dimensional or deep-tail inputs where the alternating-sign Faà di Bruno sum can lose Float64 precision.

Partial-observation likelihood

Lower-tail partial observation is an emergent capability of the standard condition + subsetdims framework — there is no bespoke likelihood function. For an observed set $O$ and a lower-tail set $C$, the likelihood factorises as the "gist recipe"

logpdf(subsetdims(X, O), x_O) + logcdf(condition(X, O, x_O), x_C)

(on the SklarDist X = SklarDist(C, margins)), which equals the observed-marginal densities times the mixed partial of the nested CDF over the observed coordinates. The subsetdims/condition specialisations for this type route both factors through the Faà di Bruno tree walk; the denominator $c_O$ cancels, reproducing the raw mixed partial.

Right-censored coordinates use the same recipe after flipping the censored coordinates with SurvivalCopula: on the copula scale, evaluate the conditional lower tail of SurvivalCopula(C, censored_dims) at 1 .- u_C.

Example

using Copulas: ClaytonGenerator   # generator types are not exported

# outer Clayton(2) over two inner Clayton panels on dims 1:2 and 3:4
C = NestedArchimedeanCopula(ClaytonGenerator(2.0);
        children = [ClaytonCopula(2, 5.0), ClaytonCopula(2, 6.0)])
logpdf(C, [0.3, 0.5, 0.4, 0.6])

# lower-tail likelihood with dim 2 partially observed (observed O = {1,3,4}, C = {2}):
S = SklarDist(C, ntuple(_ -> Exponential(1.0), 4))
x = [0.7, 0.3, 0.5, 0.9]
logpdf(subsetdims(S, (1, 3, 4)), x[[1, 3, 4]]) +
    logcdf(condition(S, (1, 3, 4), x[[1, 3, 4]]), x[2])

# right-censored dim 2 on the copula scale:
u = [cdf(S.m[i], x[i]) for i in 1:4]
Cs = SurvivalCopula(C, (2,))
logpdf(subsetdims(C, (1, 3, 4)), u[[1, 3, 4]]) +
    logcdf(condition(Cs, (1, 3, 4), u[[1, 3, 4]]), 1 - u[2])

The density and the partial-observation likelihood follow the algorithm of Yang & Li (arXiv:2605.23134), computed via Faà di Bruno's formula / partial Bell polynomials over the generator tree.

References:

• Yang, C. & Li, D. "Archimedean Copula Inference via Taylor-Mode AD." arXiv:2605.23134 (2026). https://arxiv.org/abs/2605.23134

source

Copulas.PlackettCopula Type

PlackettCopula{d, P}

Fields: - θ::Real - parameter

Constructor

PlackettCopula(θ)

The Plackett copula is parameterized by $\theta >0$ and is defined by

$$C_{\theta }(u,v)=\frac{[1+(\theta -1)(u+v)]-\sqrt{[1+(\theta -1)(u+v){]}^2-4uv\theta (\theta -1)}}{2(\theta -1)}$$

and for $\theta =1$ we have $C_1(u,v)=uv$.

Special cases:

• θ = 0: WCopula (lower Fréchet–Hoeffding bound)

• θ = 1: IndependentCopula

• θ = ∞: MCopula (upper Fréchet–Hoeffding bound)

These values retain the concrete PlackettCopula family type.

References:

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

• [75] Johnson, Mark E. Multivariate statistical simulation: A guide to selecting and generating continuous multivariate distributions. Vol. 192. John Wiley & Sons, 1987. Page 193.

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

source

Copulas.RafteryCopula Type

RafteryCopula{d, P}

Fields: - θ::Real - parameter

Constructor

RafteryCopula(d, θ)

The multivariate Raftery copula of dimension d is parameterized by $\theta \in [0,1]$.

$$C_{\theta }(\mathbf{u})=u_{(1)}+\frac{(1-\theta )(1-d)}{1-\theta -d}{\left(\prod _{j=1}^d{u}_j\right)}^{\frac{1}{1-\theta }}-\sum _{i=2}^d\frac{\theta (1-\theta )}{(1-\theta -i)(2-\theta -i)}{\left(\prod _{j=1}^{i-1}{u}_{(j)}\right)}^{\frac{1}{1-\theta }}{u}_{(i)}^{\frac{2-\theta -i}{1-\theta }}$$

where $u_{(1)},\dots ,u_{(d)}$ denote the order statistics of $u_1,\dots ,u_d$. More details about Multivariate Raftery Copula are found in the references below.

Special cases:

• When θ = 0, it is the IndependentCopula.

• When θ = 1, it is the the Fréchet upper bound

References:

• [77] Saali, T., M. Mesfioui, and A. Shabri, 2023: Multivariate Extension of Raftery Copula. Mathematics, 11, 414, https://doi.org/10.3390/math11020414.

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

source

Copulas.SklarDist Type

SklarDist{CT,TplMargins}

Fields:

• C::CT - The copula

• m::TplMargins - a Tuple representing the marginal distributions

Constructor

SklarDist(C,m)

Construct a joint distribution via Sklar's theorem from marginals and a copula. See Sklar's theorem:

Theorem - Sklar 1959

For every random vector $\mathit{X}$, there exists a copula $C$ such that

$\mathrm{\forall }\mathit{x}\in {\mathbb{R}}^d,F(\mathit{x})=C(F_1(x_1),...,F_d(x_d)).$ The copula $C$ is uniquely determined on $\mathrm{Ran}(F_1)\times ...\times \mathrm{Ran}(F_d)$, where $\mathrm{Ran}(F_i)$ denotes the range of the function $F_i$. In particular, if all marginals are absolutely continuous, $C$ is unique.

The resulting random vector follows the Distributions.jl API (rand/cdf/pdf/logpdf). A fit method is also provided. Example:

using Copulas, Distributions, Random
X₁ = Gamma(2,3)
X₂ = Pareto()
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

simu = rand(D,1000) # Generate a dataset

# You may estimate a copula using the `fit` function:
D̂ = fit(SklarDist{ClaytonCopula,Tuple{Gamma,Normal,LogNormal}}, simu)

References:

• [9] Sklar, M. (1959). Fonctions de répartition à n dimensions et leurs marges. In Annales de l'ISUP (Vol. 8, No. 3, pp. 229-231).

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

source

Copulas.SurvivalCopula Type

SurvivalCopula(C, flips)
SurvivalCopula{d,CT}

Construct the survival (flipped) version of a copula by flipping the arguments at the given indices.

The ergonomic constructor SurvivalCopula(C, flips) accepts the indices to flip:

SurvivalCopula(ClaytonCopula(4, θ), (2,3))

The flip pattern is stored in the object rather than its type, so distinct rotations of the same copula share one concrete type.

For a copula C in dimension d and indices i₁, ..., iₖ ∈ 1:d, the survival copula flips the corresponding arguments:

$$S(u_1,\dots ,u_d)=C(v_1,\dots ,v_d),v_j=\{\begin{array}{ll}1-u_j& j\in \text{flips}\\ u_j& \text{otherwise}\end{array}$$

Notes:

• In the bivariate case, this includes the usual 90/180/270-degree "rotations" of a copula family.

• The resulting object is handled like the base copula: same API (cdf, pdf/logpdf, rand, fit) and uniform marginals in $[0,1{]}^d$.

References:

• [3] Nelsen (2006), An introduction to copulas.

source

Copulas.TCopula Type

TCopula{d, Tν, MT}

Fields:

• df::Tν — degrees of freedom

• Σ::MT — correlation matrix

Constructor

TCopula(df, Σ)
TCopula{d}(df, Σ)

The Student t copula is the copula of a multivariate Student t distribution. It is defined by

$$C(\mathbf{x};\nu ,\mathbf{\Sigma })=F_{\nu ,\mathrm{\Sigma }}(F_{\nu ,\mathrm{\Sigma },1}^{-1}(x_1),\dots ,F_{\nu ,\mathrm{\Sigma },d}^{-1}(x_d)),$$

where $F_{\nu ,\mathrm{\Sigma }}$ is the cdf of a centered multivariate t with correlation $\mathrm{\Sigma }$ and $\nu$ degrees of freedom.

Example usage:

C = TCopula(2, Σ)
u = rand(C, 1000)
pdf(C, u); cdf(C, u)
Ĉ = fit(TCopula, u)

References:

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

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 concrete tail must implement either A or ℓ; each representation is derived from the other by homogeneity.

• A(tail::Tail, ω::NTuple{d,Real}) — Pickands function on the simplex \Delta_{d-1}. (For d=2, a convenience A(tail::Tail, 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.TawnCopula Type

TawnCopula{d}(α, weights)
TawnCopula(d, α, weights)
TawnCopula{d}(dep, asy)
TawnCopula(d, dep, asy)

Construct a Tawn asymmetric-logistic extreme-value copula.

TawnCopula{d}(α, weights) is a convenience submodel with one full-set logistic component plus singleton remainders.

TawnCopula(d, dep, asy) exposes the full subset model. It requires one dependence parameter for each non-singleton subset, length(dep) = 2^d-d-1, and one asymmetry-weight vector for each nonempty subset, length(asy) = 2^d-1. The weights involving each margin must sum to one.

source

Copulas.TawnTail Type

TawnTail(d, dep, asy)
TawnTail(α, weights)

Multivariate asymmetric-logistic stable tail dependence function. The full subset representation follows Tawn's multivariate extreme-value construction [45]:

$$\ell (x)=\sum _{\varnothing \ne C\subseteq \{1,\dots ,d\}}{[\sum _{i\in C}({\beta }_{i,C}{x}_i{)}^{{\alpha }_C}]}^{1/{\alpha }_C},$$

with α_C ≥ 1, β_{i,C} ≥ 0, β_{i,C}=0 for i ∉ C, and

$$\sum _{C\ni i}{\beta }_{i,C}=1$$

for every margin.

TawnTail(d, dep, asy) exposes the full subset model. TawnTail(α, weights) is a Copulas.jl convenience parameterization with one full-set logistic component plus singleton remainders; it is a structured submodel of the same valid Tawn representation, not a separate literature family.

References:

• [47] for the bivariate precursor.

• [45] for the multivariate model.

source

Copulas.WCopula Type

WCopula

The lower Fréchet–Hoeffding bound is the copula with the smallest value among all copulas. Note that $W$ is a proper copula only when $d=2$; for $d>2$ it remains the pointwise lower bound but is not itself a copula. For any copula $C$ and all $\mathbf{u}\in [0,1{]}^d$,

$$W(\mathbf{u})\le C(\mathbf{u})\le M(\mathbf{u}).$$

Both Fréchet–Hoeffding bounds are Archimedean copulas.

References:

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

source

Copulas.WilliamsonGenerator Type

𝒲{TX, TO} (alias WilliamsonGenerator{TX, TO})

Fields:

• X::TX – a random variable that represents its Williamson d-transform

• order::TO – the order of the Williamson transform

The type parameter TO is the numeric type of the order, not its value.

Constructor

WilliamsonGenerator(X::Distributions.UnivariateDistribution, d)
𝒲(X::Distributions.UnivariateDistribution,d)
WilliamsonGenerator(atoms::AbstractVector, weights::AbstractVector, d)
𝒲(atoms::AbstractVector, weights::AbstractVector, d)

The 𝒲 type (also available as WilliamsonGenerator) constructs a d-monotonous archimedean generator from a positive random variable X::Distributions.UnivariateDistribution. The transformation is implemented fully generically in the package.

For a univariate non-negative random variable $X$, with cumulative distribution function $F$ and a positive real order $d$, 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 a d-monotone archimedean generator, able to generate archimedean copulas in dimensions up to $d$. Our implementation provides this through the Generator interface: the function $\varphi$ can be accessed by

G = WilliamsonGenerator(X, d)
ϕ(G,t)

Note that you'll always have:

max_monotony(WilliamsonGenerator(X,d)) == d

Special case (finite-support discrete X)

• If X isa Distributions.DiscreteUnivariateDistribution and support(X) is finite, or if you pass directly atoms and weights to the constructor, the produced generator is piecewise-polynomial ϕ(t) = ∑_j w_j · (1 − t/r_j)_+^(d−1) matching the Williamson transform of a discrete radial law. It has specialized methods.

• For infinite-support discrete distributions or when the support is not accessible as a finite iterable, the standard WilliamsonGenerator is constructed.

References:

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

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

source

Copulas.tEVCopula Type

tEVTail{T,P}, tEVCopula{d,T,P}

tEVCopula{d}(ν, ρ)
tEVCopula(d, ν, ρ)
tEVCopula{d}(ν, R)
tEVCopula(d, ν, R)

Extremal-t extreme-value copula with degrees of freedom ν > 0.

tEVCopula(d, ν, ρ) uses an exchangeable correlation matrix with common off-diagonal correlation ρ. For a non-degenerate d-dimensional model,

$$-\frac{1}{d-1}<\rho <1.$$

tEVCopula{d}(ν, R) uses a general correlation matrix R. R must be d×d, finite, symmetric, have unit diagonal, and be strictly positive definite in the non-degenerate general representation. Scalar and matrix parameters are stored by the same tEVTail type. A valid 2×2 matrix retains its matrix representation while the specialized bivariate analytic kernel recovers ρ from its off-diagonal entry.

For d = 2, the Pickands dependence function is

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

where

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

Special case:

• ρ = 1 represents MCopula(d).

References:

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

source

Copulas.tEVTail Type

tEVTail{T,P}, tEVCopula{d,T,P}

tEVCopula{d}(ν, ρ)
tEVCopula(d, ν, ρ)
tEVCopula{d}(ν, R)
tEVCopula(d, ν, R)

Extremal-t extreme-value copula with degrees of freedom ν > 0.

tEVCopula(d, ν, ρ) uses an exchangeable correlation matrix with common off-diagonal correlation ρ. For a non-degenerate d-dimensional model,

$$-\frac{1}{d-1}<\rho <1.$$

tEVCopula{d}(ν, R) uses a general correlation matrix R. R must be d×d, finite, symmetric, have unit diagonal, and be strictly positive definite in the non-degenerate general representation. Scalar and matrix parameters are stored by the same tEVTail type. A valid 2×2 matrix retains its matrix representation while the specialized bivariate analytic kernel recovers ρ from its off-diagonal entry.

For d = 2, the Pickands dependence function is

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

where

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

Special case:

• ρ = 1 represents MCopula(d).

References:

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

source

Copulas.𝒲 Type

𝒲{TX, TO} (alias WilliamsonGenerator{TX, TO})

Fields:

• X::TX – a random variable that represents its Williamson d-transform

• order::TO – the order of the Williamson transform

The type parameter TO is the numeric type of the order, not its value.

Constructor

WilliamsonGenerator(X::Distributions.UnivariateDistribution, d)
𝒲(X::Distributions.UnivariateDistribution,d)
WilliamsonGenerator(atoms::AbstractVector, weights::AbstractVector, d)
𝒲(atoms::AbstractVector, weights::AbstractVector, d)

The 𝒲 type (also available as WilliamsonGenerator) constructs a d-monotonous archimedean generator from a positive random variable X::Distributions.UnivariateDistribution. The transformation is implemented fully generically in the package.

For a univariate non-negative random variable $X$, with cumulative distribution function $F$ and a positive real order $d$, 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 a d-monotone archimedean generator, able to generate archimedean copulas in dimensions up to $d$. Our implementation provides this through the Generator interface: the function $\varphi$ can be accessed by

G = WilliamsonGenerator(X, d)
ϕ(G,t)

Note that you'll always have:

max_monotony(WilliamsonGenerator(X,d)) == d

Special case (finite-support discrete X)

• If X isa Distributions.DiscreteUnivariateDistribution and support(X) is finite, or if you pass directly atoms and weights to the constructor, the produced generator is piecewise-polynomial ϕ(t) = ∑_j w_j · (1 − t/r_j)_+^(d−1) matching the Williamson transform of a discrete radial law. It has specialized methods.

• For infinite-support discrete distributions or when the support is not accessible as a finite iterable, the standard WilliamsonGenerator is constructed.

References:

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

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

source

Copulas.𝒲₋₁ Type

𝒲₋₁(G::Generator, d::Real)

Computes the inverse Williamson transform of the monotone Archimedean generator G at a positive real order d.

For an integer order, the generic implementation uses the classical inversion formula below, while more specific generator families may provide an exact or faster radial distribution. For non-integer d, it first inverts at n = ceil(Int, d) and returns the law of Rₙ * B, where B ~ Beta(d, n-d) is independent of Rₙ = 𝒲₋₁(G, n). Consequently, ceil(d) <= max_monotony(G) is required. Integer-valued orders retain the specialized integer dispatch path. If G = 𝒲(X, source_order) retains its source radial, every d <= source_order is instead reduced directly from X; the ceiling condition is then unnecessary.

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.EmpiricalGenerator Method

EmpiricalGenerator(u::AbstractMatrix; pseudo_values=true)

Nonparametric Archimedean generator fit via inversion of the empirical Kendall distribution.

This function returns a WilliamsonGenerator{TX, TO} whose underlying distribution TX is a Distributions.DiscreteNonParametric, rather than a separate struct. The returned object still implements all optimized methods (ϕ, derivatives, inverses) via specialized dispatch on WilliamsonGenerator{<:DiscreteNonParametric}.

Usage

G = EmpiricalGenerator(u)

where u::AbstractMatrix is a d×n matrix of pseudo-observations. Pass pseudo_values=false to rank-transform raw observations first.

Notes

• The recovered discrete radial support is rescaled so its largest atom equals 1 (scale is not identifiable).

• We keep the old documentation entry point for backward compatibility; existing code that relied on the EmpiricalGenerator type should instead treat the result as a Generator.

References

• [14]

• [30]

• [38] Genest, Neslehova and Ziegel (2011), Inference in Multivariate Archimedean Copula Models

source

Copulas.Nataf Method

Nataf(margins, R; nodes=32)
Nataf(margins, ρ::Real; nodes=32)

Nataf correction [20, 21]: compute the correlation matrix for a GaussianCopula such that the SklarDist built from it and the given margins has Pearson correlation matrix R.

A Gaussian copula with parameter ${\rho }_0$ induces, once the margins are applied, a Pearson correlation that depends on the shape of the margins and equals ${\rho }_0$ only when the margins are themselves Gaussian. Matching a Pearson target $\rho$ therefore means inverting, for each pair of margins,

$$\rho ({\rho }_0)=\mathbb{E}[g_i(Z_i)g_j(Z_j)],(Z_i,Z_j)\sim \mathcal{N}(0,\left(\begin{array}{cc}1& {\rho }_0\\ {\rho }_0& 1\end{array}\right)),$$

where $g_k(z)=(F_k^{-1}(\mathrm{\Phi }(z))-{\mu }_k)/{\sigma }_k$ is the standardized margin pulled back to standard normal space. The expectation is evaluated with a product Gauss-Hermite rule and, since it is increasing in ${\rho }_0$, inverted by a bracketed root search.

Arguments

• margins: a Tuple or vector of univariate distributions, each with finite mean and finite positive standard deviation.

• R: the target Pearson correlation matrix (or a single target correlation ρ when there are exactly two margins, in which case the corrected scalar is returned).

• nodes: number of Gauss-Hermite nodes per dimension. The default is accurate to about 1e-8 for well-behaved margins; heavy-tailed or strongly skewed margins converge more slowly and want more nodes.

Zero targets map to exactly zero. Pairs whose induced correlation is known analytically skip the quadrature and use the closed form instead: Normal-Normal pairs (the identity, so Gaussian margins reproduce R exactly), LogNormal-LogNormal pairs (${\rho }_0=\log (1+\rho \sqrt{(e^{s_i^2}-1)(e^{s_j^2}-1)})/(s_i{s}_j)$), and all pairs among Normal, LogNormal, and Uniform margins. Because non-Gaussian margins cannot attain every Pearson correlation (the Fréchet-Hoeffding bounds), a target outside the attainable range throws an error naming the pair and the range. Targets on the attainable boundary snap just inside $\pm 1$, so the result stays usable by the GaussianCopula constructor; the corrected matrix is nevertheless not guaranteed to stay positive definite for extreme targets in dimension $d>2$, and the GaussianCopula constructor validates it.

The computation is type-generic and follows the precision of the inputs: BigFloat targets or margin parameters yield BigFloat results, at full precision on the closed-form paths. Two caveats on the generic quadrature path: its nodes are computed in Float64, and it requires margins whose quantile accepts the working type — some quantiles in Distributions.jl (e.g. Gamma, Beta) are implemented for machine floats only and throw a MethodError for BigFloat arguments.

Example

using Copulas, Distributions, Statistics

m  = (LogNormal(0, 0.8), Gamma(1, 2), Beta(1, 2))
R0 = [1 0.7 0.3; 0.7 1 0.5; 0.3 0.5 1]

D = SklarDist(GaussianCopula(Nataf(m, R0)), m)
cor(rand(D, 10^6)') # ≈ R0, while GaussianCopula(R0) directly would miss the target.

References:

• [20] Nataf, A. (1962). Détermination des distributions de probabilités dont les marges sont données.

• [21] Liu, P.-L., & Der Kiureghian, A. (1986). Multivariate distribution models with prescribed marginals and covariances.

source

Copulas.condition Method

    condition(C::Copula{D}, js, u_js)
    condition(X::SklarDist, js, x_js)

Construct conditional distributions with respect to a copula, either on the uniform scale (when passing a Copula) or on the original data scale (when passing a SklarDist).

Arguments

• C::Copula{D}: D-variate copula

• X::SklarDist: joint distribution with copula X.C and marginals X.m

• js: indices of conditioned coordinates (tuple, NTuple, or vector)

• u_js: values in [0,1] for U_js (when conditioning a copula)

• x_js: values on original scale for X_js (when conditioning a SklarDist)

• j, u_j, x_j: 1D convenience overloads for the common p = 1 case

Returns

• If the number of remaining coordinates d = D - length(js) is 1:

  • condition(C, js, u_js) returns a Distortion on [0,1] describing U_i | U_js = u_js.

  • condition(X, js, x_js) returns an unconditional univariate distribution for X_i | X_js = x_js, computed as the push-forward D(X.m[i]) where D = condition(C, js, u_js) and u_js = cdf.(X.m[js], x_js).

• If d > 1:

  • condition(C, js, u_js) returns the conditional joint distribution on the uniform scale as a SklarDist(ConditionalCopula, distortions).

  • condition(X, js, x_js) returns the conditional joint distribution on the original scale as a SklarDist with copula ConditionalCopula(C, js, u_js) and appropriately distorted marginals D_k(X.m[i_k]).

Notes

• For best performance, pass js and u_js as NTuple to keep p = length(js) known at compile time. The specialized method condition(::Copula{2}, j, u_j) exploits this for the common D = 2, d = 1 case.

• Specializations are provided for many copula families (Independent, Gaussian, t, Archimedean, several bivariate families). Others fall back to an automatic differentiation based construction.

• This function returns the conditional joint distribution H_{I|J}(· | u_J). The “conditional copula” is ConditionalCopula(C, js, u_js), i.e., the copula of that conditional distribution.

source

Copulas.inverse_rosenblatt Method

inverse_rosenblatt(C::Copula, u)

Computes the inverse rosenblatt transform associated to the copula C on the vector u. Formally, assuming that U ∼ Π, the independence copula, the result should be distributed as C. Also look at rosenblatt(C, u) for the inverse transformation. The interface proposes faster versions for matrix inputs u.

Generic inverse Rosenblatt using conditional distortions: U₁ = S₁, U_k = H_{k|1:(k-1)}^{-1}(S_k | U₁:U_{k-1}). Specialized families may provide faster overrides.

References:

• [13] Rosenblatt, M. (1952). Remarks on a multivariate transformation. Annals of Mathematical Statistics, 23(3), 470-472.

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

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

source

Copulas.pseudos Method

pseudos(sample)

Compute the pseudo-observations of a multivariate sample. Note that the sample has to be given in wide format (d,n), where d is the dimension and n the number of observations.

Warning: the order used is ordinal ranking like https://en.wikipedia.org/wiki/Ranking#Ordinal_ranking_.28.221234.22_ranking.29, see StatsBase.ordinalrank for the ordering we use. If you want more flexibility, checkout NormalizeQuantiles.sampleranks.

source

Copulas.rosenblatt Method

rosenblatt(C::Copula, u)

Computes the rosenblatt transform associated to the copula C on the vector u. Formally, assuming that U ∼ C, the result should be uniformely distributed on the unit hypercube. The importance of this transofrmation comes from its bijectivity: inverse_rosenblatt(C, rand(d)) is equivalent to rand(C). The interface proposes faster versions for matrix inputs u.

Generic Rosenblatt transform using conditional distortions: S₁ = U₁, S_k = H_{k|1:(k-1)}(U_k | U₁:U_{k-1}). Specialized families may provide faster overrides.

• [13] Rosenblatt, M. (1952). Remarks on a multivariate transformation. Annals of Mathematical Statistics, 23(3), 470-472.

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

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

source

Copulas.subsetdims Method

subsetdims(C::Copula, dims::NTuple{p, Int})
subsetdims(D::SklarDist, dims)

Return a new copula or Sklar distribution corresponding to the subset of dimensions specified by dims.

Arguments

• C::Copula: The original copula object.

• D::SklarDist: The original Sklar distribution.

• dims::NTuple{p, Int}: Tuple of indices representing the dimensions to keep.

Returns

• A SubsetCopula or a new SklarDist object corresponding to the selected dimensions. If p == 1, returns a Uniform distribution or the corresponding marginal.

Details

This function extracts the dependence structure among the specified dimensions from the original copula or Sklar distribution. Specialized methods exist for some copula types to ensure efficiency and correctness.

source

References

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

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

4. A. Sklar. Fonctions de Repartition à n Dimension et Leurs Marges. Université Paris 8, 1–3 (1959).

5. M. Rosenblatt. Remarks on a multivariate transformation. Annals of Mathematical Statistics 23, 470–472 (1952).

6. A. J. McNeil and J. Nešlehová. Multivariate Archimedean Copulas, $d$-Monotone Functions and ${\ell }_1$-Norm Symmetric Distributions. The Annals of Statistics 37, 3059–3097 (2009).

7. A. Nataf. Détermination des distributions de probabilités dont les marges sont données. Comptes Rendus de l'Académie des Sciences 255, 42–43 (1962).

8. P.-L. Liu and A. Der Kiureghian. Multivariate distribution models with prescribed marginals and covariances. Probabilistic Engineering Mechanics 1, 105–112 (1986).

9. R. E. Williamson. Multiply Monotone Functions and Their Laplace Transforms. Duke Mathematical Journal 23, 189–207 (1956).

10. C. Genest, J. Nešlehová and J. Ziegel. Inference in Multivariate Archimedean Copula Models. TEST 20, 223–256 (2011).

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

12. J. A. Tawn. Modelling multivariate extreme value distributions. Biometrika 77, 245–253 (1990).

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

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

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

16. G. Gudendorf and J. Segers. Nonparametric estimation of an extreme-value copula in arbitrary dimensions. Journal of multivariate analysis 102, 37–47 (2011).

17. G. Gudendorf and J. Segers. Nonparametric estimation of multivariate extreme-value copulas. Journal of Statistical Planning and Inference 142, 3073–3085 (2012).

18. 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.

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

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

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

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

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

24. P. Capéraà, A.-L. Fougères and C. Genest. Bivariate distributions with given extreme value attractor. Journal of Multivariate Analysis 72, 30–49 (2000).

25. A. Charpentier, A.-L. Fougères, C. Genest and J. Nešlehová. Multivariate archimax copulas. Journal of Multivariate Analysis 126, 118–136 (2014).

26. J. Segers, M. Sibuya and H. Tsukahara. The Empirical Beta Copula. Journal of Multivariate Analysis 155, 35–51 (2017).

27. A. Sancetta and S. Satchell. The Bernstein copula and its applications to modeling and approximations of multivariate distributions. Econometric theory 20, 535–562 (2004).

28. M. E. Johnson. Multivariate statistical simulation: A guide to selecting and generating continuous multivariate distributions. Vol. 192 (John Wiley & Sons, 1987).

29. C. Blier-Wong, H. Cossette and E. Marceau. Stochastic representation of FGM copulas using multivariate Bernoulli random variables. Computational Statistics & Data Analysis 173, 107506 (2022).

30. T. Saali, M. Mesfioui and A. Shabri. Multivariate extension of Raftery copula. Mathematics 11, 414 (2023).