Public API

This page lists all public docstrings exposed by the package.

Behavioural contract

Docstrings list supported constructor calls, rather than complete concrete type signatures. For copula families that support both forms, Family{d}(args...) supplies the dimension through the type and Family(d, args...) supplies it at runtime. The former is the inference-friendly path when d is known to the compiler; this is not a blanket inference guarantee for arbitrary argument types. Additional storage parameters shown by Julia when printing a type are not constructor arguments or supported extension points unless explicitly documented. The deliberate exception is SklarDist{CopulaType,Tuple{MarginTypes...}}, whose two family selectors are a supported fitting-target syntax; this does not expose any further representation details of SklarDist.

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.

A public copula object has dimension d ≥ 2. The unique mathematical one-dimensional copula C(u)=u is represented by the ordinary univariate Uniform() distribution when marginalization or conditioning leaves one coordinate; Copulas.jl does not expose a Copula{1} model. Families may impose stronger dimension restrictions.

Area	Public operations	Guaranteed behaviour
Construction	Family{d}(parameters...), Family(d, parameters...)	Both forms select dimension d ≥ 2, 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 or a stronger dimension restriction.
Distribution	length, eltype, params, cdf, logcdf, rand	Every copula is a multivariate distribution with uniform margins (except the EmpiricalCopula) 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. A family-defined boundary value is preserved; if its formula is indeterminate (NaN) on the boundary of the unit hypercube, the public interface uses the valid density representative pdf = 0 (logpdf = -Inf).
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, given points or intervals of the conditioned coordinates, with generalized quantiles where atoms occur. A discrete observation of a SklarDist conditions on its latent interval.
Transforms	rosenblatt, inverse_rosenblatt	Vector and matrix forms are supported. Round trips hold almost surely when successive conditional CDFs are continuous and invertible on their supports; atomic conditionals of a copula need not give a bijection or a uniform forward transform. A SklarDist with discrete margins takes the distributional transform of each atom, so rosenblatt(rng, X, x) is random on atoms and inverse_rosenblatt(X, s) inverts it in law.
Dependence	τ, ρ, β, γ, ι, λₗ, λᵤ, StatsBase.corkendall, StatsBase.corspearman	Copula-level scalar summaries operate on public copulas, hence d ≥ 2. Data-level scalar τ, ρ, β, and γ likewise require at least two rows; their multivariate normalizations are degenerate at d=1. Results otherwise have the documented scalar or pairwise-matrix shape, bounds and symmetry. Closed forms and numerical fallbacks have the same contract. Parameter inversions used by fitting are internal.
Fitting, inference, and selection	fit, CopulaModel, fitted_distribution, infer, selected_model, and selection_table	Documented family/method pairs return valid point estimates. CopulaModel retains only the fitted result, original data, fitted likelihood, and replay recipe. Inference owns covariance state, while automatic selection keeps candidate comparisons separate from the winning model. Estimator registries, execution hooks, result storage, and parameter reconstruction remain internal; see the fitting interface.
Hypothesis testing	IndependenceCopulaTest, ExchangeabilityCopulaTest, RadialSymmetryCopulaTest, ExtremeValueCopulaTest, GOFCopulaTest, pvalue, teststatistic	Each procedure applies its documented statistic and calibration under its stated assumptions and returns a CopulaTest; see hypothesis testing.
Composition	SklarDist	Distribution operations, marginalization, conditioning and Rosenblatt transforms are expressed on the marginal scales. SklarDist{CopulaType,Tuple{MarginTypes...}} is additionally a supported fitting target.
Generator extension	Generator, ϕ, max_monotony	Subtyping Generator and implementing these two mathematical operations is a supported way to define a custom Archimedean generator. Optional derivative, inverse, radial, fitting, cache, and dispatch hooks remain internal.
Utilities	pseudos, measure, Nataf	Rank pseudo-observations, copula rectangle probability, and Nataf correlation correction respectively.

Distribution support and measure class

Copulas.jl follows the Distributions.jl ValueSupport terminology. In that interface, Continuous means that the support is uncountable; it does not mean that the law is absolutely continuous with respect to Lebesgue measure. Consequently, a singular copula such as the comonotone or countermonotone bound can legitimately be a ContinuousMultivariateDistribution even though it has no ordinary Lebesgue density. Copulas.jl tracks absolute continuity separately through its internal measure-style machinery and uses that distinction whenever an operation requires an ordinary density.

For the same API-simplicity reason, SklarDist keeps one multivariate Distributions.jl support supertype even though its marginals may be discrete, continuous, or mixed. In particular, a SklarDist with only discrete margins is not reflected as a DiscreteMultivariateDistribution at the Julia supertype level. Its likelihood, conditioning, sampling, and transform semantics remain discrete-aware; downstream code should rely on those documented behaviours rather than infer absolute continuity or atomicity from the historical ContinuousMultivariateDistribution supertype alone.

Numeric representation

For continuous distributions, eltype follows the Distributions.jl convention: it is the default numeric type allocated by rand. Parameterized copulas preserve or promote the numeric representation of their mathematical parameters, composite copulas promote their components, and parameter-free copulas default to Float64. Integer-like inputs may be converted to a suitable floating representation when the mathematical object requires it. rand! may instead target any compatible real-valued buffer type.

Numerical algorithms are allowed to use a wider local working type when that does not reduce the information carried by the model, for example using a Float64 backend while evaluating a Float32 parameterization. Backend limitations must not silently redefine the stored/public model representation. In particular, silently narrowing an existing floating representation (for example BigFloat to Float64) is a bug, not an accepted compatibility mode. If an operation cannot support the precision of its model or input, it must use a generic implementation or fail explicitly rather than silently discard precision.

This contract describes the 1.0 public policy, not a claim that every numerical backend already supports every Real type. Concrete violations should be reported as focused bugs so the implementation can be improved without weakening the model-level numeric contract.

Public component constructors guarantee their documented mathematical semantics and supported constructor forms. Public status does not expose undocumented fields, storage type parameters, intermediate subtype hierarchies, caches, AD backends, or numerical algorithms as extension contracts. Explicitly documented public relationships and constructor syntax remain part of the contract.

The public mathematical operations on components are documented below. Their public status describes evaluation of supported components; it does not imply that defining one operation supplies every copula capability. The current implementation machinery is described separately in the developer guide and is not part of this contract.

Copulas.AMHCopula Type

AMHGenerator(θ)
AMHCopula{d}(θ)
AMHCopula(d, θ)

The AMH Copula is parameterized by θ ∈ [-1,1]. Negative values are valid only in dimensions d ≤ max_monotony(AMHGenerator(θ)). It is an Archimedean copula with generator:

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

Special cases:

• θ = 0 gives the independence copula.

AMH covers only a modest range of dependence. Negative parameters have a parameter-dependent maximum dimension, so constructing the generator alone does not establish validity of a requested copula dimension.

See also: Generator, ArchimedeanCopula, τ, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("nelsen2006-cite-3")

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

source

Copulas.AMHGenerator Type

AMHGenerator(θ)
AMHCopula{d}(θ)
AMHCopula(d, θ)

The AMH Copula is parameterized by θ ∈ [-1,1]. Negative values are valid only in dimensions d ≤ max_monotony(AMHGenerator(θ)). It is an Archimedean copula with generator:

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

Special cases:

• θ = 0 gives the independence copula.

AMH covers only a modest range of dependence. Negative parameters have a parameter-dependent maximum dimension, so constructing the generator alone does not establish validity of a requested copula dimension.

See also: Generator, ArchimedeanCopula, τ, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("nelsen2006-cite-4")

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

source

Copulas.ArchimaxCopula Type

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

Construct an Archimax copula by combining Archimedean generator gen with stable tail dependence function tail. Let $x_i={\varphi }^{-1}(u_i)$; its CDF is

$$C(\mathbf{u})=\varphi (\ell (x_1,\dots ,x_d)).$$

Reductions

• If $\ell (x)=\sum _i{x}_i$, this is the Archimedean copula generated by gen.

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

params(::ArchimaxCopula) concatenates the parameter tuples of gen and tail. Both components must be valid in d dimensions. Smooth components generally use the generic density and bivariate sampling machinery; singular radial or spectral components retain their non-Lebesgue measure semantics. Generic fitting is currently limited to supported typed component combinations.

Example

using Copulas

C = ArchimaxCopula(2, Copulas.ClaytonGenerator(2.0),
                   Copulas.LogTail(1.5))

See also: Generator, Tail, ArchimedeanCopula, ExtremeValueCopula, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("caperaa2000-cite-3")

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

• [ DocumenterCitations.CitationSiteNode("charpentier2014-cite-1")

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

• [ DocumenterCitations.CitationSiteNode("mai2012simulating-cite-2")

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

source

Copulas.ArchimedeanCopula Type

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

Construct the d-dimensional Archimedean copula generated by G. The constructor requires d ≤ max_monotony(G). Its CDF is

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

The generic sampler uses the radial–simplex representation obtained from the inverse Williamson transform of $\varphi$. A working CDF requires an evaluable generator inverse; density and sampling additionally require the derivatives and radial law described by the generator's documented capabilities. A generator being valid in dimension d does not by itself guarantee that every numerical operation is available or stable.

Named families provide convenient constructors such as GumbelCopula{d}(θ) and GumbelCopula(d, θ). Their storage representation and alias expansion are implementation details.

A custom generator is part of the supported public API. Define a subtype of Generator and the two core methods ϕ and max_monotony:

using Copulas, Distributions

struct MyGenerator <: Copulas.Generator end
Copulas.ϕ(::MyGenerator, t) = exp(-t)
Copulas.max_monotony(::MyGenerator) = Inf
C = ArchimedeanCopula(3, MyGenerator())
cdf(C, fill(0.5, 3))

This minimal contract supports construction and the generic CDF. Density, sampling, conditioning, and transforms additionally depend on the regularity of the generator and on generic numerical derivative, inverse, and radial fallbacks. Optional specializations can improve their accuracy or speed, but those hooks are implementation machinery rather than part of the public extension contract.

For a known radial distribution use WilliamsonGenerator; for a known non-negative frailty use FrailtyGenerator. Named families provide validated parameterizations and usually more efficient formulas.

See also: Generator, ϕ, max_monotony, WilliamsonGenerator, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("williamson1956-cite-5")

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

• [ DocumenterCitations.CitationSiteNode("mcneil2009-cite-9")

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

source

Copulas.AsymGalambosCopula Type

AsymGalambosTail(α, θ₁, θ₂)
AsymGalambosTail(α, weights)
AsymGalambosTail(dep, weights₁, ..., weights_d)
AsymGalambosTail(d, dep, asy)

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

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

The family uses the subset-based negative-logistic/min-stable construction of Joe [ DocumenterCitations.CitationSiteNode("Joe1990-cite-2")

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

The canonical parameterization stores one dependence parameter for every non-singleton subset and, for every margin i, the vector (β_{i,C})_{C∋i} as a probability simplex. AsymGalambosTail(d, dep, asy) retains the historical subset-oriented input and converts it to this canonical form. AsymGalambosTail(α, weights) contains only the full-set negative-logistic component plus singleton remainders. In d=2, this is the whole family and is equivalent to the historical (α, θ₁, θ₂) form.

The full subset form can be high-dimensional in both parameter count and evaluation cost. Zero weights remove subset contributions and can place the model on a lower-dimensional or partially independent boundary.

See also: Tail, ExtremeValueCopula, ℓ, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("galambos1975order-cite-2")

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

• [ DocumenterCitations.CitationSiteNode("Joe1990-cite-3")

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

source

Copulas.AsymGalambosTail Type

AsymGalambosTail(α, θ₁, θ₂)
AsymGalambosTail(α, weights)
AsymGalambosTail(dep, weights₁, ..., weights_d)
AsymGalambosTail(d, dep, asy)

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

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

The family uses the subset-based negative-logistic/min-stable construction of Joe [ DocumenterCitations.CitationSiteNode("Joe1990-cite-4")

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

The canonical parameterization stores one dependence parameter for every non-singleton subset and, for every margin i, the vector (β_{i,C})_{C∋i} as a probability simplex. AsymGalambosTail(d, dep, asy) retains the historical subset-oriented input and converts it to this canonical form. AsymGalambosTail(α, weights) contains only the full-set negative-logistic component plus singleton remainders. In d=2, this is the whole family and is equivalent to the historical (α, θ₁, θ₂) form.

The full subset form can be high-dimensional in both parameter count and evaluation cost. Zero weights remove subset contributions and can place the model on a lower-dimensional or partially independent boundary.

See also: Tail, ExtremeValueCopula, ℓ, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("galambos1975order-cite-3")

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

• [ DocumenterCitations.CitationSiteNode("Joe1990-cite-5")

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

source

Copulas.AsymLogCopula Type

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

The model is bivariate. Its weights govern how logistic dependence is allocated to the two margins; values near zero approach independence and can make the remaining shape parameter weakly identifiable.

See also: Tail, ExtremeValueCopula, A, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("tawn1988bivariate-cite-3")

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

source

Copulas.AsymLogTail Type

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

The model is bivariate. Its weights govern how logistic dependence is allocated to the two margins; values near zero approach independence and can make the remaining shape parameter weakly identifiable.

See also: Tail, ExtremeValueCopula, A, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("tawn1988bivariate-cite-4")

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

source

Copulas.AsymMixedCopula Type

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

This polynomial Pickands model is bivariate. The admissible set is the intersection of all four inequalities above, not a rectangular parameter box; fitting or proposing parameters independently can therefore leave the valid region.

See also: Tail, ExtremeValueCopula, A, MixedTail, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("tawn1988bivariate-cite-5")

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

source

Copulas.AsymMixedTail Type

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

This polynomial Pickands model is bivariate. The admissible set is the intersection of all four inequalities above, not a rectangular parameter box; fitting or proposing parameters independently can therefore leave the valid region.

See also: Tail, ExtremeValueCopula, A, MixedTail, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("tawn1988bivariate-cite-6")

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

source

Copulas.BB10Copula Type

BB10Generator(θ, δ)
BB10Copula{d}(θ, δ)
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 },$$

The special case δ = 0 gives the independence copula.

On the independence edge, θ is not identifiable. The displayed expression also becomes a limiting formula at δ = 1; interior values are preferable for fitting when both parameters are intended to be estimated.

See also: Generator, ArchimedeanCopula, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("joe2014-cite-3")

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

source

Copulas.BB10Generator Type

BB10Generator(θ, δ)
BB10Copula{d}(θ, δ)
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 },$$

The special case δ = 0 gives the independence copula.

On the independence edge, θ is not identifiable. The displayed expression also becomes a limiting formula at δ = 1; interior values are preferable for fitting when both parameters are intended to be estimated.

See also: Generator, ArchimedeanCopula, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("joe2014-cite-4")

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

source

Copulas.BB1Copula Type

BB1Generator(θ, δ)
BB1Copula{d}(θ, δ)
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:

• δ = 1 gives the Clayton copula with parameter $\theta$.

• θ = Inf gives the upper Fréchet–Hoeffding bound.

BB1 combines Clayton- and Gumbel-type behavior and can represent dependence in both tails. The limit θ → 0⁺ gives Gumbel with parameter δ; near either one-parameter reduction, the two fitted parameters may be weakly identifiable.

See also: ClaytonGenerator, GumbelGenerator, ArchimedeanCopula, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("joe2014-cite-5")

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

source

Copulas.BB1Generator Type

BB1Generator(θ, δ)
BB1Copula{d}(θ, δ)
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:

• δ = 1 gives the Clayton copula with parameter $\theta$.

• θ = Inf gives the upper Fréchet–Hoeffding bound.

BB1 combines Clayton- and Gumbel-type behavior and can represent dependence in both tails. The limit θ → 0⁺ gives Gumbel with parameter δ; near either one-parameter reduction, the two fitted parameters may be weakly identifiable.

See also: ClaytonGenerator, GumbelGenerator, ArchimedeanCopula, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("joe2014-cite-6")

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

source

Copulas.BB2Copula Type

BB2Generator(θ, δ)
BB2Copula{d}(θ, δ)
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 }},$$

The two positive parameters control different aspects of the dependence shape; neither is a universal strength index. Very small values approach open parameter-space boundaries and can be numerically delicate, so fitted models should be compared through concordance, tail coefficients or probabilities.

See also: Generator, ArchimedeanCopula, τ, λₗ, λᵤ, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("joe2014-cite-7")

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

source

Copulas.BB2Generator Type

BB2Generator(θ, δ)
BB2Copula{d}(θ, δ)
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 }},$$

The two positive parameters control different aspects of the dependence shape; neither is a universal strength index. Very small values approach open parameter-space boundaries and can be numerically delicate, so fitted models should be compared through concordance, tail coefficients or probabilities.

See also: Generator, ArchimedeanCopula, τ, λₗ, λᵤ, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("joe2014-cite-8")

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

source

Copulas.BB3Copula Type

BB3Generator(θ, δ)
BB3Copula{d}(θ, δ)
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 }}),$$

Both parameter constraints are essential and should be enforced when optimizing. Large values can strongly concentrate probability, making logpdf preferable to raw density calculations and potentially weakening finite-sample parameter identification.

See also: Generator, ArchimedeanCopula, Distributions logpdf, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("joe2014-cite-9")

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

source

Copulas.BB3Generator Type

BB3Generator(θ, δ)
BB3Copula{d}(θ, δ)
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 }}),$$

Both parameter constraints are essential and should be enforced when optimizing. Large values can strongly concentrate probability, making logpdf preferable to raw density calculations and potentially weakening finite-sample parameter identification.

See also: Generator, ArchimedeanCopula, Distributions logpdf, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("joe2014-cite-10")

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

source

Copulas.BB4Copula Type

BB4Copula{2}(θ, δ)
BB4Copula(2, θ, δ)
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:

• [ DocumenterCitations.CitationSiteNode("joe2014-cite-11")

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

source

Copulas.BB5Copula Type

BB5Copula{2}(θ, δ)
BB5Copula(2, θ, δ)

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:

• [ DocumenterCitations.CitationSiteNode("joe2014-cite-12")

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

source

Copulas.BB6Copula Type

BB6Generator(θ, δ)
BB6Copula{d}(θ, δ)
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 }}$$

Special cases:

• θ = δ = 1 gives the independence copula.

• θ = Inf or δ = Inf gives the upper Fréchet–Hoeffding bound.

Setting δ = 1 gives Joe with parameter θ, while θ = 1 gives Gumbel with parameter δ. Data near either subfamily may not identify both parameters well; the common corner (1,1) is independence.

See also: JoeGenerator, GumbelGenerator, ArchimedeanCopula, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("joe2014-cite-13")

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

source

Copulas.BB6Generator Type

BB6Generator(θ, δ)
BB6Copula{d}(θ, δ)
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 }}$$

Special cases:

• θ = δ = 1 gives the independence copula.

• θ = Inf or δ = Inf gives the upper Fréchet–Hoeffding bound.

Setting δ = 1 gives Joe with parameter θ, while θ = 1 gives Gumbel with parameter δ. Data near either subfamily may not identify both parameters well; the common corner (1,1) is independence.

See also: JoeGenerator, GumbelGenerator, ArchimedeanCopula, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("joe2014-cite-14")

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

source

Copulas.BB7Copula Type

BB7Generator(θ, δ)
BB7Copula{d}(θ, δ)
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 }.$$

The limiting combination θ = 1, δ = Inf gives the upper Fréchet–Hoeffding bound.

At θ = 1, BB7 reduces to Clayton with parameter δ. The family can represent dependence in both tails, but its two tail coefficients are not independently controlled over the entire parameter space; inspect them after fitting.

See also: ClaytonGenerator, ArchimedeanCopula, λₗ, λᵤ, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("joe2014-cite-15")

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

source

Copulas.BB7Generator Type

BB7Generator(θ, δ)
BB7Copula{d}(θ, δ)
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 }.$$

The limiting combination θ = 1, δ = Inf gives the upper Fréchet–Hoeffding bound.

At θ = 1, BB7 reduces to Clayton with parameter δ. The family can represent dependence in both tails, but its two tail coefficients are not independently controlled over the entire parameter space; inspect them after fitting.

See also: ClaytonGenerator, ArchimedeanCopula, λₗ, λᵤ, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("joe2014-cite-16")

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

source

Copulas.BB8Copula Type

BB8Generator(ϑ, δ)
BB8Copula{d}(ϑ, δ)
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 }$.

Special cases:

• ϑ = 1 gives the independence copula.

• δ = 1, ϑ = Inf gives the upper Fréchet–Hoeffding bound.

When δ = 1, BB8 is the Joe family; when ϑ = 1, δ is unidentified because the copula is independent for every admissible value. Computation near the open boundary δ = 0 can suffer cancellation in the definition of η.

See also: JoeGenerator, ArchimedeanCopula, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("joe2014-cite-17")

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

source

Copulas.BB8Generator Type

BB8Generator(ϑ, δ)
BB8Copula{d}(ϑ, δ)
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 }$.

Special cases:

• ϑ = 1 gives the independence copula.

• δ = 1, ϑ = Inf gives the upper Fréchet–Hoeffding bound.

When δ = 1, BB8 is the Joe family; when ϑ = 1, δ is unidentified because the copula is independent for every admissible value. Computation near the open boundary δ = 0 can suffer cancellation in the definition of η.

See also: JoeGenerator, ArchimedeanCopula, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("joe2014-cite-18")

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

source

Copulas.BB9Copula Type

BB9Generator(ϑ, δ)
BB9Copula{d}(ϑ, δ)
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}),$$

The corner ϑ = 1 is independence, while δ → ∞ approaches Gumbel with parameter ϑ. A large fitted δ can therefore leave the second parameter weakly identified; log-scale evaluation is preferable for extreme values.

See also: GumbelGenerator, ArchimedeanCopula, Distributions logpdf, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("joe2014-cite-19")

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

source

Copulas.BB9Generator Type

BB9Generator(ϑ, δ)
BB9Copula{d}(ϑ, δ)
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}),$$

The corner ϑ = 1 is independence, while δ → ∞ approaches Gumbel with parameter ϑ. A large fitted δ can therefore leave the second parameter weakly identified; log-scale evaluation is preferable for extreme values.

See also: GumbelGenerator, ArchimedeanCopula, Distributions logpdf, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("joe2014-cite-20")

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

source

Copulas.BC2Copula Type

BC2Tail(a, b)
BC2Tail(a::AbstractVector)
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 [ DocumenterCitations.CitationSiteNode("mai2011bivariate-cite-1")

],

$$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 [ DocumenterCitations.CitationSiteNode("mai2011bivariate-cite-2")

]. The vector constructor is the direct higher-dimensional two-atom spectral construction used by Copulas.jl; general finite spectral constructions are discussed in [ DocumenterCitations.CitationSiteNode("mai2012simulating-cite-3")

].

The finite spectral measure generally creates singular components, so pdf is not an ordinary global Lebesgue density. Entries at zero or one can collapse spectral atoms and produce simpler dependence structures.

See also: DiscreteSpectralTail, ExtremeValueCopula, ℓ.

source

Copulas.BC2Tail Type

BC2Tail(a, b)
BC2Tail(a::AbstractVector)
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 [ DocumenterCitations.CitationSiteNode("mai2011bivariate-cite-3")

],

$$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 [ DocumenterCitations.CitationSiteNode("mai2011bivariate-cite-4")

]. The vector constructor is the direct higher-dimensional two-atom spectral construction used by Copulas.jl; general finite spectral constructions are discussed in [ DocumenterCitations.CitationSiteNode("mai2012simulating-cite-4")

].

The finite spectral measure generally creates singular components, so pdf is not an ordinary global Lebesgue density. Entries at zero or one can collapse spectral atoms and produce simpler dependence structures.

See also: DiscreteSpectralTail, ExtremeValueCopula, ℓ.

source

Copulas.BernsteinCopula Type

BernsteinCopula(C; m=10)
BernsteinCopula(data; m=10)
BernsteinCopula{d}(C_or_data; m=10)
BernsteinCopula(d, C_or_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.

Behavior and cost:

• The choice of m controls smoothness: larger values give a finer polynomial approximation but require work and memory proportional to $\prod _j{m}_j$. Large d or m can therefore be prohibitive.

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

• For an empirical sample of size $n$ without ties, this construction is a genuine copula if and only if every degree $m_j$ divides $n$. Invalid degree choices are rejected. With m=nothing, the largest divisor of $n$ not exceeding $\lfloor n^{1/d}\rfloor$ is selected in every dimension.

• Raw data supplied with pseudo_values=false must have tie-free margins. Resolve ties explicitly with pseudos(data; ties=:first), :last, or :random before construction when deliberate tie breaking is scientifically justified.

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

See also: BetaCopula, EmpiricalCopula, Copula, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("sancetta2004bernstein-cite-1")

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

• [ DocumenterCitations.CitationSiteNode("segers2017-cite-3")

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

source

Copulas.BetaCopula Type

BetaCopula(data)
BetaCopula{d}(data)
BetaCopula(d, data)

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.

• Rows of data are variables and columns are observations. Empirical beta copulas require each margin to have distinct ranks; tied margins are rejected rather than broken according to observation order. If deliberate tie breaking is appropriate, apply pseudos with ties=:first, :last, or :random first. Tie-preserving methods remain tied and are still rejected.

• The beta kernels smooth the empirical mass into an absolutely continuous copula. This removes atoms but does not remove finite-sample uncertainty or sensitivity to the tie convention.

• Supports cdf, logpdf, random sampling and subsetting.

See also: EmpiricalCopula, BernsteinCopula, pseudos.

References:

• [ DocumenterCitations.CitationSiteNode("segers2017-cite-4")

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

source

Copulas.CheckerboardCopula Type

CheckerboardCopula(X; m=nothing, pseudo_values=true)
CheckerboardCopula{d}(X; m=nothing, pseudo_values=true)
CheckerboardCopula(d, 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). Raw tied margins are rejected because silently breaking them can change the fitted dependence according to observation order; resolve them explicitly with pseudos(X; ties=:first), :last, or :random when deliberate tie breaking is scientifically justified.

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

The result is absolutely continuous inside its boxes but its density is discontinuous at grid boundaries. Increasing grid resolution reduces smoothing and raises computational cost; sparse samples can leave many boxes empty.

See also: EmpiricalCopula, BernsteinCopula, pseudos.

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(θ)
ClaytonCopula{d}(θ)
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$):

• $\theta =-1/(d-1)$ gives the lower Fréchet–Hoeffding bound.

• $\theta =0$ gives the independence copula.

• $\theta =\mathrm{\infty }$ gives the upper Fréchet–Hoeffding bound.

Positive parameters produce lower-tail dependence but no upper-tail dependence. Negative parameters are valid only up to d ≤ 1 - 1/θ; equality introduces a singular component, so ordinary-density likelihood reasoning requires care at that boundary.

See also: Generator, ArchimedeanCopula, λₗ, λᵤ, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("nelsen2006-cite-5")

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

source

Copulas.ClaytonGenerator Type

ClaytonGenerator(θ)
ClaytonCopula{d}(θ)
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$):

• $\theta =-1/(d-1)$ gives the lower Fréchet–Hoeffding bound.

• $\theta =0$ gives the independence copula.

• $\theta =\mathrm{\infty }$ gives the upper Fréchet–Hoeffding bound.

Positive parameters produce lower-tail dependence but no upper-tail dependence. Negative parameters are valid only up to d ≤ 1 - 1/θ; equality introduces a singular component, so ordinary-density likelihood reasoning requires care at that boundary.

See also: Generator, ArchimedeanCopula, λₗ, λᵤ, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("nelsen2006-cite-6")

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

source

Copulas.Copula Type

Copula{d} <: Distributions.ContinuousMultivariateDistribution

Abstract type for a d-dimensional copula: a multivariate distribution on the unit hypercube with uniform univariate margins. Concrete families support the standard Distributions.jl operations documented for that family. The type parameter records dimension; internal storage parameters of concrete subtypes are not part of the public contract.

See also: SklarDist, subsetdims, condition, Distributions.fit, measure.

source

Copulas.CopulaModel Type

fit(CopulaModel, family, data; kwargs...)

A fitted copula model.

This type stores only the fitted distribution, the data supplied to fit, its cached fitted log-likelihood, and the minimal recipe needed to reproduce the estimator. Transformed observations and optimizer diagnostics are deliberately not retained.

Retrieve the fitted copula or Sklar distribution with fitted_distribution. CopulaModel also implements the documented StatsBase.StatisticalModel interface, including nobs, coef, coefnames, deviance, nulldeviance, nullloglikelihood, aic, bic, and residuals. Use selection_table for the candidate report produced by automatic family selection.

The complete field layout and type-parameter order of CopulaModel are implementation details.

See also Distributions.fit.

See also: fitted_distribution, infer, selection_table, GOFCopulaTest, StatsBase.residuals.

source

Copulas.CopulaTest Type

CopulaTest

Result of a copula hypothesis test.

Obtain this result from the public hypothesis-test functions, not by constructing its internal representation. Use pvalue, teststatistic, StatsBase.nobs and the displayed summary to inspect the result. Type parameters and internal calibration metadata are not part of the public constructor interface.

Example

using Copulas, Random

U = rand(Xoshiro(1), IndependentCopula(2), 100)
test = IndependenceCopulaTest(U; N=199, rng=Xoshiro(2))
(teststatistic(test), pvalue(test))

See also: IndependenceCopulaTest, ExchangeabilityCopulaTest, RadialSymmetryCopulaTest, ExtremeValueCopulaTest, GOFCopulaTest.

source

Copulas.CuadrasAugeCopula Type

CuadrasAugeTail(θ)
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).

For every positive θ, the finite spectral representation contains a singular component; density-based methods must therefore follow the documented generalized-density semantics rather than assume absolute continuity.

See also: DiscreteSpectralTail, ExtremeValueCopula, ℓ, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("mai2012simulating-cite-5")

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

source

Copulas.CuadrasAugeTail Type

CuadrasAugeTail(θ)
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).

For every positive θ, the finite spectral representation contains a singular component; density-based methods must therefore follow the documented generalized-density semantics rather than assume absolute continuity.

See also: DiscreteSpectralTail, ExtremeValueCopula, ℓ, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("mai2012simulating-cite-6")

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

Columns with zero total mass are discarded. Different matrices can represent the same spectral measure through repeated or zero atoms, so the matrix is not an identifiable statistical parameterization. The resulting copula can contain singular components and is sampled through its finite spectral representation.

See also: Tail, ExtremeValueCopula, ℓ, A.

source

Copulas.EmpiricalCopula Type

EmpiricalCopula(u; pseudo_values=true)
EmpiricalCopula{d}(u; pseudo_values=true)
EmpiricalCopula(d, 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 using the default average-rank tie convention; otherwise it assumes u already contains pseudo-observations in $[0,1]$. Call pseudos(data; ties=...) explicitly before construction to use another convention.

Notes:

• This is an empirical distribution on the observed pseudo-points. For finite N, its step margins are not continuous uniforms, so it is commonly called an empirical copula function without being a genuine copula on the full unit cube. EmpiricalCopula remains a Copula subtype for compatibility.

• Its probability measure is atomic. logpdf reports generalized mass values at stored points and -Inf elsewhere; it is not a Lebesgue log-density.

• Random sampling resamples observed columns, and subsetting preserves their empirical dependence.

See also: pseudos, BetaCopula, CheckerboardCopula, BernsteinCopula.

References:

• [ DocumenterCitations.CitationSiteNode("nelsen2006-cite-7")

  ] 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 [ DocumenterCitations.CitationSiteNode("gudendorf2011nonparametric-cite-2")

].

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 [ DocumenterCitations.CitationSiteNode("gudendorf2012multivariate-cite-2")

].

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 finite spectral measure defines a valid STDF and permits exact spectral simulation. Its concrete storage type is an implementation detail.

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.

See also: EmpiricalEVCopula, DiscreteSpectralTail, ExtremeValueCopula, ℓ, Distributions.fit.

source

Copulas.EmpiricalEVTail Type

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.

See also: EmpiricalEVCopula, ExtremeValueCopula, A, Distributions.fit.

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

Rows of u are the two margins and columns are observations. With pseudo_values=true, values are interpreted as pseudo-observations; otherwise the margins are ranked first using the default average-rank tie convention. Call pseudos(data; ties=...) explicitly to use another convention. method selects the classical Pickands, CFG, or OLS-intercept pilot estimator. The pilot is evaluated on grid points between eps and 1-eps, then projected onto the convex Pickands class and extended with the required endpoint values.

The returned tail evaluates A by piecewise-linear interpolation. Increasing grid gives a finer representation at additional fitting and storage cost; eps protects logarithmic calculations near zero and one. Shape projection guarantees a valid bivariate extreme-value model but can visibly modify a noisy pilot estimate, especially for small samples.

source

Copulas.ExtremeValueCopula Type

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 a tail valid in the requested dimension to construct the copula.

• CDF evaluation uses its STDF. Density requires the appropriate regularity or a documented specialized representation; a multivariate sampler does not follow from defining the STDF alone. See the developer guide for implementation requirements beyond the public constructor.

Example

using Copulas, Distributions

C = ExtremeValueCopula{2}(Copulas.GalambosTail(1.0))
U = rand(C, 1000)
logpdf.(Ref(C), eachcol(U))

Finite-spectral and limiting tails can produce singular components; in those cases pdf is not an ordinary global Lebesgue density. Constructor validity checks the tail's dimension but cannot turn a bivariate Pickands model into a multivariate STDF.

See also: Tail, A, ℓ, DiscreteSpectralTail, ExtremeValueCopulaTest.

References:

• [ DocumenterCitations.CitationSiteNode("gudendorf2010extreme-cite-1")

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

• [ DocumenterCitations.CitationSiteNode("joe2014-cite-21")

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

• [ DocumenterCitations.CitationSiteNode("mai2014financial-cite-1")

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

source

Copulas.FGMCopula Type

FGMCopula{d}(θ)
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 [ DocumenterCitations.CitationSiteNode("nelsen2006-cite-8")

]. We use the stochastic representation from [ DocumenterCitations.CitationSiteNode("blier2022stochastic-cite-2")

] to obtain random samples.

The parameter vector is ordered by interaction order and then by coordinate combination. Componentwise bounds |θᵢ| ≤ 1 are necessary but not sufficient; the constructor also checks all hypercube-corner inequalities. Parameter count grows exponentially with d, while attainable dependence remains relatively weak. In dimension two, the admissible endpoints θ = ±1 remain ordinary FGM copulas; the family does not attain either Fréchet–Hoeffding bound.

See also: Copula, IndependentCopula, τ, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("nelsen2006-cite-9")

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

• [ DocumenterCitations.CitationSiteNode("blier2022stochastic-cite-3")

  ] 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(D)

Construct a completely monotone Archimedean generator from a non-negative continuous frailty distribution D. Its generator is the Laplace transform

$$\varphi (t)=\mathbb{E}[e^{-tV}]={\mathrm{mgf}}_D(-t),V\sim D.$$

D must have non-negative support and implement Distributions.mgf. Generator derivatives additionally use expectations of V^k exp(-tV), and sampling an associated Archimedean copula uses rand on the frailty. The resulting complete monotonicity permits construction in every dimension.

Multiplying V by a positive constant changes the generator scale but not the resulting Archimedean copula. Consequently the frailty distribution is not an identifiable copula parameterization without a scale convention. This generic wrapper is useful for custom frailties; named generator families generally offer clearer parameter validation and fitting support.

Example

G = FrailtyGenerator(Gamma(2.0, 1.0))
C = ArchimedeanCopula(3, G)

References:

• [ DocumenterCitations.CitationSiteNode("hofert2009-cite-1")

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

See also: Generator, ArchimedeanCopula, ϕ, WilliamsonGenerator.

source

Copulas.FrankCopula Type

FrankGenerator(θ)
FrankCopula{d}(θ)
FrankCopula(d, θ)

The Frank copula is parameterized by $\theta \in (-\mathrm{\infty },\mathrm{\infty })$. Negative values are valid only in dimension two; nonnegative values are valid in every supported dimension. It is an Archimedean copula with generator

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

Special cases:

• $\theta =-\mathrm{\infty }$ gives the bivariate lower Fréchet–Hoeffding bound.

• $\theta =0$ gives the independence copula (continuous extension).

• $\theta =\mathrm{\infty }$ gives the upper Fréchet–Hoeffding bound.

Finite Frank copulas have neither lower- nor upper-tail dependence: they can fit central concordance while missing joint extremes. Negative parameters are restricted to dimension two; positive parameters are valid in every dimension.

See also: Generator, ArchimedeanCopula, τ, λₗ, λᵤ, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("nelsen2006-cite-10")

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

source

Copulas.FrankGenerator Type

FrankGenerator(θ)
FrankCopula{d}(θ)
FrankCopula(d, θ)

The Frank copula is parameterized by $\theta \in (-\mathrm{\infty },\mathrm{\infty })$. Negative values are valid only in dimension two; nonnegative values are valid in every supported dimension. It is an Archimedean copula with generator

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

Special cases:

• $\theta =-\mathrm{\infty }$ gives the bivariate lower Fréchet–Hoeffding bound.

• $\theta =0$ gives the independence copula (continuous extension).

• $\theta =\mathrm{\infty }$ gives the upper Fréchet–Hoeffding bound.

Finite Frank copulas have neither lower- nor upper-tail dependence: they can fit central concordance while missing joint extremes. Negative parameters are restricted to dimension two; positive parameters are valid in every dimension.

See also: Generator, ArchimedeanCopula, τ, λₗ, λᵤ, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("nelsen2006-cite-11")

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

source

Copulas.GalambosCopula Type

GalambosTail(θ)
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).

Increasing θ strengthens upper-tail association. The finite-parameter model is upper-tail dependent but does not imply analogous lower-tail clustering.

See also: Tail, ExtremeValueCopula, ℓ, λᵤ, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("galambos1975order-cite-4")

  ] 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(θ)
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).

Increasing θ strengthens upper-tail association. The finite-parameter model is upper-tail dependent but does not imply analogous lower-tail clustering.

See also: Tail, ExtremeValueCopula, ℓ, λᵤ, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("galambos1975order-cite-5")

  ] 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(Σ)
GaussianCopula(d, Σ)
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:

using Copulas, Distributions

Σ = [1.0 0.6; 0.6 1.0]
C = GaussianCopula(Σ)
u = rand(C, 1000)
logpdf(C, u[:, 1]), cdf(C, u[:, 1])
Ĉ = fit(GaussianCopula, u)

Special case:

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

Covariance-like inputs are copied and normalized to correlation scale, and non-positive-definite matrices are rejected. The copula owns its normalized matrix; mutating the constructor input or a matrix returned by params does not change the model. Gaussian copulas are asymptotically independent in both tails for every non-degenerate correlation, and multivariate CDF values are numerical estimates.

See also: TCopula, SklarDist, Nataf, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("nelsen2006-cite-12")

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

source

Copulas.Generator Type

Generator

Abstract representation of an Archimedean generator. A generator is a decreasing function ϕ : [0,∞) → [0,1] with ϕ(0)=1 and ϕ(∞)=0; constructing a d-dimensional Archimedean copula additionally requires the appropriate d-monotonicity.

Generator is a supported public extension point. A downstream generator G must implement:

• ϕ(G, t), the mathematical generator;

• max_monotony(G), the largest supported Williamson order (Inf for a completely monotone generator);

These methods are sufficient to construct ArchimedeanCopula(d, G) and use its generic CDF path: the inverse of ϕ is obtained numerically when no specialized method exists. Generic automatic differentiation and inverse-Williamson fallbacks provide density and sampling.

Only this mathematical interface is public. Copulas.jl's generator subtype hierarchy beyond documented public types, derivative and inverse hooks, radial caches, fitting hooks, dispatch traits, and specialized numerical machinery are implementation details. The developer guide describes those optional in-package optimizations separately.

See also: ArchimedeanCopula, ϕ, max_monotony, WilliamsonGenerator, FrailtyGenerator, Paramorph.transformation_schema.

source

Copulas.GumbelBarnettCopula Type

GumbelBarnettGenerator(θ)
GumbelBarnettCopula{d}(θ)
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:

• θ = 0 gives the independence copula.

Despite its name, this is not the Gumbel family: it models negative association. The admissible upper parameter decreases with dimension because the generator is not completely monotone over all θ ∈ [0,1]; construct the target copula dimension to trigger monotonicity validation.

See also: Generator, ArchimedeanCopula, max_monotony, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("joe2014-cite-22")

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

• [ DocumenterCitations.CitationSiteNode("nelsen2006-cite-13")

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

source

Copulas.GumbelBarnettGenerator Type

GumbelBarnettGenerator(θ)
GumbelBarnettCopula{d}(θ)
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:

• θ = 0 gives the independence copula.

Despite its name, this is not the Gumbel family: it models negative association. The admissible upper parameter decreases with dimension because the generator is not completely monotone over all θ ∈ [0,1]; construct the target copula dimension to trigger monotonicity validation.

See also: Generator, ArchimedeanCopula, max_monotony, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("joe2014-cite-23")

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

• [ DocumenterCitations.CitationSiteNode("nelsen2006-cite-14")

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

source

Copulas.GumbelCopula Type

GumbelGenerator(θ)
GumbelCopula{d}(θ)
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:

• θ = 1 gives the independence copula.

• θ = Inf gives the upper Fréchet–Hoeffding bound.

Increasing θ strengthens positive association. The family has upper-tail dependence and no lower-tail dependence, and its completely monotone generator is valid in every dimension. Very large values approach a singular limit.

See also: Generator, ArchimedeanCopula, λᵤ, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("nelsen2006-cite-15")

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

source

Copulas.GumbelGenerator Type

GumbelGenerator(θ)
GumbelCopula{d}(θ)
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:

• θ = 1 gives the independence copula.

• θ = Inf gives the upper Fréchet–Hoeffding bound.

Increasing θ strengthens positive association. The family has upper-tail dependence and no lower-tail dependence, and its completely monotone generator is valid in every dimension. Very large values approach a singular limit.

See also: Generator, ArchimedeanCopula, λᵤ, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("nelsen2006-cite-16")

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

source

Copulas.HuslerReissCopula Type

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

Hüsler-Reiss extreme-value copula.

The internal representation is always a variogram matrix Γ. Scalar constructors are convenience adapters to the exchangeable variogram whose off-diagonal entry is γ = (2 / θ)^2.

For d = 2, this is exactly the usual one-parameter representation. A 2×2 variogram is converted back with θ = 2 / sqrt(Γ[1,2]).

Special cases are stored in the same matrix representation: the zero variogram is complete dependence and the variogram with +Inf off-diagonal entries is independence.

See also: Tail, ExtremeValueCopula, ℓ, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("husler1989maxima-cite-1")

  ] 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(θ)
HuslerReissTail(Γ)
HuslerReissCopula{d}(θ)
HuslerReissCopula(d, θ)
HuslerReissCopula{d}(Γ)
HuslerReissCopula(d, Γ)
HuslerReissCopula(Γ)

Hüsler-Reiss extreme-value copula.

The internal representation is always a variogram matrix Γ. Scalar constructors are convenience adapters to the exchangeable variogram whose off-diagonal entry is γ = (2 / θ)^2.

For d = 2, this is exactly the usual one-parameter representation. A 2×2 variogram is converted back with θ = 2 / sqrt(Γ[1,2]).

Special cases are stored in the same matrix representation: the zero variogram is complete dependence and the variogram with +Inf off-diagonal entries is independence.

See also: Tail, ExtremeValueCopula, ℓ, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("husler1989maxima-cite-2")

  ] 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)
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}$.

The model is parameter free and available in every public copula dimension d ≥ 2. Its density is one throughout the unit hypercube, sampling produces independent uniform coordinates, and both Rosenblatt transforms are the identity. It is also the zero-dependence limit of many parametric families; constructing the named family at such a limit need not return this concrete type.

Example

using Copulas, Distributions

C = IndependentCopula(3)
cdf(C, [0.2, 0.5, 0.8]) == 0.2 * 0.5 * 0.8

See also: Copula, IndependentGenerator, ArchimedeanCopula.

References:

• [ DocumenterCitations.CitationSiteNode("nelsen2006-cite-17")

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

source

Copulas.IndependentGenerator Type

IndependentGenerator()

Parameter-free Archimedean generator ϕ(t) = exp(-t), corresponding to the independence copula in every dimension. It is useful when composing generic generator-based models; ordinary users will usually construct IndependentCopula directly.

See also: IndependentCopula, Generator, ArchimedeanCopula.

source

Copulas.InvGaussianCopula Type

InvGaussianGenerator(θ)
InvGaussianCopula{d}(θ)
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:

• θ = 0 gives the independence copula.

This frailty-based generator is completely monotone and therefore valid in every dimension. Unlike several common one-parameter families, letting θ grow without bound does not produce the comonotonic copula; compare implied dependence measures rather than raw parameter magnitudes across families.

See also: FrailtyGenerator, ArchimedeanCopula, τ, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("nelsen2006-cite-18")

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

source

Copulas.InvGaussianGenerator Type

InvGaussianGenerator(θ)
InvGaussianCopula{d}(θ)
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:

• θ = 0 gives the independence copula.

This frailty-based generator is completely monotone and therefore valid in every dimension. Unlike several common one-parameter families, letting θ grow without bound does not produce the comonotonic copula; compare implied dependence measures rather than raw parameter magnitudes across families.

See also: FrailtyGenerator, ArchimedeanCopula, τ, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("nelsen2006-cite-19")

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

source

Copulas.JoeCopula Type

JoeGenerator(θ)
JoeCopula{d}(θ)
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:

• θ = 1 gives the independence copula.

• θ = Inf gives the upper Fréchet–Hoeffding bound.

Joe copulas have upper-tail dependence and no lower-tail dependence. They are valid in every dimension, but large parameters concentrate mass near the singular comonotonic limit and can make likelihood optimization stiff.

See also: Generator, ArchimedeanCopula, λᵤ, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("nelsen2006-cite-20")

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

source

Copulas.JoeGenerator Type

JoeGenerator(θ)
JoeCopula{d}(θ)
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:

• θ = 1 gives the independence copula.

• θ = Inf gives the upper Fréchet–Hoeffding bound.

Joe copulas have upper-tail dependence and no lower-tail dependence. They are valid in every dimension, but large parameters concentrate mass near the singular comonotonic limit and can make likelihood optimization stiff.

See also: Generator, ArchimedeanCopula, λᵤ, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("nelsen2006-cite-21")

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

source

Copulas.LiebscherCopula Type

LiebscherCopula{d}(copulas, weights)
LiebscherCopula(d, copulas, weights)

The power Liebscher copula in dimension $d$ is defined as

$$C(\mathit{u})=\prod _{k=1}^K{C}_k(u_1^{a_{k1}},\dots ,u_d^{a_{kd}}),$$

where C_1,\ldots,C_K are d-dimensional copulas and the weights satisfy

$$a_{kj}\ge 0,\sum _{k=1}^K{a}_{kj}=1,j=1,\dots ,d.$$

Notes:

• copulas is a tuple of component copulas and weights is a K × d matrix, with one row per component and one column per coordinate.

• All component copulas must have dimension d.

• The constructor stores a floating-point copy of weights. Small numerical deviations from unit column sums are normalized; invalid columns are rejected.

• Zero weights deactivate the corresponding coordinate of a component.

• Supports cdf, logpdf when the resulting copula is absolutely continuous, random sampling, subsetting, conditioning and Rosenblatt transforms.

See also: KhoudrajiCopula, Copula, subsetdims, condition.

References:

• [ DocumenterCitations.CitationSiteNode("liebscher2008-cite-1")

  ] Liebscher, E. (2008). Construction of asymmetric multivariate copulas. Journal of Multivariate Analysis, 99(10), 2234-2250.

source

Copulas.LiouvilleCopula Type

LiouvilleCopula{d}(G::Generator, α)
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 and distribution evaluation follow Distributions.jl. Selecting dimensions yields the Liouville copula with the corresponding entries of α and the same mathematical generator. Conditioning and Rosenblatt transforms use the corresponding conditional distributions. Their numerical algorithms and intermediate representations are implementation details.

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

Example

using Copulas
using Copulas: ClaytonGenerator

C = LiouvilleCopula(ClaytonGenerator(2.0), (0.8, 1.2, 1.5))
U = rand(C, 100)

See also: Generator, ArchimedeanCopula, 𝒲₋₁, condition, subsetdims.

source

Copulas.LogCopula Type

LogTail(θ)
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).

Increasing θ strengthens exchangeable upper-tail dependence. This is the extreme-value representation of the Gumbel-Hougaard family, so users should not fit both names as distinct candidate models.

See also: GumbelCopula, ExtremeValueCopula, ℓ, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("tawn1988bivariate-cite-7")

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

source

Copulas.LogTail Type

LogTail(θ)
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).

Increasing θ strengthens exchangeable upper-tail dependence. This is the extreme-value representation of the Gumbel-Hougaard family, so users should not fit both names as distinct candidate models.

See also: GumbelCopula, ExtremeValueCopula, ℓ, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("tawn1988bivariate-cite-8")

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

source

Copulas.MCopula Type

MCopula(d)
MCopula{d}()

The upper Fréchet–Hoeffding bound is the pointwise largest copula and represents complete positive dependence. For any copula $C$ and all $\mathbf{u}\in [0,1{]}^d$,

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

MCopula is parameter free and valid in every public copula dimension d ≥ 2. A sample repeats one uniform variate across all coordinates, hence the distribution is concentrated on the main diagonal and has no ordinary Lebesgue density. pdf and logpdf follow Copulas.jl's generalized-density convention for singular copulas and must not be integrated against Lebesgue measure as if they were a density.

Example

using Copulas, Distributions

C = MCopula(3)
cdf(C, [0.2, 0.5, 0.8]) == 0.2

See also: Copula, WCopula, measure.

References:

• [ DocumenterCitations.CitationSiteNode("nelsen2006-cite-22")

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

source

Copulas.MOCopula Type

MOTail(λ₁, λ₂, λ₁₂)
MOTail(λ::AbstractVector)
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.

The common scale is therefore not identifiable and should be fixed when these intensities are estimated. The finite shock representation generally creates singular components; density-only fitting and interpretation require care.

See also: DiscreteSpectralTail, ExtremeValueCopula, ℓ.

References:

• [ DocumenterCitations.CitationSiteNode("mai2012simulating-cite-7")

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

source

Copulas.MOTail Type

MOTail(λ₁, λ₂, λ₁₂)
MOTail(λ::AbstractVector)
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.

The common scale is therefore not identifiable and should be fixed when these intensities are estimated. The finite shock representation generally creates singular components; density-only fitting and interpretation require care.

See also: DiscreteSpectralTail, ExtremeValueCopula, ℓ.

References:

• [ DocumenterCitations.CitationSiteNode("mai2012simulating-cite-8")

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

source

Copulas.MixedCopula Type

MixedTail(θ)
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 [ DocumenterCitations.CitationSiteNode("tawn1988bivariate-cite-9")

].

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 [ DocumenterCitations.CitationSiteNode("galambos1975order-cite-6")

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

Increasing θ moves from independence toward the fixed Galambos component, not all the way to comonotonicity. The multivariate extension is a Copulas.jl construction and should not be attributed directly to the bivariate paper.

See also: GalambosTail, ExtremeValueCopula, ℓ, Distributions.fit.

source

Copulas.MixedTail Type

MixedTail(θ)
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 [ DocumenterCitations.CitationSiteNode("tawn1988bivariate-cite-10")

].

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 [ DocumenterCitations.CitationSiteNode("galambos1975order-cite-7")

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

Increasing θ moves from independence toward the fixed Galambos component, not all the way to comonotonicity. The multivariate extension is a Copulas.jl construction and should not be attributed directly to the bivariate paper.

See also: GalambosTail, ExtremeValueCopula, ℓ, Distributions.fit.

source

Copulas.NestedArchimedeanCopula Type

NestedArchimedeanCopula(G; leaves=Int[], children=[])
NestedArchimedeanCopula{d}(G; leaves=Int[], children=[])
NestedArchimedeanCopula(d, G; leaves=Int[], children=[])

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 validates the tree structure, dimension placement, and each node generator's dimensional validity at that node's local arity. It intentionally does not validate the mathematical nesting relation between parent and child generators. Expert users may therefore construct trees outside the built-in fitting geometry. Template fitting performs its own upfront validation by constructing a nesting-aware Paramorph chart.

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, Distributions
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.

See also: Generator, ArchimedeanCopula, condition, subsetdims, SurvivalCopula, Distributions.fit.

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(θ)
PlackettCopula{2}(θ)
PlackettCopula(2, θ)

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.

The model is bivariate. Finite interior parameters are absolutely continuous and have no asymptotic tail dependence; θ < 1 gives negative association and θ > 1 positive association. Near θ = 1, use the continuous independence branch rather than evaluating the displayed quotient directly.

See also: Copula, WCopula, MCopula, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("joe2014-cite-24")

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

• [ DocumenterCitations.CitationSiteNode("johnson1987multivariate-cite-1")

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

• [ DocumenterCitations.CitationSiteNode("nelsen2006-cite-23")

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

source

Copulas.RafteryCopula Type

RafteryCopula{d}(θ)
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

Increasing θ moves from independence toward complete positive dependence. The endpoint at one is singular, while finite interior parameters use the family's continuous representation. The exchangeable construction uses one common parameter in every dimension and cannot represent heterogeneous pairs.

See also: Copula, IndependentCopula, MCopula, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("Raftery2023-cite-2")

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

• [ DocumenterCitations.CitationSiteNode("nelsen2006-cite-24")

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

source

Copulas.Rotated180Copula Type

Rotated180Copula(C)
Rotated180Copula{2}(C)
Rotated180Copula(2, C)

Construct the 180-degree rotation of the bivariate copula C. Both coordinates are reflected, so this is the bivariate survival copula. The reflection pattern is encoded by the concrete type and is preserved by fitting.

See also: SurvivalCopula, Copulas.flipmask, Copulas.flips.

source

Copulas.Rotated270Copula Type

Rotated270Copula(C)
Rotated270Copula{2}(C)
Rotated270Copula(2, C)

Construct the 270-degree rotation of the bivariate copula C. Its second coordinate is reflected. The reflection pattern is encoded by the concrete type and is therefore preserved by fitting.

See also: SurvivalCopula, Copulas.flipmask, Copulas.flips.

source

Copulas.Rotated90Copula Type

Rotated90Copula(C)
Rotated90Copula{2}(C)
Rotated90Copula(2, C)

Construct the 90-degree rotation of the bivariate copula C. Its first coordinate is reflected. The reflection pattern is encoded by the concrete type and is therefore preserved by fitting.

See also: SurvivalCopula, Copulas.flipmask, Copulas.flips.

source

Copulas.SklarDist Type

SklarDist(C, margins)

Construct a multivariate distribution from copula C and one univariate distribution per coordinate. The order of margins determines which marginal is attached to each copula coordinate, and its length must equal length(C).

The joint CDF follows Sklar's representation

$$F(x_1,\dots ,x_d)=C(F_1(x_1),\dots ,F_d(x_d)).$$

Theorem - Sklar 1959

Every multivariate distribution admits such a copula. It is unique on the product of the marginal ranges and, in particular, unique when all margins are continuous.

cdf, rand, marginalization, conditioning, and Rosenblatt transforms are available through the corresponding distribution and Copulas.jl interfaces. The usual density factorization is available when the copula and every margin provide the required densities. With discrete or mixed margins, pdf and logpdf evaluate the probability mass of Sklar's representation [ DocumenterCitations.CitationSiteNode("genest2007-cite-2")

]: a mixed derivative of the copula CDF in the continuous coordinates and a finite difference over the latent interval (F_j(x_j⁻), F_j(x_j)] in each discrete one, multiplied by the continuous marginal densities only. That difference costs 2^k copula CDF evaluations for k discrete margins, which is the mathematics rather than the implementation; a high-dimensional discrete model calls for a simulated likelihood. Conditioning and the Rosenblatt transforms treat a discrete observation as the same latent interval, so rosenblatt draws the atom's distributional transform and is random on atoms.

Passing an EmpiricalCopula is allowed for compatibility and emits a warning because its finite-sample margins are not exactly uniform. The result therefore does not generally have the requested margins. It represents the atomic empirical sample transformed by the marginal quantiles, and its pdf and logpdf values are generalized point masses rather than Lebesgue densities. Prefer BetaCopula, a valid BernsteinCopula, or CheckerboardCopula when a genuine copula is required.

Example

using Copulas, Distributions

C = ClaytonCopula(3, 0.7)
D = SklarDist(C, (Gamma(2, 3), Pareto(), LogNormal()))
sample = rand(D, 1000)

For fitting, SklarDist{CopulaType,Tuple{MarginTypes...}} is a deliberately supported public target syntax. It specifies the copula family and one marginal family per coordinate, for example SklarDist{ClaytonCopula,Tuple{Gamma,Normal}}. Those family parameters are public in this fitting context; no other field layout, storage parameter, or concrete representation detail of SklarDist is part of the public API. Use fit(CopulaModel, SklarDist{...}, data) to retain the fitted likelihood and the minimal state needed for diagnostics, inference, and reproducible refitting.

References:

• [ DocumenterCitations.CitationSiteNode("sklar1959-cite-2")

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

• [ DocumenterCitations.CitationSiteNode("nelsen2006-cite-25")

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

• [ DocumenterCitations.CitationSiteNode("genest2007-cite-3")

  ] Genest, C., & Nešlehová, J. (2007). A primer on copulas for count data. ASTIN Bulletin, 37(2), 475-515.

source

Copulas.SurvivalCopula Type

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

Construct a reflected version of a copula. SurvivalCopula(C) reflects every coordinate and therefore constructs the survival copula in the usual sense. The existing SurvivalCopula(C, flips) form reflects only the given indices.

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

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

If U ∼ C, the resulting random vector has coordinates 1-U[i] for i ∈ flips and U[i] otherwise. Its CDF is the corresponding inclusion–exclusion transform of C; it is not obtained merely by evaluating C at reflected arguments. Indices are one-based, unique, and must lie in 1:length(C). A Boolean tuple of length d is also accepted as a flip mask.

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

• Since the flip pattern belongs to an instance rather than its type, preserve a particular pattern during fitting with fit(typeof(S), U; flips=(...)). If flips is omitted, fitting flips every coordinate. The fitting methods available are those of the underlying copula.

Flipping all coordinates gives the usual survival copula. Partial flips can exchange upper- and lower-tail behavior and can change the sign of pairwise association; they do not change the uniform margins.

See also: Copula, subsetdims, condition, Rotated90Copula, Rotated180Copula, Rotated270Copula, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("nelsen2006-cite-26")

  ] Nelsen (2006), An introduction to copulas.

source

Copulas.TCopula Type

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

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.

The multivariate CDF is evaluated through the normal scale-mixture representation of the Student distribution. The remaining one-dimensional radial integral uses adaptive quadrature and the inner normal probabilities use MvNormalCDF.jl; consequently, returned probabilities are numerical estimates. For bivariate copulas, Spearman's rho uses the one-dimensional formula of Heinen and Valdesogo (2020).

Example usage:

using Copulas, Distributions

Σ = [1.0 0.6; 0.6 1.0]
C = TCopula(4.0, Σ)
u = rand(C, 1000)
logpdf(C, u[:, 1]), cdf(C, u[:, 1])
Ĉ = fit(TCopula{2}, u)

Degrees of freedom must be positive. Covariance-like matrix inputs are copied and normalized to correlation scale, and non-positive-definite matrices are rejected. The copula owns its normalized matrix; mutating the constructor input or a matrix returned by params does not change the model. Unlike the Gaussian copula, finite degrees of freedom produce symmetric lower- and upper-tail dependence. Large ν approaches the Gaussian copula and can be weakly identified.

See also: GaussianCopula, SklarDist, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("nelsen2006-cite-27")

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

• [ DocumenterCitations.CitationSiteNode("heinen2020spearman-cite-1")

  ] Heinen, Andréas and Valdesogo, Alfonso. Spearman rank correlation of the bivariate Student t and scale mixtures of normal distributions. Journal of Multivariate Analysis, 2020.

• [ DocumenterCitations.CitationSiteNode("genz1992normal-cite-1")

  ] Genz, Alan. Numerical computation of multivariate normal probabilities. Journal of Computational and Graphical Statistics, 1992.

source

Copulas.Tail Type

Tail

Abstract representation of the stable tail dependence function of an extreme-value copula. A valid STDF ℓ : [0,∞)^d → [0,∞) is convex, one-homogeneous, and satisfies

$$\underset{i}{max}{x}_i\le \ell (x)\le \sum _i{x}_i.$$

Equivalently, on the unit simplex it defines a Pickands dependence function A(w)=ℓ(w). Public component contracts concern documented constructors and mathematical evaluation. Dimension validation, derivative machinery, density, conditioning and sampling backends are internal and may require additional family-specific conditions. See the developer guide for the current architecture.

See also: ExtremeValueCopula, A, ℓ, DiscreteSpectralTail.

source

Copulas.TawnCopula Type

TawnCopula{d}(α, weights)
TawnCopula(d, α, weights)
TawnCopula{d}(dep, weights₁, ..., weights_d)
TawnCopula(d, dep, weights₁, ..., weights_d)
TawnCopula{d}(dep, asy)
TawnCopula(d, dep, asy)

Construct a Tawn asymmetric-logistic extreme-value copula.

The canonical full model uses one dep vector of length 2^d-d-1 and one probability-simplex vector of length 2^(d-1) for every margin. The historical (dep, asy) form remains accepted, with one local weight vector for every nonempty subset. TawnCopula{d}(α, weights) is the convenience model with one full-set logistic component plus singleton remainders.

source

Copulas.TawnTail Type

TawnTail(d, dep, asy)
TawnTail(dep, weights₁, ..., weights_d)
TawnTail(α, weights)
TawnCopula{d}(dep, weights₁, ..., weights_d)
TawnCopula{d}(α, weights)
TawnCopula(d, dep, asy)
TawnCopula(d, α, weights)

Multivariate asymmetric-logistic stable tail dependence function. The full subset representation follows Tawn's multivariate extreme-value construction [ DocumenterCitations.CitationSiteNode("tawn1990multivariate-cite-2")

]:

$$\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.

The canonical parameterization stores one dependence parameter for every non-singleton subset and, for every margin i, the vector (β_{i,C})_{C∋i} as a probability simplex. TawnTail(d, dep, asy) retains the historical subset-oriented input and converts it to this canonical form. TawnTail(α, weights) is the convenience model containing only the full-set logistic component plus singleton remainders.

The full subset representation grows exponentially with dimension, and zero weights can put the model on reduced or partially independent boundaries where some parameters are weakly identified.

See also: AsymLogTail, ExtremeValueCopula, ℓ, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("tawn1988bivariate-cite-11")

  ] for the bivariate precursor.

• [ DocumenterCitations.CitationSiteNode("tawn1990multivariate-cite-3")

  ] for the multivariate model.

source

Copulas.WCopula Type

WCopula{2}()
WCopula(2)

The lower Fréchet–Hoeffding bound is the smallest bivariate copula and represents complete negative dependence. For any copula $C$ and all $\mathbf{u}\in [0,1{]}^2$,

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

WCopula is parameter free and exists only in dimension two: the analogous formula is merely a pointwise lower bound, not a copula, in higher dimensions. A sample has the form (U, 1-U), so the law is singular on the anti-diagonal and has no ordinary Lebesgue density. pdf and logpdf use Copulas.jl's generalized-density convention and must not be integrated as a Lebesgue density.

Example

using Copulas, Distributions

C = WCopula()
isapprox(cdf(C, [0.7, 0.6]), 0.3)

See also: Copula, MCopula, measure.

References:

• [ DocumenterCitations.CitationSiteNode("nelsen2006-cite-28")

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

source

Copulas.WilliamsonGenerator Type

WilliamsonGenerator(X::Distributions.UnivariateDistribution, d)
WilliamsonGenerator(atoms::AbstractVector, weights::AbstractVector, d)
𝒲(X::Distributions.UnivariateDistribution,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,∞[ 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}$$

For integer d ≥ 2 and a strictly positive radial variable, this function has the following properties:

• We have that ϕ(0) = 1 and ϕ(Inf) = 0

• ϕ is d-2 times derivable, and the signs of its derivatives alternates : ∀ k ∈ 0,...,d-2, (-1)^k ϕ^(k) ≥ 0.

• (-1)^(d-2)ϕ^(d-2) is non-increasing and convex.

These properties characterize a d-monotone Archimedean generator. Real orders are also supported, but the integer derivative characterization above should not be read as a definition of fractional derivatives. Copula dimensions remain integers and are checked against the supported order. The function is 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)

• For a finite discrete radial law, the transform is ϕ(t) = ∑_j w_j · (1 − t/r_j)_+^(d−1). It is piecewise polynomial for integer orders; real orders need not give polynomials.

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

References:

• [ DocumenterCitations.CitationSiteNode("williamson1956-cite-6")

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

• [ DocumenterCitations.CitationSiteNode("mcneil2009-cite-10")

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

source

Copulas.tEVCopula Type

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

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

The internal representation is always a correlation matrix R. Scalar ρ constructors are convenience adapters to the exchangeable correlation matrix. For d = 2, ρ is exactly the off-diagonal matrix entry.

The complete-dependence limit ρ = 1 is stored as the all-ones correlation matrix in the same concrete tail type.

See also: TCopula, ExtremeValueCopula, ℓ, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("nikoloulopoulos2009extreme-cite-1")

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

source

Copulas.tEVTail Type

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

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

The internal representation is always a correlation matrix R. Scalar ρ constructors are convenience adapters to the exchangeable correlation matrix. For d = 2, ρ is exactly the off-diagonal matrix entry.

The complete-dependence limit ρ = 1 is stored as the all-ones correlation matrix in the same concrete tail type.

See also: TCopula, ExtremeValueCopula, ℓ, Distributions.fit.

References:

• [ DocumenterCitations.CitationSiteNode("nikoloulopoulos2009extreme-cite-2")

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

source

Copulas.𝒲 Type

WilliamsonGenerator(X::Distributions.UnivariateDistribution, d)
WilliamsonGenerator(atoms::AbstractVector, weights::AbstractVector, d)
𝒲(X::Distributions.UnivariateDistribution,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,∞[ 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}$$

For integer d ≥ 2 and a strictly positive radial variable, this function has the following properties:

• We have that ϕ(0) = 1 and ϕ(Inf) = 0

• ϕ is d-2 times derivable, and the signs of its derivatives alternates : ∀ k ∈ 0,...,d-2, (-1)^k ϕ^(k) ≥ 0.

• (-1)^(d-2)ϕ^(d-2) is non-increasing and convex.

These properties characterize a d-monotone Archimedean generator. Real orders are also supported, but the integer derivative characterization above should not be read as a definition of fractional derivatives. Copula dimensions remain integers and are checked against the supported order. The function is 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)

• For a finite discrete radial law, the transform is ϕ(t) = ∑_j w_j · (1 − t/r_j)_+^(d−1). It is piecewise polynomial for integer orders; real orders need not give polynomials.

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

References:

• [ DocumenterCitations.CitationSiteNode("williamson1956-cite-7")

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

• [ DocumenterCitations.CitationSiteNode("mcneil2009-cite-11")

  ] McNeil, Alexander J., & Nešlehová, Johanna. "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.

For integer $d\ge 2$, a $d$-monotone Archimedean generator $\varphi$ has these 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$.

• $(-1{)}^{d-2}{\varphi }^{(d-2)}$ is non-increasing and 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)}{(d-1)!}-\sum _{k=0}^{d-2}\frac{(-x{)}^k{\varphi }^{(k)}(x)}{k!}$$

The result is the corresponding non-negative univariate distribution, not a particular concrete distribution type. It need not be continuous: an inverse at the original Williamson order can return the original discrete radial law. Use Distributions.cdf and rand to evaluate its CDF and sample it. Density or mass evaluation follows the returned distribution's supported interface; no Lebesgue density is promised for discrete or singular laws.

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.

See also: WilliamsonGenerator, Generator, ArchimedeanCopula, LiouvilleCopula.

source

Copulas.A Method

A(tail::Tail, ω)

Evaluate the Pickands representation on the unit simplex. For a generic tail this is ℓ(tail, ω); bivariate Pickands-capable tails also accept a scalar coordinate. The input must belong to the representation documented by the concrete tail.

See also: ℓ, Tail, ExtremeValueCopula.

source

Copulas.EmpiricalGenerator Method

EmpiricalGenerator(u::AbstractMatrix; pseudo_values=true)

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

It returns a Generator representing the fitted generator. Its concrete representation is an implementation detail and may depend on the data.

Usage

G = EmpiricalGenerator(u)

where u::AbstractMatrix has one component per row and one observation per column (d×n). With pseudo_values=true, values must already be pseudo-observations; pass pseudo_values=false to rank-transform raw data.

Notes

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

• Code should use the documented Generator operations rather than rely on a particular concrete return type.

References

• [ DocumenterCitations.CitationSiteNode("mcneil2009-cite-12")

  ]

• [ DocumenterCitations.CitationSiteNode("williamson1956-cite-8")

  ]

• [ DocumenterCitations.CitationSiteNode("genest2011a-cite-4")

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

source

Copulas.ExchangeabilityCopulaTest Method

ExchangeabilityCopulaTest(U; permutations=:G2, weight=:wm2, N=1000, pseudo_values=false, rng=Random.default_rng())

Test exchangeability of a copula in arbitrary dimension.

U is a d × n matrix with observations in columns. The statistic compares the empirical copula with versions obtained by permuting its coordinates. permutations=:G2 uses a compact generating set; :G1 uses transpositions with the first coordinate, and an explicit collection can target particular permutations. weight=:wm2 applies the boundary-aware weight, while :none leaves the squared discrepancies unweighted. A multiplier procedure with N replicates calibrates the p-value.

By default raw continuous margins are ranked; use pseudo_values=true for precomputed pseudo-observations. Ties are currently rejected. The multiplier representation uses dense n × n matrices for every selected permutation, so large samples or permutation sets may reach the package's memory safety limit.

See also: CopulaTest, pvalue, RadialSymmetryCopulaTest.

source

Copulas.ExtremeValueCopulaTest Method

ExtremeValueCopulaTest(U; powers=3:5, N=1000, pseudo_values=false, rng=Random.default_rng())

Test whether a copula belongs to the extreme-value class.

The test probes max-stability through the identities C(u^(1/r))^r = C(u) for the values r in powers; every power must be finite and greater than one. U is a d × n matrix whose observations are columns, and a multiplier procedure with N replicates calibrates the resulting Cramér–von Mises statistic.

Raw continuous margins are ranked unless pseudo_values=true, and ties are currently unsupported. More powers examine more max-stability identities but also require one dense n × n multiplier matrix per power; very large requests may therefore reach the memory safety limit.

See also: CopulaTest, pvalue, ExtremeValueCopula, GOFCopulaTest.

source

Copulas.GOFCopulaTest Method

GOFCopulaTest(C, U; N=1000, pseudo_values=false, rng=Random.default_rng())
GOFCopulaTest(model, U; N=1000, pseudo_values=false, rng=Random.default_rng())
GOFCopulaTest(model)

Test goodness of fit for a copula or fitted copula model.

GOFCopulaTest(C, U) treats C as a fixed specified copula and tests a simple null hypothesis.

GOFCopulaTest(M) tests the fitting sample stored by M under a composite null hypothesis. The estimator specification that produced M is replayed in every parametric-bootstrap replicate.

GOFCopulaTest(M, U) first refits that estimator specification on U; the resulting fitted model is used for the observed statistic, and the same fitting procedure is repeated in every bootstrap replicate. If the fitting procedure is not reproducibly specified, composite GOF throws an ArgumentError.

For a fitted SklarDist, stored and explicit observations remain on their raw marginal scales. Each bootstrap replicate samples and refits the complete Sklar distribution, then reconstructs its copula observations for the statistic.

The test statistic compares the empirical and fitted copula CDFs at the sample points. N controls parametric-bootstrap replication, and raw continuous margins are ranked unless pseudo_values=true. Ties are currently rejected.

See also: CopulaTest, CopulaModel, Distributions.fit, selection_table.

source

Copulas.IndependenceCopulaTest Method

IndependenceCopulaTest(U; N=1000, pseudo_values=false, rng=Random.default_rng())

Test mutual independence between the components of a random vector.

U is a d × n matrix with observations in columns. By default its margins are converted to pseudo-observations; pass pseudo_values=true when U has already been ranked. The Cramér–von Mises statistic compares the empirical copula with the independence copula, and N samples from the latter calibrate the p-value.

The current procedure assumes continuous, tie-free margins. Larger N reduces Monte Carlo uncertainty at a proportional computational cost. Supply rng for reproducible calibration.

See also: CopulaTest, pvalue, ExchangeabilityCopulaTest, GOFCopulaTest.

source

Copulas.KhoudrajiCopula Method

KhoudrajiCopula(d, C, shapes)
KhoudrajiCopula(d, (C1, C2), shapes)

Construct a Khoudraji copula in dimension $d$ as a power LiebscherCopula.

For two component copulas $C_1$ and $C_2$,

`math C_K(\boldsymbol u) = C_1!\left(u_1^{1-\alpha_1},\ldots,u_d^{1-\alpha_d}\right)C_2!\left(u_1^{\alpha_1},\ldots,u_d^{\alpha_d}\right),``

where 0 \le \alpha_j \le 1 for j=1,\ldots,d.

Notes:

• shapes contains the d parameters \alpha_1,\ldots,\alpha_d.

• KhoudrajiCopula(d, C, shapes) uses IndependentCopula as the first component.

• KhoudrajiCopula is a convenience constructor and returns a LiebscherCopula; it does not define a separate copula type.

• All probability, sampling, subsetting, conditioning and Rosenblatt operations are therefore inherited from LiebscherCopula.

See also: LiebscherCopula, IndependentCopula.

References:

• [ DocumenterCitations.CitationSiteNode("khoudraji1996-cite-1")

  ] Khoudraji, A. (1996). Contributions à l'étude des copules et à la modélisation des valeurs extrêmes bivariées. PhD thesis, Université Laval, Québec, Canada.

• [ DocumenterCitations.CitationSiteNode("liebscher2008-cite-2")

  ] Liebscher, E. (2008). Construction of asymmetric multivariate copulas. Journal of Multivariate Analysis, 99(10), 2234-2250.

source

Copulas.Nataf Method

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

Nataf correction [ DocumenterCitations.CitationSiteNode("nataf1962-cite-3")

, DocumenterCitations.CitationSiteNode("liu1986-cite-3")

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

See also: GaussianCopula, SklarDist.

References:

• [ DocumenterCitations.CitationSiteNode("nataf1962-cite-4")

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

• [ DocumenterCitations.CitationSiteNode("liu1986-cite-4")

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

source

Copulas.RadialSymmetryCopulaTest Method

RadialSymmetryCopulaTest(U; N=1000, pseudo_values=false, rng=Random.default_rng())

Test radial symmetry of a copula.

U is a d × n matrix with observations in columns. The statistic compares the empirical copula with the empirical copula of the reflected observations 1 .- U. Its p-value is calibrated by independently reflecting each observation with probability one half over N randomizations.

Raw continuous margins are ranked unless pseudo_values=true. Ties are not currently supported. Because calibration is randomized, pass rng when the result must be reproducible and increase N when finer Monte Carlo precision is needed.

See also: CopulaTest, pvalue, ExchangeabilityCopulaTest.

source

Copulas.basecopula Method

basecopula(C)

Return the underlying copula transformed by the reflected copula C.

See also: flipmask, flips.

source

Copulas.condition Method

    condition(C::Copula{D}, js, u_js)
    condition(C::Copula{D}, js, lo_js, hi_js)
    condition(X::SklarDist, js, x_js)
    condition(X::SklarDist, js, xlo_js, xhi_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). The three-argument form conditions on the event U_js = u_js; the four-argument form conditions on the box U_js ∈ ∏ₖ [lo_js[k], hi_js[k]], and a coordinate with lo == hi is conditioned on that point, so condition(C, js, u, u) is condition(C, js, u) and one call may mix fixed values with intervals.

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)

• lo_js, hi_js: bounds in [0,1], lo_js ≤ hi_js, of the box for U_js

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

• xlo_js, xhi_js: bounds on the original scale of the box for X_js

• 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 the univariate conditional distribution of U_i | U_js = u_js, supported on [0,1].

  • condition(X, js, x_js) returns the univariate conditional distribution of X_i | X_js = x_js on the original marginal scale.

• If d > 1:

  • condition(C, js, u_js) returns the conditional joint distribution of U_I | U_js = u_js on the original copula coordinate scale [0,1]^d; its conditional margins need not be uniform.

  • condition(X, js, x_js) returns the conditional joint distribution on the original marginal scales.

• The four-argument forms return the same kinds of objects for the box event.

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.

• Concrete return types are implementation details. Use the standard Distributions.jl operations on the returned distribution.

Conditioning on a point is defined through regular conditional laws at the supplied values. At zero-density points, a generic derivative-based representation may be undefined or numerically unstable; family specializations can provide meaningful endpoint or atomic behavior. Conditioning on a box is defined wherever the box has positive probability, through inclusion–exclusion of the same CDF partials over its corners; a box of zero probability throws an ArgumentError. Remaining coordinates preserve their original relative order.

Observing a discrete margin X_j = x_j of a SklarDist is the latent event U_j ∈ (F_j(x_j⁻), F_j(x_j)], not the point U_j = F_j(x_j) [ DocumenterCitations.CitationSiteNode("genest2007-cite-4")

], so condition(X, js, x_js) conditions an atom on its interval and a continuous margin on its point, as the discrete pair-copula constructions of [ DocumenterCitations.CitationSiteNode("panagiotelis2012-cite-2")

] and [ DocumenterCitations.CitationSiteNode("schallhorn2017-cite-1")

] do; the box form condition(X, js, xlo_js, xhi_js) maps [xlo, xhi] to (F_j(xlo⁻), F_j(xhi)] in the same way.

Example

using Copulas, Distributions

C = GaussianCopula(3, 0.4)
D = condition(C, (1,), (0.7,))
cdf(D, [0.4, 0.8])

# U₁ | U₂ = 0.7, U₃ ∈ [0, 0.1]
B = condition(C, (2, 3), (0.7, 0.0), (0.7, 0.1))
cdf(B, 0.4)

References:

• [ DocumenterCitations.CitationSiteNode("genest2007-cite-5")

  ] Genest, C., & Nešlehová, J. (2007). A primer on copulas for count data. ASTIN Bulletin, 37(2), 475-515.

• [ DocumenterCitations.CitationSiteNode("panagiotelis2012-cite-3")

  ] Panagiotelis, A., Czado, C., & Joe, H. (2012). Pair copula constructions for multivariate discrete data. Journal of the American Statistical Association, 107(499), 1063-1072.

• [ DocumenterCitations.CitationSiteNode("schallhorn2017-cite-2")

  ] Schallhorn, N., Kraus, D., Nagler, T., & Czado, C. (2017). D-vine quantile regression with discrete variables. arXiv:1705.08310.

See also: subsetdims, rosenblatt, inverse_rosenblatt, SklarDist.

source

Copulas.corblomqvist Method

corblomqvist(X::AbstractMatrix)
corblomqvist(C::Copula)

Return the symmetric matrix of pairwise Blomqvist beta coefficients. Data follow the StatsBase convention (n × d, observations in rows); a copula is reduced to each bivariate margin. Diagonal entries are one.

Data columns are ranked before observations are split at their median. A column containing NaN produces NaN in all corresponding off-diagonal entries.

source

Copulas.corentropy Method

corentropy(X::AbstractMatrix; k=5, p=Inf, leafsize=32)
corentropy(C::Copula)

Return pairwise copula entropy as a symmetric matrix with zero diagonal. The data method uses n × d observations and a nearest-neighbor estimator; the copula method requires bivariate margins with ordinary densities.

For data, k, p and leafsize have the same interpretation and caveats as in ι; columns containing NaN propagate NaN to the corresponding pairs. The zero diagonal is conventional and does not invoke a degenerate self-copula entropy calculation.

source

Copulas.corgini Method

corgini(X::AbstractMatrix)
corgini(C::Copula)

Return the symmetric matrix of pairwise Gini gamma coefficients. Data follow the StatsBase n × d orientation; copula entries are computed from bivariate margins. Diagonal entries are one.

The data estimator is rank based. A column containing NaN produces NaN in all corresponding off-diagonal entries.

source

Copulas.corlowertail Function

corlowertail(X::AbstractMatrix, method=:SchmidtStadtmueller, p=nothing)
corlowertail(C::Copula)

Return the symmetric matrix of pairwise lower-tail dependence coefficients. Data use the StatsBase n × d orientation and either the :SchmidtStadtmueller threshold estimator or :SchmidSchmidt integral estimator. Copula entries use their bivariate margins.

p controls the lower-tail threshold and defaults to 1/√n. Smaller values focus farther into the tail but increase sampling variability. Diagonal entries are one; a data column containing NaN propagates NaN to its off-diagonal pairs. Data must already be represented on the uniform scale; apply pseudos to raw continuous margins. Many ties can make a continuous-tail interpretation unreliable.

source

Copulas.coruppertail Function

coruppertail(X::AbstractMatrix, method=:SchmidtStadtmueller, p=nothing)
coruppertail(C::Copula)

Return the symmetric matrix of pairwise upper-tail dependence coefficients. Data use the StatsBase n × d orientation and either the :SchmidtStadtmueller threshold estimator or :SchmidSchmidt integral estimator. Copula entries use their bivariate margins.

p controls the upper-tail threshold and defaults to 1/√n. Smaller values focus farther into the tail but increase sampling variability. Diagonal entries are one; a data column containing NaN propagates NaN to its off-diagonal pairs. Data must already be represented on the uniform scale; apply pseudos to raw continuous margins. Many ties can make a continuous-tail interpretation unreliable.

source

Copulas.fitted_distribution Method

fitted_distribution(M::CopulaModel)

Return the fitted copula or SklarDist represented by M.

This is the supported way to retrieve the fitted distribution from a CopulaModel; the model's concrete storage fields are not public API. The returned distribution can be passed to the ordinary Distributions.jl and Copulas.jl operations.

See also: CopulaModel, Distributions.fit, StatsBase.residuals.

source

Copulas.flipmask Method

flipmask(C)

Return the Boolean tuple identifying the reflected coordinates of C. The tuple has one entry per coordinate and is suitable for dispatch-neutral, type-stable internal algorithms. Use flips for the corresponding one-based indices.

source

Copulas.flips Method

flips(C)

Return the one-based indices of the reflected coordinates of C.

See also: flipmask, basecopula.

source

Copulas.infer Method

infer(M::CopulaModel; method=:default, kwargs...) -> CopulaInference

Apply an uncertainty-quantification procedure after estimation. fit is never rerun except by resampling procedures, and M is not mutated.

The principled default is :hessian for supported maximum-likelihood fits, :godambe for supported bivariate rank-matching estimators, and :godambe_pairwise for supported multivariate estimators based on pairwise rank moments. A fitting extension does not acquire analytical inference merely by implementing a fitting route. Fits without a justified default raise an ArgumentError. Explicit methods are :hessian, :godambe, :godambe_pairwise, :jackknife, and :bootstrap. Godambe and bootstrap inference accept nresamples and rng; these execution controls are not retained in the result.

Analytical inference does not silently regularize failed covariance estimates. A singular observed-information matrix still raises an ArgumentError. The reported natural-parameter covariance may legitimately be singular because coef(M) can contain constrained or redundant entries (for example both halves of a symmetric matrix); such positive-semidefinite covariance is preserved.

For a fitted SklarDist, the default is :bootstrap. Every resample repeats the complete estimator: all margins are fitted again, pseudo-observations are recomputed, and the copula is refitted. The resulting covariance therefore contains marginal, copula, and cross-component uncertainty. Analytical methods remain unavailable because the estimators selected by Distributions.fit for arbitrary marginal families do not share a common derivative contract.

A model fitted with weights is treated as a fit of the sample in which observation j is repeated weights[j] times, which is what the weights mean to fit. :hessian inverts the observed information of the weighted log-likelihood; :godambe, :godambe_pairwise and :bootstrap draw each resample of size n with observation j taken with probability weights[j] / n, and compute the moment or refit the estimator on that resample unweighted. Unit weights reproduce the unweighted :hessian bit for bit; the resampling methods draw through a weighted sampler, so they reproduce the unweighted covariance in distribution, not for a given rng. :jackknife refuses a weighted model, because the delete-one jackknife of the replicated sample needs every weight to be at least one, which after normalization to n holds for unit weights only.

See also: CopulaInference, StatsBase.vcov, StatsBase.stderror, StatsBase.confint.

source

Copulas.inverse_rosenblatt Method

inverse_rosenblatt(C::Copula, u)

Map independent uniform inputs to the dependence structure of C by successive conditional quantiles. If S follows the independence copula, the result follows C. Vector inputs represent one point; matrix inputs store points in columns and are processed without changing their order.

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.

Inputs are clamped to the unit interval. Generalized quantiles make the transformation suitable for sampling conditionals with atoms, but in that case rosenblatt(C, inverse_rosenblatt(C, s)) == s need not hold pointwise. An almost-sure round trip requires continuous conditional CDFs that are invertible on their supports.

For a SklarDist with discrete margins, step k is the generalised inverse x_k = Q_k(H⁻¹(s_k)) of the conditional CDF given the predecessors, an atom among them conditioning on its latent interval [ DocumenterCitations.CitationSiteNode("panagiotelis2012-cite-4")

], so independent uniforms map to the joint law and inverse_rosenblatt(X, rosenblatt(rng, X, x)) == x.

References:

• [ DocumenterCitations.CitationSiteNode("rosenblatt1952-cite-2")

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

• [ DocumenterCitations.CitationSiteNode("joe2014-cite-25")

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

• [ DocumenterCitations.CitationSiteNode("mcneil2009-cite-13")

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

• [ DocumenterCitations.CitationSiteNode("panagiotelis2012-cite-5")

  ] Panagiotelis, A., Czado, C., & Joe, H. (2012). Pair copula constructions for multivariate discrete data. Journal of the American Statistical Association, 107(499), 1063-1072.

See also: rosenblatt, condition, SklarDist.

source

Copulas.max_monotony Function

max_monotony(G::Generator)

Return the largest Williamson order for which G is known to be monotone. Inf denotes complete monotonicity. This public mathematical query is used to validate the dimensions of Archimedean and Liouville constructions.

A downstream Generator subtype must implement this method. If it does not, Julia's normal method dispatch raises MethodError.

See also: Generator, ArchimedeanCopula, LiouvilleCopula, ϕ.

source

Copulas.measure Method

measure(C::Copula, lower, upper)

Return the probability assigned by C to the axis-aligned half-open rectangle with opposite corners lower and upper, using CDF inclusion–exclusion. Bounds are clipped to the unit hypercube; a rectangle with any non-positive width has measure zero. Both corners must contain one value per copula dimension.

See also: Distributions.cdf, subsetdims, Copula.

source

Copulas.pseudos Method

pseudos(sample; ties=:average, rng=Random.default_rng(), weights=nothing)

Compute pseudo-observations from a d×n sample, with variables in rows and observations in columns.

Each row is replaced by its ranks divided by n+1, so every output is strictly inside (0,1). The transformation is invariant under strictly increasing changes of each margin and returns a newly allocated floating-point matrix.

The ties keyword controls equal observations. Supported values are :average (the default), :first, :last, :min, :max, and :random. Average ranks preserve ties and make the result invariant to observation order. :first is the ordinal convention used by Copulas.jl before version 1.0; :last reverses that order within each tied group. :random randomly assigns the available ordinal ranks within each tied group and uses rng; deterministic methods do not consume it.

Choosing a rank convention does not by itself make continuous-margin fitting or hypothesis-testing procedures valid for genuinely discrete data.

weights gives one non-negative, finite weight per observation, not all zero, and ranks each margin by weighted mass. The weights are normalized to sum to the number of observations n first, so the result is invariant to their scale and unit weights reproduce the unweighted ranks exactly. The ranks are computed and returned in the floating-point type that the sample and the weights promote to. Observation i then receives the mean rank of its copies in the sample where every observation j is repeated weights[j] times, under the same tie convention, divided by n + 1. A zero-weight observation contributes no mass and is placed at the weighted empirical distribution function of its value.

Example

X = [30 10 20; 4 6 5]
pseudos(X) == [0.75 0.25 0.5; 0.25 0.75 0.5]

# Integer weights that sum to `n` are counts: the ranks are those of the
# sample where each observation is repeated that many times.
X = [30 10 20 40; 4 6 5 7]
kept = [1, 3, 4]
pseudos(X; weights=[2, 0, 1, 1])[:, kept] == pseudos([30 30 20 40; 4 4 5 7])[:, kept]

See also: EmpiricalCopula, BetaCopula, CheckerboardCopula.

source

Copulas.rosenblatt Method

rosenblatt(C::Copula, u)
rosenblatt(X::SklarDist, x)
rosenblatt([rng::AbstractRNG,] X::SklarDist, x)

Evaluate successive conditional CDFs associated with C on the vector u. For U ∼ C, the result consists of independent uniforms when the successive conditional laws are atomless. Forward/inverse round trips hold almost surely when those CDFs are continuous and invertible on their supports, not universally for singular or atomic models. Generalized conditional quantiles may still sample such models through inverse_rosenblatt; they do not make the deterministic forward transform bijective. Matrix inputs evaluate observations columnwise.

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.

For a SklarDist with continuous margins, x is mapped through the marginal CDFs and the copula transform applies. A discrete margin is an atom: its observation x_k is the latent interval (F_k(x_k⁻), F_k(x_k)], so coordinate k takes the distributional transform [ DocumenterCitations.CitationSiteNode("ruschendorf2009-cite-2")

] of its conditional law, S_k = H(F_k(x_k⁻)) + V (H(F_k(x_k)) − H(F_k(x_k⁻))) with V ∼ U(0,1) drawn from rng, the randomisation of [ DocumenterCitations.CitationSiteNode("brockwell2007-cite-2")

], and every later coordinate conditions on that interval rather than on the randomised value, as in the discrete pair-copula constructions of [ DocumenterCitations.CitationSiteNode("panagiotelis2012-cite-6")

]. The result is then a vector of independent uniforms for X ∼ SklarDist, and inverse_rosenblatt inverts it in law. The rng is drawn only for atoms; without one, the default rng is used. This is the convention of vinecopulib's Vinecop::rosenblatt with randomize_discrete.

• [ DocumenterCitations.CitationSiteNode("rosenblatt1952-cite-3")

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

• [ DocumenterCitations.CitationSiteNode("joe2014-cite-26")

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

• [ DocumenterCitations.CitationSiteNode("mcneil2009-cite-14")

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

• [ DocumenterCitations.CitationSiteNode("brockwell2007-cite-3")

  ] Brockwell, A. E. (2007). Universal residuals: A multivariate transformation. Statistics & Probability Letters, 77(14), 1473-1478.

• [ DocumenterCitations.CitationSiteNode("ruschendorf2009-cite-3")

  ] Rüschendorf, L. (2009). On the distributional transform, Sklar's theorem, and the empirical copula process. Journal of Statistical Planning and Inference, 139(11), 3921-3927.

• [ DocumenterCitations.CitationSiteNode("panagiotelis2012-cite-7")

  ] Panagiotelis, A., Czado, C., & Joe, H. (2012). Pair copula constructions for multivariate discrete data. Journal of the American Statistical Association, 107(499), 1063-1072.

See also: inverse_rosenblatt, condition, StatsBase.residuals.

source

Copulas.selected_model Method

selected_model(result::CopulaSelection) -> CopulaModel

Return the winning fitted model from an automatic family-selection result.

See also: selection_table, fitted_distribution.

source

Copulas.selection_table Method

selection_table(result::CopulaSelection)

Return a copy of the candidate comparison rows recorded by automatic family selection. Each row identifies a candidate, its status and effective method, its likelihood and information criteria, or the error that prevented fitting. Rows retain candidate order; changing the returned vector does not mutate the selection result.

See also: CopulaSelection, selected_model, StatsBase.aic, StatsBase.bic.

source

Copulas.subsetdims Method

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

Return the marginal distribution on the coordinates selected by dims.

Indices are one-based, distinct, and order-sensitive: (3, 1) both selects and reorders coordinates. For a copula, selecting one coordinate returns the uniform marginal; for a SklarDist, it returns the corresponding original marginal. Selecting several coordinates preserves their joint marginal law and returns a copula or Sklar distribution of that dimension. Selecting every coordinate in natural order may return the original object.

The result can be a family-specific closed form or an internal generic wrapper; callers should rely on its distribution behavior rather than its concrete type. Invalid, repeated, or empty index collections are rejected.

Example

C = GaussianCopula(3, [1.0 0.2 0.6; 0.2 1.0 0.4; 0.6 0.4 1.0])
C31 = subsetdims(C, (3, 1))
length(C31) == 2

See also: condition, SklarDist, measure.

source

Copulas.teststatistic Method

teststatistic(test::CopulaTest)

Return the observed value of the test statistic.

Larger values indicate a greater discrepancy from the null hypothesis. The scale and precise interpretation depend on the test; use pvalue(test) for the calibrated result rather than comparing statistics produced by different tests.

source

Copulas.β Method

β(C::Copula)
β(U::AbstractMatrix)

Return multivariate Blomqvist's beta, a median-orthant measure of concordance, for a copula or pseudo-observations stored by columns.

In two dimensions this is 4C(1/2,1/2)-1; the multivariate extension combines the lower and upper median orthants. Independence maps to zero and complete positive dependence to one. The data form expects values already represented on the uniform scale and classifies observations relative to 1/2; use pseudos first for raw continuous margins.

See also: corblomqvist, pseudos, τ.

source

Copulas.γ Method

γ(C::Copula)
γ(U::AbstractMatrix)

Return multivariate Gini's gamma for a copula or for pseudo-observations stored as a d × n matrix. The generic copula method estimates the defining expectation numerically.

The normalization maps independence to zero and complete positive dependence to one. The sample form expects uniform-scale observations and replaces the population expectation by an empirical average. The generic copula method uses Monte Carlo expectation; its result therefore has sampling error unless a family supplies an exact specialization.

See also: corgini, pseudos, ρ.

source

Copulas.ι Method

ι(C::Copula)
ι(U::AbstractMatrix; k=5, p=Inf, leafsize=32)

Return copula entropy. For a copula with probability law $P_C$, Copulas.jl defines

$$\iota (C)=-D_{KL}(P_C\Vert {\lambda }^d),$$

where ${\lambda }^d$ is Lebesgue (uniform) measure on the unit hypercube. Hence independence has entropy zero, absolutely continuous dependent copulas have a non-positive value, and any copula with a singular component has entropy -Inf. For an absolutely continuous copula with density $c$, the definition reduces to $\iota (C)=E_C[-\log c(U)]$; generalized logpdf values of singular laws are deliberately not substituted into that density formula.

For data, a nearest-neighbor differential-entropy estimator is applied to the d × n pseudo-observation matrix. It assumes a continuous pseudo-sample, uses the kth neighbor under the Minkowski p-norm, and can be sensitive to ties, boundary effects and the choice of k. The Shannon entropy of an atomic empirical law is a different quantity from ι under the Lebesgue reference.

See also: corentropy, Copula, pseudos.

source

Copulas.λᵤ Method

λᵤ(C::Copula; ε=1e-10)
λᵤ(U::AbstractMatrix; p=nothing)

Return upper-tail dependence. The generic copula method applies the lower-tail calculation to the survival copula; the data method estimates joint upper-tail frequency at threshold p, defaulting to 1/√n. Family-specific exact formulas take precedence when available.

For a d × n input, rows are variables, columns are observations, and values must already be on the uniform scale. Smaller p targets a more extreme region but uses fewer observations. Likewise, ε is a numerical extrapolation scale, not a statistical tolerance; results can be unstable when a closed form is unavailable.

See also: λₗ, coruppertail, pseudos.

source

Copulas.λₗ Method

λₗ(C::Copula; ε=1e-10)
λₗ(U::AbstractMatrix; p=nothing)

Return lower-tail dependence. The generic copula method extrapolates diagonal CDF ratios near zero; the data method estimates joint lower-tail frequency at threshold p, defaulting to 1/√n. Family-specific exact formulas take precedence when available.

For a d × n input, rows are variables, columns are observations, and values must already be on the uniform scale. Smaller p targets a more extreme region but uses fewer observations. Likewise, ε is a numerical extrapolation scale, not a statistical tolerance; results can be unstable when a closed form is unavailable.

See also: λᵤ, corlowertail, pseudos.

source

Copulas.ρ Method

ρ(C::Copula)
ρ(U::AbstractMatrix)

Return multivariate Spearman's rho for a copula or for pseudo-observations stored as a d × n matrix. Family methods may provide exact formulas; the generic copula method uses numerical integration.

This is the normalized multivariate concordance coefficient based on ∫_[0,1]^d C(u) du; it is zero under independence and one under complete positive dependence. The sample form ranks each row internally, so it can also be applied to continuous raw observations. Numerical integration becomes costly as dimension grows and may be less accurate near singular limits.

See also: τ, StatsBase.corspearman, subsetdims.

source

Copulas.τ Method

τ(C::Copula)
τ(U::AbstractMatrix)

Return multivariate Kendall's tau for a copula or a d × n matrix of pseudo-observations. Family methods may replace the generic expectation-based calculation with an exact formula.

The population coefficient normalizes E[C(U)] for U ∼ C; the sample form counts concordant unordered pairs. It is zero under independence and one under complete positive dependence. The generic population method uses Monte Carlo expectation, so repeated calls need not be bitwise identical and exact family methods should be preferred when available. Ties in sample data do not receive a dedicated correction.

See also: ρ, StatsBase.corkendall, subsetdims.

source

Copulas.ϕ Function

ϕ(G::Generator, t)
ϕ(G::Generator)

Evaluate the Archimedean generator at t ≥ 0, or return its callable unary form. A valid implementation is decreasing, satisfies ϕ(G, 0) = 1, tends to zero at infinity, and has the monotonicity reported by max_monotony(G).

A downstream Generator subtype must implement the two-argument method. If it does not, Julia's normal method dispatch raises MethodError.

See also: Generator, max_monotony, ArchimedeanCopula, WilliamsonGenerator.

source

Copulas.ℓ Method

ℓ(tail::Tail, x)

Evaluate the stable tail dependence function at a nonnegative vector x. The generic implementation extends A from the simplex by one-homogeneity and returns zero at the origin.

See also: A, Tail, ExtremeValueCopula.

source

StatsAPI.pvalue Method

pvalue(test::CopulaTest)

Return the p-value of test.

Copula tests calibrate this value by simulation, randomization, multiplier resampling, or parametric bootstrap. It is therefore an approximation whose Monte Carlo precision depends on the requested number of resamples N.

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. L. Rüschendorf. On the distributional transform, Sklar's theorem, and the empirical copula process. Journal of Statistical Planning and Inference 139, 3921–3927 (2009).

5. A. E. Brockwell. Universal residuals: A multivariate transformation. Statistics & Probability Letters 77, 1473–1478 (2007).

6. A. Panagiotelis, C. Czado and H. Joe. Pair copula constructions for multivariate discrete data. Journal of the American Statistical Association 107, 1063–1072 (2012).

7. C. Genest and J. Nešlehová. A primer on copulas for count data. ASTIN Bulletin 37, 475–515 (2007).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.-F. Mai and M. Scherer. Bivariate extreme-value copulas with discrete Pickands dependence measure. Extremes 14, 311–324 (2011).

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

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

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

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

32. E. Liebscher. Construction of asymmetric multivariate copulas. Journal of Multivariate analysis 99, 2234–2250 (2008).

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

34. A. Heinen and A. Valdesogo. Spearman Rank Correlation of the Bivariate Student t and Scale Mixtures of Normal Distributions. Journal of Multivariate Analysis 179, 104650 (2020).

35. A. Genz. Numerical Computation of Multivariate Normal Probabilities. Journal of Computational and Graphical Statistics 1, 141–149 (1992).

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

37. A. Khoudraji. Contributions a l'etude des copules et a la modelisation de valeurs extremes bivariees. (Université Laval, 1996).

38. N. Schallhorn, D. Kraus, T. Nagler and C. Czado. D-vine quantile regression with discrete variables, arXiv preprint (2017), arXiv:1705.08310.