Internal API

The names on this page are implementation details and may change without a deprecation cycle. User code should prefer the public API.

Base.rand Method

rand([rng], vine, n; fixed=nothing)
rand!([rng], A, vine; fixed=nothing)

Draw n observations from a vine copula as a p × n matrix.

With fixed = (js, Ujs) the coordinates js are held at the uniforms Ujs and the remaining coordinates are drawn from their conditional law given those values, so the result is an exact sample from  . Ujs is a length(js) × n matrix, or a tuple or vector of length(js) scalars broadcast over every column, of uniforms in [0, 1]; any other value is an ArgumentError. The rows js of the result hold the supplied values exactly, and a boundary value 0 or 1 conditions the recursion at the nearest interior floating-point number. The draw is exact only when admits_conditioning(vine, js) is true; otherwise an ArgumentError names the fix. See inverse_rosenblatt for the mechanism.

source

VineCopulas._chatterjee_xi Method

_chatterjee_xi(x, y)

Chatterjee's (2021) coefficient  : with the observations sorted by x (ties in x keep their sample order), the number of   and the number of  ,

which reduces to     without ties in y. It measures how well y is a function of x, so it is asymmetric; the population value is in and the estimate can be slightly negative. A constant y gives 0.

source

VineCopulas._check_groups Method

_check_groups(groups, p)

groups is nothing or a vector of p integer group ids, one per variable; the ids themselves carry no meaning beyond equality.

source

VineCopulas._check_threshold Method

_check_threshold(threshold, criterion)

threshold is compared with the tree criterion's value on the criterion's own scale (force_independence = w_e < threshold), so its admissible range follows the criterion: [0, 1] for :tau, :rho, :hoeffd, :mcor and :cxi, [0, ∞) for :joe, and any finite value for a custom function.

source

VineCopulas._compile_standard_rvine Method

_compile_standard_rvine(vc)

Compile a standard (order, struct_array) R-vine into a DAG of conditional states. An edge (a,b | D) consumes states (a|D) and (b|D) and produces (a|D∪{b}) and (b|D∪{a}).

This representation is label-invariant and therefore remains correct for non-identity variable orders.

source

VineCopulas._gaussian_mutual_information Method

_gaussian_mutual_information(x, y)

Joe's (1989) relative-entropy dependence measure under a Gaussian copula: with the Pearson correlation of the normal scores , , the mutual information  , in . It is strictly increasing in , so as a tree criterion it selects the same trees as on normal scores; its scale matters only to threshold. This is vinecopulib's joe criterion. The value is Inf when the normal scores are exactly linearly dependent.

source

VineCopulas._hoeffding_d Method

_hoeffding_d(x, y)

Hoeffding's statistic (Hoeffding 1948) in the computational form of Hollander & Wolfe, scaled by 30 so that the population value lies in  : 0 under independence, 1 under a monotone functional relation. With , the ranks of , and one plus the number of observations below in both coordinates,

Ties are counted strictly (an equal coordinate is not "below"), which is the form vinecopulib's hoeffd criterion computes. Requires n ≥ 5; O(n log n).

source

VineCopulas._kendall_tau_b Method

_kendall_tau_b(x, y)

O(n log n) Kendall tau-b. Ties in x are handled by querying all observations in an x-tie block before inserting that block into the Fenwick tree.

source

VineCopulas._max_weight_hamiltonian_path Method

_max_weight_hamiltonian_path(W)

Held-Karp dynamic programming for the maximum-weight Hamiltonian path. This is exact and is used only below exact_order_max.

source

VineCopulas._maximum_correlation Method

_maximum_correlation(x, y)

The maximum correlation coefficient of Gebelein (1941) and Rényi (1959), , estimated by the alternating conditional expectations (ACE) algorithm of Breiman & Friedman (1985): the transforms , are updated in turn as the smoothed conditional expectation of the other, with a running-mean smoother of half-width , at most 10 inner and 100 outer iterations, and stopping tolerances (inner) and   (outer) on the change of the mean squared difference of the two transforms. The value is the Pearson correlation of the converged transforms, in . These are the constants of vinecopulib's mcor criterion, so the two agree on the same data. Requires n ≥ 3, so that at least one full smoothing window exists.

source

VineCopulas._tree_dependence Method

_tree_dependence(x, y, a, b, D, criterion)

Weight of the candidate edge (a, b | D) whose conditional pseudo-observations are x and y. The built-in criteria are the absolute value of a documented statistic:

criterion	statistic	range
:tau	Kendall's (_kendall_tau_b)
:rho	Spearman's (_spearman_rho)
:hoeffd	Hoeffding's (_hoeffding_d)
:mcor	maximum correlation by ACE (_maximum_correlation)
:joe	Gaussian-copula mutual information (_gaussian_mutual_information)
:cxi	symmetrised Chatterjee (_symmetric_chatterjee_xi)

A function is called as criterion(x, y, a, b, D) and its value, used as is (no absolute value), is the weight. It must be a finite Real; anything else is an ArgumentError naming the edge and the value.

source