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

julia

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.

VineCopulas._chatterjee_xi Method

julia

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

VineCopulas._check_groups Method

julia

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

VineCopulas._check_threshold Method

julia

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

VineCopulas._check_weighted_tree_criterion Method

julia

_check_weighted_tree_criterion(criterion, weights)

Refuse, before any fit, a built-in tree criterion that has no weighted form when observation weights are given. :tau, :rho, :joe and a function pass; :hoeffd, :mcor and :cxi throw an ArgumentError.

VineCopulas._compile_standard_rvine Method

julia

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

VineCopulas._gaussian_mutual_information Method

julia

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

VineCopulas._hoeffding_d Method

julia

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

VineCopulas._kendall_independence_pvalue Method

julia

_kendall_independence_pvalue(τhat, n)

Two-sided p-value of the asymptotic Kendall independence test. Under independence the sample tau of n continuous observations is approximately normal with variance 2(2n+5) / (9n(n-1)), so the statistic is 3 τhat √(n(n-1)) / √(2(2n+5)). This is the indeptest of vinecopulib.

VineCopulas._kendall_tau_b Method

julia

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

VineCopulas._kendall_tau_w Method

julia

_kendall_tau_w(x, y, w)

Weighted Kendall tau-b,

julia

τ_w = Σ_{i<j} w_i w_j sgn(x_i − x_j) sgn(y_i − y_j) / √((W0 − W1)(W0 − W2)),

with W0 = Σ_{i<j} w_i w_j and W1, W2 the weighted counts of pairs tied in x and in y. It is the same O(n log n) sweep as _kendall_tau_b with weight sums in place of counts, and it equals tau-b when w ≡ 1.

VineCopulas._max_weight_hamiltonian_path Method

julia

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

VineCopulas._maximum_correlation Method

julia

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

VineCopulas._maximum_spanning_tree Method

julia

_maximum_spanning_tree(candidates, nvertices; groups=nothing)

Deterministic Kruskal maximum spanning tree over candidates, ordered by decreasing weight with the existing label-based tie break.

When groups is supplied, it contains one integer group id per tree-1 vertex. The selected tree is restricted so that every group induces a connected subtree.

For the complete candidate graph of R-vine tree 1, the constrained optimum is obtained exactly by processing within-group edges before cross-group edges, with decreasing weight inside each class. Equivalently, this builds a maximum spanning tree inside each group and then connects the contracted groups through cross-group edges.

The grouped form is used only for tree 1. Higher R-vine trees retain the ordinary proximity-constrained selection.

VineCopulas._tree_dependence Function

julia

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

With observation weights w (the last argument; nothing is the unweighted path) :tau, :rho and :joe take their weighted form, _kendall_tau_w, _spearman_rho_w and _gaussian_mutual_information_w, the statistic of the sample in which observation i is repeated w[i] times. :hoeffd, :mcor and :cxi have no weighted form here, so _check_weighted_tree_criterion refuses them with weights before any fit. A function receives the full columns, aligned with w, and no weight: a weighted custom criterion closes over the weight vector.