Public API

This page lists all public docstrings exposed by the package.

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)

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:

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

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

• [52] 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)

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:

• [29] 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.BB4Copula Type

BB4Copula{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{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.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:

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

• [60] 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:

• [60] 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.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.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.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 [74] to obtain random samples.

References:

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

• [74] 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.GaussianCopula Type

GaussianCopula{d, MT}

Fields:

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

Constructors

GaussianCopula(Σ)
GaussianCopula(d, ρ)
GaussianCopula(d::Integer, ρ::Real)

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, this returns IndependentCopula(d) (same fast-path as when passing a 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 constructor returns IndependentCopula(d).

References:

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

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

PlackettCopula{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: MCopula (upper Fréchet–Hoeffding bound)

• θ = 1: IndependentCopula

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

References:

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

• [73] 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:

• [75] 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,flips}

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

Type-level encoding: The indices to flip are encoded at the type level as a tuple of integers, e.g. SurvivalCopula{4,ClaytonCopula,(2,3)}. This enables compile-time specialization and dispatch, and ensures that the flipping pattern is part of the type.

Sugar constructor: The ergonomic constructor SurvivalCopula(C, flips::Tuple) infers the type parameters from the arguments, so you can write:

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

which is equivalent to the explicit type form:

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

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, df, MT}

Fields:

• df::Int — degrees of freedom

• Σ::MT — correlation matrix

Constructor

TCopula(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.TiltedGenerator Type

TiltedGenerator(G, p, sJ) <: Generator

Archimedean generator tilted by conditioning on p components fixed at values with cumulative generator sum sJ = ∑ ϕ⁻¹(u_j). It defines

ϕ_tilt(t) = ϕ^{(p)}(sJ + t) / ϕ^{(p)}(sJ)

and higher derivatives accordingly:

ϕ_tilt^{(k)}(t) = ϕ^{(k+p)}(sJ + t) / ϕ^{(p)}(sJ)

which yields the conditional copula within the Archimedean family for the remaining d-p variables. You will get a TiltedGenerator if you condition() an archimedean copula.

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

WilliamsonGenerator{d, TX}
i𝒲{TX}

Fields:

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

The type parameter d::Int is the dimension of the transformation.

Constructor

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

The WilliamsonGenerator (alias i𝒲) allows to construct a d-monotonous archimedean generator from a positive random variable X::Distributions.UnivariateDistribution. The transformation, which is called the inverse Williamson transformation, is implemented fully generically in the package.

For a univariate non-negative random variable $X$, with cumulative distribution function $F$ and an integer $d\ge 2$, the Williamson-d-transform of $X$ is the real function supported on $[0,\mathrm{\infty }[$ given by:

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

This function has several properties:

• We have that $\varphi (0)=1$ and $\varphi (Inf)=0$

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

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

These properties makes this function what is called 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:

• [29] 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.EmpiricalGenerator Method

EmpiricalGenerator(u::AbstractMatrix)

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

This function returns a WilliamsonGenerator{TX} 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 observations (already on copula or pseudo scale).

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

• [42]

• [43]

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

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

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

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

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

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

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

6. R. E. Williamson. On multiply monotone functions and their laplace transforms (Mathematics Division, Office of Scientific Research, US Air Force, 1955).

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

8. A. J. McNeil and J. Nešlehová. Multivariate Archimedean copulas, $d$-monotone functions and ${\ell }_1$-norm symmetric distributions. Annals of Statistics 37, 3059–3097 (2009).

9. R. E. Williamson. Multiply monotone functions and their Laplace transforms. Duke Mathematical Journal 23, 189–207 (1956).

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

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

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

13. J. Segers, M. Sibuya and H. Tsukahara. The empirical beta copula. Journal of Multivariate Analysis 155, 35–51 (2017).

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

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

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

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