Internal API (for reference)

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

Copulas.ConditionalCopula Type

ConditionalCopula{d} <: Copula{d}

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

source

Copulas.DistortedDist Type

DistortedDist{Disto,Distrib} <: Distributions.UnivariateDistribution

Push-forward of a base marginal by a Distortion.

source

Copulas.DistortionFromCop Type

DistortionFromCop{TC,p,T} <: Distortion

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

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

Parameters

• TC: copula type

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

• T: element type for the conditioned values u_J

Construction

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

Notes

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

source

Copulas.EllipticalCopula Type

EllipticalCopula{d,MT}

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

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

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

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

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

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

Details

Recall the definition of spherical random vectors:

Definition - Spherical and elliptical random vectors

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

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

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

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

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

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

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

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

References:

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

source

Copulas.MTail Type

MTail

Corresponds to the MCopula viewed as an etreme value copula.

source

Copulas.NestedDistortion Type

NestedDistortion{TC,p,D} <: Distortion

Closed-form conditional marginal U_i | U_js = u_js of a NestedArchimedeanCopula. Its cdf(D, u_i) is the mixed partial of the nested CDF over the conditioned set js (with i and every other coordinate entering only as CDF arguments), divided by the observed-marginal density c_O = pdf(subsetdims(C, js), u_js). This routes the numerator through our O(d²) Faà di Bruno tree walk rather than ForwardDiff. Handles general p, so it is reused for each per-coordinate distortion the generic ConditionalCopula constructor builds in the multi-unobserved case.

source

Copulas.NoTail Type

NoTail

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

source

Copulas.SubsetCopula Type

SubsetCopula{d,CT}

Fields:

• C::CT - The copula

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

Constructor

SubsetCopula(C::Copula,dims)

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

source

Copulas.TiltedGenerator Type

TiltedGenerator(G, p, sJ)

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

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

and higher derivatives accordingly:

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

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

source

Copulas._available_fitting_methods Method

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

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

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

Example

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

source

Copulas._copula_of Method

_copula_of(M::CopulaModel)

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

source

Copulas._div_factorial Method

Divide x by k! without first forming an integer factorial.

source

Copulas._falling_factorial Method

_falling_factorial(x, k)

Compute x * (x - 1) * ⋯ * (x - k + 1) without forming factorials or using loggamma. The implementation also applies to non-integer x.

source

Copulas._fit Method

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

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

Arguments

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

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

or nothing for automatic selection.

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

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

Returns

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

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

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

source

Copulas._fit Method

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

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

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

Arguments

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

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

Returns

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

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

source

Copulas._fit Method

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

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

Arguments

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

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

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

• kwargs...: forwarded to the constructor.

Returns

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

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

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

source

Copulas._fit Method

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

Internal entry point for fitting routines.

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

• copula is the fitted copula instance,

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

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

source

Copulas._fit Method

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

Constructs the empirical Deheuvels copula from U.

Arguments

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

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

Returns

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

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

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

source

Copulas._fit Method

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

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

Arguments

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

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

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

• eps: extreme trimming for numerical stability.

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

Returns

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

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

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

source

Copulas._hr Method

Small horizontal rule for section separation.

source

Copulas._kendall_sample Method

_kendall_sample(u::AbstractMatrix)

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

Input and tie handling

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

Returns

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

source

Copulas._kv Method

Key-value aligned printing for header lines.

source

Copulas._mul_factorial Method

Multiply x by k! without first forming an integer factorial.

source

Copulas._print_dependence_metrics Method

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

source

Copulas._print_marginals_section Method

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

source

Copulas._print_param_section Method

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

source

Copulas._pstr Method

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

source

Copulas._rising_factorial Method

Compute x * (x + 1) * ⋯ * (x + k - 1) directly.

source

Copulas._section Method

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

source

Copulas._williamson_tail_expectation Method

Generic fallback for ϕ on WilliamsonGenerator (non-discrete-nonparametric TX). Specializations for TX<:DiscreteNonParametric are provided below.

source

Copulas.composition_taylor Method

composition_taylor(outer::Generator, inner::Generator, t₀, d) -> Vector

Overridable hook for the parent→child edge composition in a nested Archimedean density. Returns the Taylor coefficients [h⁽¹⁾(t₀)/1!, …, h⁽ᵈ⁾(t₀)/d!] (the constant term h₀ dropped) of the inner-to-outer change of variables h = ϕ⁻¹_outer ∘ ϕ_inner.

The default delegates to composition_taylor_direct. Select a different method, or supply your own, by adding a method to this function — most-specific wins, no keyword or flag, mirroring the per-generator ϕ⁽ᵏ⁾ override idiom:

• switch globally to the implicit solver composition_taylor_implicit (paper App. A.4 — uses only scalar ϕ⁽ᵏ⁾ and one scalar ϕ⁻¹, never a Taylor1 through ϕ⁻¹; the method to use when a generator's ϕ⁻¹ has no Taylor1 method):

  Copulas.composition_taylor(o::Copulas.Generator, i::Copulas.Generator, t₀, d) =
      Copulas.composition_taylor_implicit(o, i, t₀, d)

• register a closed form for a generator pair (fastest, most robust — see the Clayton/Clayton method in Generator/ClaytonGenerator.jl).

• roll your own with the taylor primitive: jet your (possibly hand-simplified) link and drop the constant term — taylor returns [f(t₀), f'(t₀)/1!, …], so take [2:d+1]:

  Copulas.composition_taylor(o::MyGen, i::MyGen, t₀, d) =
      Copulas.taylor(t -> Copulas.ϕ⁻¹(o, Copulas.ϕ(i, t)), t₀, d)[2:d+1]

The working type flows from t₀, so BigFloat/Double64 precision is carried through whichever method is selected.

source

Copulas.composition_taylor_direct Method

composition_taylor_direct(outer, inner, t₀, d)

Default edge composition (see composition_taylor): a single Taylor jet over the explicit composition ϕ⁻¹_outer ∘ ϕ_inner at t₀, returning the coefficients [h⁽ᵏ⁾(t₀)/k! for k in 1:d]. Requires both ϕ and ϕ⁻¹ to accept a Taylor1 argument.

source

Copulas.composition_taylor_implicit Method

composition_taylor_implicit(outer, inner, t₀, d)

Edge composition by implicit differentiation (paper App. A.4; see composition_taylor): h satisfies ϕ_outer(h(t)) = ϕ_inner(t), solved order by order by a triangular system using only the scalar derivatives ϕ⁽ᵏ⁾ of both generators and one scalar ϕ⁻¹_outer — it never puts a Taylor1 through ϕ⁻¹, so it is the method to use when a generator's ϕ⁻¹ has no Taylor1 method. Returns the same [h⁽ᵏ⁾(t₀)/k! for k in 1:d] convention as composition_taylor_direct.

source

Copulas.taylor Method

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

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

Arguments

• f: A function to be expanded.

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

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

Returns

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

source

StatsAPI.aic Method

aic(M::CopulaModel) -> Float64

Akaike information criterion for the fitted model.

source

StatsAPI.bic Method

bic(M::CopulaModel) -> Float64

Bayesian information criterion for the fitted model.

source

StatsAPI.coef Method

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

Vector with the estimated parameters of the copula.

source

StatsAPI.coefnames Method

coefnames(M::CopulaModel) -> Vector

Names of the estimated copula parameters.

source

StatsAPI.deviance Method

deviance(M::CopulaModel) -> Float64

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

source

StatsAPI.fit Method

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

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

source

StatsAPI.fit Method

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

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

Arguments

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

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

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

Returns

A CopulaModel containing the fitted copula and metadata.

Examples

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

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

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

source

StatsAPI.fit Method

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

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

source

StatsAPI.nobs Method

nobs(M::CopulaModel) -> Int

Number of observations used in the model fit.

source

StatsAPI.params Method

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

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

Arguments

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

Returns

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

source

StatsAPI.predict Method

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

Predict or simulate from a fitted copula model.

Keyword arguments

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

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

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

Returns

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

source

StatsAPI.residuals Method

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

Compute Rosenblatt residuals of a fitted copula model.

Arguments

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

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

Notes

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

source

StatsAPI.vcov Method

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

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

source

References

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