Internal implementation reference

The bindings listed on this page are implementation details, not supported API. They are collected here only to keep internal docstrings available to contributors and covered by Documenter's consistency checks. They may change without notice and do not define downstream extension contracts.

The developer guide describes the current contributor workflows and architecture. It is likewise descriptive rather than a semantic versioning commitment.

Copulas.AbstractReflectedCopula Type

julia

AbstractReflectedCopula{d,CT} <: Copula{d}

Internal supertype shared by copulas obtained by reflecting coordinates of an underlying copula of type CT. Implementations provide basecopula and flipmask; the common distribution and conditioning behaviour is then inherited from this interface.

Copulas.AbstractUnivariateGenerator Type

julia

AbstractUnivariateGenerator <: Generator

Internal capability type for parametric generators whose user-facing parameters are represented by a single univariate generator object. It is used to share constructor and fitting machinery; downstream packages must not rely on this subtype as a stable extension interface.

See also: Generator, FrailtyGenerator, _available_fitting_methods.

Copulas.BivEVDistortion Type

julia

BivEVDistortion(tail, conditioned_index, conditioned_value)

Internal uniform-scale conditional marginal for a bivariate extreme-value copula represented by tail. It evaluates the conditional CDF, density and quantile directly from the scalar Pickands function and its derivatives, including endpoint versions. conditioned_index identifies the observed coordinate. This fast-path must remain semantically equivalent to the generic extreme-value distortion and is not public API.

See also: BivariatePickandsTail, dA, d²A, distortion, condition.

Copulas.BivariatePickandsTail Type

julia

BivariatePickandsTail <: Tail

Internal capability type for tails that provide the scalar bivariate Pickands function A(tail, t). It activates generic derivatives, density, conditioning and sampling machinery. The capability is valid only in dimension two by default; a mathematically valid multivariate family must specialize _is_valid_in_dim explicitly. This subtype is not a stable downstream API.

See also: Tail, A, dA, d²A, _is_valid_in_dim.

Copulas.ConditionalCopula Type

julia

ConditionalCopula{d} <: Copula{d}

Internal fallback for the copula of the remaining coordinates U_I | U_J = u_J. It computes each conditional marginal distortion and uses mixed CDF partials to normalize the joint conditional law. Coordinates in I retain their natural order. Family-specific conditional_copula methods may replace this representation, so its fields are not a downstream contract.

See also: conditional_copula, distortion, _partial_cdf, condition.

Copulas.CopulaHypothesis Type

julia

CopulaHypothesis

Abstract supertype for hypotheses about copulas.

Each subtype is an internal, immutable description of one test procedure. The generic driver dispatches on it to obtain the discrepancy statistic, calibration algorithm, result labels and null-hypothesis text. A hypothesis must contain every option needed to reproduce those choices, but no mutable resampling state. This is not a public extension API.

See also: _run_copula_test, _teststatistic, _calibrate, CopulaTest.

Copulas.CopulaInference Type

julia

CopulaInference

Result of applying one uncertainty-quantification procedure to a fitted CopulaModel. It stores only the model, the inference method, and the resulting covariance matrix. Parameter blocks for composite models are derived from the fitted model when requested. Construct one with infer; its concrete fields remain implementation details.

Inference objects are immutable and independent: several procedures can be applied to the same fitted model without mutating it.

Copulas.CopulaMeasureStyle Type

julia

CopulaMeasureStyle

Internal measure-capability trait distinguishing copulas with an ordinary Lebesgue density from copulas with singular or mixed components. Algorithms use this trait to avoid manufacturing density-based behavior from the historical ContinuousMultivariateDistribution supertype. It is not public API.

See also: copula_measure_style, LimitKind, Copula.

Copulas.CopulaSelection Type

julia

CopulaSelection

Result of comparing an explicit collection of copula families. It keeps the winning CopulaModel and the candidate comparison separately, so model selection state does not bloat ordinary fitted models.

Use selected_model to retrieve the winner and selection_table to inspect all candidates. Concrete fields are implementation details.

Copulas.DistortedDist Type

julia

DistortedDist{Disto,Distrib} <: Distributions.UnivariateDistribution

Internal representation of a conditioned marginal on its original scale. D describes the conditional law on the uniform scale and X is the original univariate marginal. Consequently its CDF is D(cdf(X, x)), while quantiles apply the two generalized inverses in reverse order. This representation is used when conditioning a SklarDist; its storage fields are not public API.

See also: Distortion, condition, SklarDist.

Copulas.Distortion Type

julia

Distortion <: Distributions.ContinuousUnivariateDistribution

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

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

See also: distortion, DistortedDist, condition.

Copulas.DistortionFromCop Type

julia

DistortionFromCop{TC,p,q,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. The conditioning event is the intersection of a point condition U_js = ujs and a box condition U_bs ∈ ∏ₖ [lo[k], hi[k]]; either part may be empty.

Parameters

TC: copula type
p: length of the point-conditioned index set J (static)
q: length of the interval-conditioned index set B (static)
T: element type for the conditioned values u_J and the bounds

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.
DistortionFromCop(C::Copula, js, ujs, bs::NTuple{q,Int}, lo::NTuple{q,<:Real}, hi::NTuple{q,<:Real}, i::Int) additionally conditions on U_bs ∈ ∏ₖ [lo[k], hi[k]]; the denominator is then a probability rather than a density, and it throws an ArgumentError when the event has zero probability.

Notes

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

Copulas.EllipticalCopula Type

julia

EllipticalCopula

Internal abstract representation shared by elliptical copula implementations. Users should construct and operate on documented concrete families such as GaussianCopula and TCopula. Its type parameters and implementation hooks are not public API; the current contributor architecture is described in the developer guide.

See also: GaussianCopula, TCopula, U, N.

Copulas.LimitKind Type

julia

LimitKind

Internal classification of exact parameter limits: no recognized limit, independence (Π), comonotonicity (M), or the bivariate lower Fréchet–Hoeffding bound (W). Constructors and algorithms use it to select mathematically exact boundary behavior. Enum values are not stable API.

See also: limit_kind, CopulaMeasureStyle.

Copulas.MTail Type

julia

MTail()

Internal extreme-value tail for complete positive dependence. Its Pickands dependence function is A(t)=max(t,1-t) in dimension two and its stable tail dependence function is ℓ(x)=maximum(x), yielding the comonotonic MCopula. This parameter-free limiting representation is not part of the public component API.

Copulas.NestedDistortion Type

julia

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.

Copulas.NoTail Type

julia

NoTail()

Internal extreme-value tail for independence. Its Pickands dependence function is A(t)=1 and its stable tail dependence function is ℓ(x)=sum(x), so ExtremeValueCopula(d, NoTail()) reduces to the independent copula. This parameter-free implementation is used as a limiting representation and is not part of the public component API.

Copulas.SubsetCopula Type

julia

SubsetCopula(C::Copula, dims)

Internal fallback representing the marginal copula of C on the coordinates listed by dims. Coordinate order is significant, indices must be distinct and valid, and selecting one coordinate returns a uniform distribution rather than a SubsetCopula. Sampling projects samples from C; CDF evaluation fixes discarded coordinates at one.

Families may specialize this constructor to return a closed-form copula of the same marginal law. Such specializations must preserve the requested coordinate order and all distribution semantics. Public code should call subsetdims; the wrapper type and its fields are internal and unstable.

See also: subsetdims, conditional_copula, _cdf.

Copulas.TiltedGenerator Type

julia

TiltedGenerator(G, p, sJ)

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

julia

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

and higher derivatives accordingly:

julia

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

Copulas._CopulaFitSpec Type

julia

_CopulaFitSpec(target, method, kwargs)

Internal, reproducible description of the estimator that produced a CopulaModel. target is the family type or runtime structural template passed to fit; method selects the estimator; kwargs contains only arguments that change that estimator. Inference controls such as covariance computation are excluded. Composite goodness-of-fit tests consume this record to replay exactly the same estimator. Its fields and representation are not stable API.

See also: _fit, _refit, CopulaModel, GOFCopulaTest.

Copulas.N Method

julia

N(C::EllipticalCopula)

Return a constructor that maps a correlation matrix to the latent multivariate elliptical distribution associated with C. Generic sampling and density code requires consistency between this law and U(C). Object-based methods may capture runtime parameters. This is an internal, non-stable family hook.

See also: U, EllipticalCopula, GaussianCopula, TCopula.

Copulas.U Method

julia

U(C::EllipticalCopula)

Return the standardized univariate radial-family margin used to map latent elliptical coordinates to uniforms. This internal family hook is consumed by generic sampling and density code. Object-based methods may preserve runtime parameters such as Student degrees of freedom; it is not public API.

See also: N, EllipticalCopula, GaussianCopula, TCopula.

Copulas._available_fitting_methods Method

julia

_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. Maximum pseudo-likelihood (:mpl) is handled by the high-level public fitting entry point whenever :mle appears in this tuple; extensions should continue to advertise and implement only their actual _fit(..., Val{method}) dispatches.

Example

julia

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

See also: _fit, Distributions.fit.

Copulas._bootstrap_hypothesis Method

julia

_bootstrap_hypothesis(h::CopulaHypothesis, U)

Return the hypothesis used for a bootstrap replicate U. The internal default reuses h; composite goodness-of-fit specializes it to refit the estimator on every replicate. This distinction is required for valid composite-null calibration and is consumed by _calibrate.

See also: _calibrate, _refit, GOFCopulaTest.

Copulas._box_partial_cdf Method

julia

_box_partial_cdf(C, is, ps, bs, uis, ups, lo, hi)

Evaluate the mixed derivative with respect to the point coordinates ps of the C-volume of the box ∏ₖ [lo[k], hi[k]] on coordinates bs, at free coordinates is => uis, point coordinates ps => ups, and ones elsewhere. It is the inclusion–exclusion sum over the 2^q corners of the box of _partial_cdf with the box coordinates placed among the free ones, so q == 0 is _partial_cdf and ps == () is the C-volume computed by measure. This internal primitive is the numerator and denominator of interval conditioning, and the likelihood of a SklarDist with atoms.

See also: _partial_cdf, measure, condition.

Copulas._calibrate Method

julia

_calibrate(h::CopulaHypothesis, U, observed; N, rng)

Calibrate an observed internal test statistic under the null hypothesis h. Implementations return (p, n_resamples, details), where details is a NamedTuple consumed by result display and diagnostics. They must use only the provided rng, preserve the validated d × n orientation of U, and count the actual number of replicates in the result.

This internal protocol is called exclusively by _run_copula_test. A new in-package hypothesis pairs one calibration method with _teststatistic and _test_method; downstream users should call a public test constructor.

See also: _run_copula_test, _teststatistic, _test_method, _bootstrap_hypothesis.

Copulas._cdf Method

julia

_cdf(C::Copula, u)

Evaluate the copula CDF at an already dimension-checked point inside the unit hypercube. Concrete families normally specialize this internal primitive. The generic fallback numerically integrates pdf(C, ·) over [0,u] and therefore requires an ordinary density; it is unsuitable for singular copulas and may be expensive in high dimension. Public callers must use cdf.

See also: Distributions._rand!, copula_measure_style, Distributions.cdf.

Copulas._copula_of Method

julia

_copula_of(M::CopulaModel)

Return the copula contained in the fitted result, extracting it from a SklarDist when margins were fitted jointly. This helper is internal; callers that need the complete public fitted result should use fitted_distribution.

Copulas._discrete_spectral_rand! Method

julia

_discrete_spectral_rand!(rng, tail::DiscreteSpectralTail, X)

Fill the d × n matrix X with samples from the extreme-value copula induced by the finite spectral measure tail. The routine simulates the max-linear spectral representation and transforms unit-Fréchet coordinates to uniforms. It preserves the output buffer's element type and returns X. This reusable algorithm is internal; dispatch to it belongs in family-specific _rand! methods.

The rows of tail.B correspond to margins and its columns to finite spectral atoms. Constructors enforce the marginal moment constraints; callers must pass a buffer with the same number of rows. This routine deliberately implements sampling only: discrete-spectral laws may contain singular mass and therefore do not acquire a global Lebesgue density from this representation.

See also: DiscreteSpectralTail, ExtremeValueCopula, Distributions._rand!.

Copulas._div_factorial Method

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

Copulas._ellpartial_signlog Method

julia

_ellpartial_signlog(tail::Tail, x, I)

Return (sign, logabs) for the mixed partial of ℓ(tail, x) with respect to the coordinates in I. This internal signed-log protocol avoids overflow and underflow in extreme-value density and conditioning formulas. The generic fallback differentiates ℓ; specializations must preserve the derivative's sign and value, with (0, -Inf) representing zero.

See also: ellpartial, ℓ, _mixed_partial.

Copulas._estimate_sklar Method

julia

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

Fit the margins and dependence structure of a Sklar distribution to a d × n raw-data matrix X, with observations in columns. TplMargins supplies one univariate distribution family per row and CT supplies the copula family.

With sklar_method=:ifm, each fitted marginal CDF transforms its row to the uniform scale before the copula is fitted. With :ecdf, rank pseudo-observations are used instead, although the requested parametric margins are still fitted for the returned distribution. margins_kwargs are forwarded to every marginal fit and copula_kwargs to the copula fit.

Both routes are sequential estimators, not joint maximum likelihood for the complete Sklar distribution. Generic joint MLE is deliberately unavailable: Distributions.jl margin families do not expose a common protocol mapping their positive, bounded, ordered or interdependent parameters to an unconstrained optimization vector. params and a constructor alone cannot provide that information safely. The default is therefore sklar_method=:ifm; both Sklar routes use copula_method=:mle by default whenever CT supports MLE, otherwise its first advertised fitting method. That copula step may be replaced by another method supported by CT.

Moreover, calling Distributions.fit for a margin does not establish a generic maximum-likelihood contract. The fitting algorithm is selected by each distribution family and is not exposed here as a stable estimator protocol; it may therefore differ between margins and need not be maximum likelihood. A joint Sklar MLE cannot safely treat those independent calls as MLE building blocks without a stronger upstream or Copulas.jl-specific interface.

The result is a CopulaModel whose result is the fitted SklarDist. Calling infer with a resampling method repeats the complete sequential estimator, including every marginal fit and the copula fit. Analytical covariance is deliberately not inferred for the arbitrary marginal estimators selected by Distributions.fit. Use fit(SklarDist{...}, X; ...) when only the fitted distribution is required.

SklarDist{CT,TplMargins} is public here specifically as a fitting target: CT selects the copula family and TplMargins == Tuple{M₁,...,M_d} selects the marginal families. This exception does not expose arbitrary storage type parameters or the concrete representation of constructed SklarDist values.

weights gives one non-negative, finite weight per observation, not all zero, normalized to sum to n as in the copula-only fit, and every step reads the same vector: margin i is fitted by Distributions.fit(Mᵢ, xᵢ, w), which is the weighted maximum-likelihood fit fit_mle(Mᵢ, xᵢ, w) that Distributions.jl defines for the families with weighted sufficient statistics, and a margin family without one is refused by name, and a zero-weight observation is dropped before the margin sees it, as _weighted_sample drops it before the copula engine; :ecdf ranks by weighted mass as pseudos does; the copula is fitted with the same weights; the stored log-likelihood is the weighted one. Unit weights reproduce the unweighted margins up to rounding, since Distributions.jl reduces its weighted sufficient statistics in another order, and integer weights summing to n reproduce the fit of the sample in which each observation is repeated that many times. weights is a keyword of fit itself, not of copula_kwargs.

Copulas._falling_factorial Method

julia

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

Copulas._fit Method

julia

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

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

The fitted BernsteinCopula.

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

Copulas._fit Method

julia

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

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

Construct C = BetaCopula(U; kwargs...).

Arguments

U::AbstractMatrix: d×n matrix of pseudo-observations in [0,1].
kwargs...: Arguments passed back to the BetaCopula constructor.

Returns

The fitted BetaCopula.

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

Copulas._fit Method

julia

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

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

The fitted CheckerboardCopula.

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

Copulas._fit Method

julia

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

Internal entry point for fitting routines.

The three-argument entry point preserves the copula dimension as Val{d} and routes once through _fit_dispatch. Ordinary estimator implementations remain _fit(CT, U, Val(d), Val(method)); a family that takes over fitting regardless of the estimator can instead specialize _fit_dispatch without competing with method-specialized generic _fit methods.

Simple parametric families can use the generic implementations by defining an @paramorph structure or a constrained prototype. This is not intended for direct use by end-users; use [Distributions.fit(CopulaModel, ...)] instead.

See also: _available_fitting_methods, Distributions.fit.

Copulas._fit Method

julia

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

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

The fitted EmpiricalCopula.

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

Copulas._fit Method

julia

_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

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

The fitted EmpiricalEVCopula.

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

Copulas._fit_weights Method

julia

_fit_weights(weights, n) -> Union{Nothing, Vector}

Validate the observation weights passed to fit and normalize them so that they sum to n, the number of observations. nothing is returned untouched and selects the unweighted code path.

A weight is then read as "how many observations this column counts for": the fitted parameters are invariant to the scale of the weights, uniform weights reproduce the unweighted fit exactly, and nobs keeps the sample size that the information criteria use. A zero weight counts its column zero times; _weighted_sample drops such a column before any likelihood sees it.

See also: _weighted_sample, _weighted_loglikelihood, pseudos, Distributions.fit.

Copulas._has_specialized_copula_method Method

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

Copulas._hr Method

Small horizontal rule for section separation.

Copulas._is_valid_in_dim Method

julia

_is_valid_in_dim(tail::Tail, d::Int)

Return whether tail defines a valid stable tail dependence function in dimension d. This internal constructor-validation hook defaults to d ≥ 2; bivariate capability types restrict it unless a mathematical family explicitly provides a multivariate extension.

See also: Tail, BivariatePickandsTail, ℓ.

Copulas._kendall_sample Method

julia

_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).
Dominance is evaluated directly on u, preserving equal values. The result is therefore invariant under strictly increasing marginal transformations and under permutations of the observations, including when ties are present.
For any rank transformation that preserves ties, including the default pseudos(u; ties=:average), applying that transformation first leaves the empirical Kendall sample unchanged.

Returns

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

Copulas._kv Method

Key-value aligned printing for header lines.

Copulas._mixed_partial Method

julia

_mixed_partial(f, x, I)

Evaluate the mixed partial derivative of f at x with respect to the ordered coordinates in I, nesting ForwardDiff.derivative once per coordinate. An empty index set evaluates f(x). This internal shared fallback powers generic conditioning and stable-tail derivatives; callers requiring non-AD numerical kernels or singular derivatives must provide a specialized route.

Repeated indices request repeated differentiation in that coordinate. Indices must address coordinates of x; this low-level helper performs no semantic validation of a derivative's existence.

See also: _partial_cdf, _ellpartial_signlog, ellpartial.

Copulas._mul_factorial Method

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

Copulas._partial_cdf Method

julia

_partial_cdf(C, is, js, uis, ujs)

Evaluate the mixed derivative of the copula CDF with respect to coordinates js, at the point assembled from free coordinates is => uis, conditioned coordinates js => ujs, and ones elsewhere. This internal signed sub-density is the common denominator and numerator primitive for generic conditioning. The fallback uses automatic differentiation; a specialization is required when the numerical CDF cannot accept dual numbers or when singular semantics demand an exact implementation.

See also: _mixed_partial, distortion, conditional_copula.

Copulas._pstr Method

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

Copulas._quantile_from_cdf Method

julia

_quantile_from_cdf([strategy], d, p)

Compute the generalized quantile inf(x: cdf(d, x) >= p). Finite support bounds are taken from minimum(d) and maximum(d); infinite bounds are bracketed geometrically. LogCDFQuantile() selects logcdf as the monotone objective when ordinary CDF values may underflow.

Copulas._refit Method

julia

_refit(M::CopulaModel, data; replay_input=false)

Refit the same estimator specification that produced M. Copula models receive pseudo-observations; Sklar models receive observations on their original scales so that every marginal and the copula are re-estimated.

With replay_input=true, resampling inference replays the estimator from the same input scale as the original call. The default is reserved for composite GOF samples that are already pseudo-observations.

A resample of a weighted fit is refitted without the weights: it is a sample of the observations in which observation j is repeated weights[j] times, and the resampling procedures draw it as such.

This is an internal inference hook. A model is refittable only when its fitting entry point recorded a reproducible _CopulaFitSpec.

See also: _CopulaFitSpec, _fit, GOFCopulaTest.

Copulas._rising_factorial Method

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

Copulas._run_copula_test Method

julia

_run_copula_test(h::CopulaHypothesis, U; N=1000,
                 pseudo_values=false, rng=Random.default_rng())

Run the internal test protocol represented by h: validate and rank the input, evaluate _teststatistic, calibrate it with _calibrate, and assemble the public CopulaTest result. New in-package hypotheses use this driver after defining their statistic, calibration and display metadata. Inputs are d × n with observations in columns. This orchestration hook is internal and is not a supported downstream extension point.

See also: CopulaHypothesis, _teststatistic, _calibrate, _test_method, CopulaTest.

Copulas._section Method

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

Copulas._test_method Method

julia

_test_method(h::CopulaHypothesis)

Return (statistic, calibration) symbols describing the procedure represented by internal hypothesis h. The generic CopulaTest display uses these labels; they must agree with _teststatistic and _calibrate and are not selectors for runtime algorithm combinations.

See also: _run_copula_test, _teststatistic, _calibrate, CopulaTest.

Copulas._teststatistic Method

julia

_teststatistic(h::CopulaHypothesis, U)

Evaluate the internal discrepancy statistic for hypothesis h on validated pseudo-observations U, stored as variables by observations (d × n). Larger values must represent greater disagreement with the null because calibration counts upper-tail exceedances. The result must be deterministic for fixed U; randomness belongs in _calibrate.

See also: _run_copula_test, _calibrate, _test_method.

Copulas._weighted_loglikelihood Method

julia

_weighted_loglikelihood(D, X, weights)

Log-likelihood of D on the columns of X, each column multiplied by its weight. With weights === nothing this is Distributions.loglikelihood(D, X). The weighted sum runs over the same column views in the same order as the unweighted reduction, so unit weights reproduce it bit for bit. A zero-weight column is dropped by _weighted_sample rather than summed.

See also: _fit_weights, StatsBase.nobs.

Copulas._weighted_sample Method

julia

_weighted_sample(X, weights) -> (X, weights)

The columns of X that carry weight, with their weights. A zero weight removes its observation, so the pair is what a likelihood engine is given: a removed observation may sit on the boundary of the unit hypercube, where its score is infinite and 0 * Inf would poison a weighted cross-product. Without a zero weight, and with weights === nothing, the inputs are returned untouched.

See also: _fit_weights, _weighted_loglikelihood.

Copulas._williamson_tail_expectation Method

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

Copulas.composition_taylor Method

julia

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):
julia
```
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]:
julia
```
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.

Copulas.composition_taylor_direct Method

julia

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.

Copulas.composition_taylor_implicit Method

julia

composition_taylor_implicit(outer::Generator, inner::Generator, 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.

Copulas.conditional_copula Method

julia

conditional_copula(C::Copula, js, ujs)

Return the copula of the remaining coordinates conditional on U[js] = ujs. The internal fallback builds a ConditionalCopula from mixed CDF partials and the marginal distortions. A family specialization may provide a simpler or faster representation, but must preserve the remaining coordinates' natural order and the same conditional law. Public code should call condition.

See also: ConditionalCopula, distortion, _partial_cdf, condition.

Copulas.copula_measure_style Method

julia

copula_measure_style(C)

Return the internal CopulaMeasureStyle of C. The default assumes absolute continuity; singular or mixed families and exact parameter limits must specialize it. This trait controls density-dependent generic operations and is not a downstream extension contract.

See also: CopulaMeasureStyle, limit_kind, Distributions logpdf.

Copulas.dA Method

julia

dA(tail::BivariatePickandsTail, t)

Evaluate the first derivative of the scalar Pickands function. The internal fallback uses forward-mode automatic differentiation; specialized formulas must retain the same one-sided behavior used by endpoint conditionals.

See also: A, d²A, BivariatePickandsTail.

Copulas.distortion Method

julia

distortion(C::Copula, js, ujs, i)

Return the uniform-scale conditional marginal of coordinate i given U[js] = ujs. This internal extension hook defaults to DistortionFromCop, which uses mixed CDF partials. Family specializations may provide a faster or atom-aware distribution but must preserve the same coordinate ordering, scale, and conditional-law semantics. Use public condition in downstream code.

See also: conditional_copula, _partial_cdf, Distortion, condition.

Copulas.d²A Method

julia

d²A(tail::BivariatePickandsTail, t)

Evaluate the second derivative of the scalar Pickands function. The internal fallback differentiates dA. It represents an ordinary derivative and is not appropriate for atomic spectral curvature, which uses discrete-spectral machinery instead.

See also: A, dA, BivariatePickandsTail, DiscreteSpectralTail.

Copulas.ellpartial Method

julia

ellpartial(tail::Tail, x, I)

Evaluate the mixed partial derivative of the STDF with respect to coordinates I. An empty index set returns ℓ(tail, x). This is internal contributor machinery consumed by generic extreme-value CDF, density and conditioning algorithms; defining ℓ supplies an automatic-differentiation fallback.

See also: _ellpartial_signlog, ℓ, ExtremeValueCopula.

Copulas.fitting_method Method

julia

fitting_method(model::CopulaModel) -> Symbol

Return the effective estimator that produced model. The value is derived from the model's reproducible fitting recipe.

Copulas.limit_kind Method

julia

limit_kind(component, ::Val{d})

Classify whether a generator, tail, or composite component is exactly at a canonical dependence limit in dimension d. Internal constructors and algorithms use the result to preserve independence, comonotonicity, or the bivariate lower bound without relying on approximate parameter comparisons. Families return NO_LIMIT away from those values. This protocol is not public API.

See also: LimitKind, CopulaMeasureStyle, Generator, Tail.

Copulas.make_cor! Method

julia

make_cor!(Σ)

Normalize the square covariance-like matrix Σ in place to unit diagonal by the congruence transform Σ[i,j] / sqrt(Σ[i,i]Σ[j,j]). The diagonal entries must be strictly positive and the element type must support the in-place division. The function does not check symmetry, positive definiteness, or whether the resulting entries form a valid correlation matrix; constructors must perform the validation required by their family.

This is an internal constructor helper. Copy user-owned input before calling it when mutation would be surprising.

See also: EllipticalCopula, GaussianCopula, TCopula.

Copulas.nullhypothesis Method

julia

nullhypothesis(x)

Return the textual null hypothesis for a copula hypothesis or test. This is an extension hook used by the generic display machinery.

Internal hypothesis implementations specialize this function with a concise, human-readable statement. It is consumed by show for CopulaTest results and is not a supported downstream extension interface.

See also: testname, CopulaHypothesis, CopulaTest.

Copulas.taylor Method

julia

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^{'} (x ₀), . . ., f^{(d)} (x ₀))$ .

Copulas.testname Method

julia

testname(x)

Return the display name for a copula hypothesis or test.

This is an extension hook for new copula tests. It is intentionally not exported to avoid clashes with HypothesisTests.testname.

See also: nullhypothesis, CopulaHypothesis, CopulaTest.

Copulas.ϕ⁻¹ Method

julia

ϕ⁻¹(G::Generator, u)

Return the generalized inverse of ϕ(G, ·) at u ∈ [0,1]. The generic internal fallback uses scalar root finding; generator implementations may specialize it for accuracy, boundary behavior, or performance.

See also: ϕ, ϕ⁽¹⁾, Generator.

Copulas.ϕ⁻¹⁽¹⁾ Method

julia

ϕ⁻¹⁽¹⁾(G::Generator, u)

Evaluate the derivative of the inverse generator through 1 / ϕ⁽¹⁾(G, ϕ⁻¹(G, u)). This is an internal conditioning and sampling hook; specializations must agree with that identity wherever the inverse is regular.

See also: ϕ⁻¹, ϕ⁽¹⁾, distortion.

Copulas.ϕ⁽¹⁾ Method

julia

ϕ⁽¹⁾(G::Generator, t)

Evaluate the first derivative of the generator. The generic internal fallback uses forward-mode automatic differentiation. Specialized methods must preserve the derivative of ϕ, including its sign and limiting behavior.

See also: ϕ, ϕ⁻¹⁽¹⁾, ϕ⁽ᵏ⁾.

Copulas.ϕ⁽ᵏ⁾ Method

julia

ϕ⁽ᵏ⁾(G::Generator, k::Int, t)

Evaluate the derivative of order k ≥ 0. The generic internal fallback uses a Taylor expansion. A specialization is a numerical fast path and must return the same derivative, with k = 0 corresponding to ϕ(G, t).

See also: ϕ, ϕ⁽¹⁾, ϕ⁽ᵏ⁾⁻¹.

Copulas.ϕ⁽ᵏ⁾⁻¹ Method

julia

ϕ⁽ᵏ⁾⁻¹(G::Generator, k::Int, y; start_at=y)

Invert the kth generator derivative on the relevant monotone branch. The generic internal fallback expands a positive bracket and applies bisection. start_at identifies the lower branch boundary used by tilted generators.

See also: ϕ⁽ᵏ⁾, ϕ⁻¹, Generator.

Distributions._rand! Method

julia

Distributions._rand!(rng, C::Copula{d}, X::AbstractMatrix)

Internal sampling primitive for copulas. A concrete implementation fills and returns the preallocated d × n matrix X, with one observation per column, using only rng for randomness and preserving the buffer element type. The public vector sampler delegates to this method. Concrete families must provide a matrix specialization; callers should use rand or rand!.

See also: _cdf, Copula, inverse_rosenblatt.

StatsAPI.aic Method

julia

aic(M::CopulaModel) -> Float64

Return Akaike's information criterion 2k - 2ℓ, using k = dof(M) and the log-likelihood stored in the model. Comparisons are meaningful only for models fitted to the same observations and likelihood contribution.

See also: StatsBase.bic, StatsBase.deviance, selection_table.

StatsAPI.bic Method

julia

bic(M::CopulaModel) -> Float64

Return the Bayesian information criterion k log(n) - 2ℓ, using k = dof(M) and n = nobs(M). Comparisons are meaningful only for models fitted to the same observations and likelihood contribution.

See also: StatsBase.aic, StatsBase.deviance, selection_table.

StatsAPI.coef Method

julia

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

Return the fitted model's natural parameters as a flat vector in the same order as coefnames(M). Structured values are flattened mechanically: matrices expose all entries, including symmetry or fixed diagonals, and simplex vectors expose all probabilities. Consequently length(coef(M)) need not equal dof(M). Parameter-free and nonparametric components return no coefficients.

See also: StatsBase.coefnames, StatsBase.vcov, StatsBase.confint.

StatsAPI.coefnames Method

coefnames(M::CopulaModel) -> Vector

Return names for the flattened parameters in coef(M), in matching order. Indices are appended to vector and matrix parameter names so each coefficient can be identified in covariance matrices and printed summaries.

See also: StatsBase.coef, StatsBase.vcov, CopulaModel.

StatsAPI.confint Method

Return pointwise Wald intervals from a CopulaInference result.

StatsAPI.deviance Method

julia

deviance(M::CopulaModel) -> Float64

Return the deviance -2ℓ, where ℓ is the maximized log-likelihood stored in the model. For non-likelihood estimators this summary reflects the likelihood evaluated at the fitted parameters, not the objective that was optimized.

See also: StatsBase.nulldeviance, StatsBase.aic, StatsBase.bic.

StatsAPI.dof Method

julia

dof(M::CopulaModel) -> Int

Return the statistical number of free estimated parameters. This is determined from the fitted model's Paramorph schema and is intentionally independent of length(coef(M)): natural coefficients may contain redundant or fixed entries, such as both halves and the unit diagonal of a correlation matrix.

See also: StatsBase.coef, StatsBase.coefnames, StatsBase.aic.

StatsAPI.fit Method

julia

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

Fit CT to the d × n matrix U, whose columns are observations, and return only the fitted copula or Sklar distribution. This is the concise form of fit(CopulaModel, CT, U; kwargs...): it uses the same estimator and validation without first constructing a CopulaModel. The same normalized estimator is used by the model-returning form.

Use the CopulaModel form when diagnostics, information criteria, later uncertainty quantification through infer, automatic selection, or composite goodness-of-fit testing are needed.

StatsAPI.fit Method

julia

fit(CopulaModel, Copula, U; candidates, criterion=:bic, method=:mle, kwargs...)

Fit an explicit collection of candidate families and return a CopulaSelection selecting the smallest finite information criterion (:bic, :aic, :aicc, or :hqc). The winning fit is reused without performing inference. Prefer maximum likelihood fitting when interpreting these as information criteria.

Failed candidates are recorded with on_error=:skip, or rethrown with on_error=:throw. Interruptions always propagate. Composite GOF after selection is not yet supported.

StatsAPI.fit Method

julia

fit(CopulaModel, C0::NestedArchimedeanCopula, U)        # template tree
fit(CopulaModel, reparam, init, U)                      # custom parametrisation

Maximum-likelihood estimation of the generator parameters of a nested Archimedean copula. U is a d×n matrix of pseudo-observations (columns = observations). The optimiser runs in an unconstrained space through a parametrisation — a map α -> NestedArchimedeanCopula decoupled from the generator objects — supplied in one of two ways:

template C0: a template instance whose tree shape (leaf layout, children blocks) and per-node generator families are kept fixed. For the supported standard one-parameter nesting rules, Paramorph jointly constrains parent and child parameters so every finite optimiser coordinate maps to a valid nesting.
custom reparam, init: your own map reparam(α) -> copula and its initial α₀ (no template needed — the map fully defines the tree). Use it to share parameters across nodes, change the per-generator parametrisation (e.g. fit on a Kendall-τ scale), or enforce a constraint such as nesting (parametrise each child's θ as a non-negative increment over its parent's). reparam must build the tree from α generically so ForwardDiff can differentiate it.

fit(C0, U) is a quick shim returning only the fitted copula; for the custom form use fitted_distribution(fit(CopulaModel, reparam, init, U)).

Both forms take weights, one non-negative weight per observation, with the semantics documented for fit(CopulaModel, CT, U): a weighted pseudo-likelihood whose weights are normalized to sum to the number of observations.

StatsAPI.isfitted Method

julia

isfitted(M::CopulaModel) -> Bool

Return true: a CopulaModel exists only after its fitting procedure has produced an accepted result.

See also: CopulaModel, Distributions.fit.

StatsAPI.nobs Method

julia

nobs(M::CopulaModel) -> Int

Number of observations used in the model fit.

Observations are columns of the matrix supplied to fit. This value is the sample size used by likelihood summaries and information criteria. A weighted fit normalizes its weights to sum to this number, so it reports the same value.

See also: CopulaModel, StatsBase.dof, StatsBase.aic, StatsBase.bic.

StatsAPI.nobs Method

julia

nobs(test::CopulaTest)

Return the number of observations used by the copula test. Each observation is one column of the matrix supplied to the test constructor.

StatsAPI.nulldeviance Method

julia

nulldeviance(M::CopulaModel)

Return -2 * nullloglikelihood(M). The null likelihood is reconstructed lazily and follows the same null-model conventions.

See also: StatsBase.nullloglikelihood, StatsBase.deviance.

StatsAPI.nullloglikelihood Method

julia

nullloglikelihood(M::CopulaModel)

Compute the null-model log-likelihood lazily. Copula-only models use the independence copula. Sklar models preserve the fitted margins and replace only their copula by independence.

See also: StatsBase.nulldeviance, StatsBase.deviance, CopulaModel.

StatsAPI.residuals Method

julia

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. Rows correspond to variables and columns to the observations stored by the fit. Normal residuals can be infinite when a uniform residual is exactly zero or one. For singular or atomic conditional laws, Rosenblatt residuals need not be independent uniforms and should not be used as a continuous-model diagnostic.

See also: rosenblatt, GOFCopulaTest, fitted_distribution.

StatsAPI.stderror Method

Return standard errors derived from a CopulaInference covariance matrix.

StatsAPI.vcov Method

julia

vcov(I::CopulaInference; component=:all)

Return the covariance matrix computed by infer. For a fitted SklarDist, component=:copula selects the copula block and component=:margins selects all marginal blocks. The default :all preserves cross-component covariance.