RVineStructure

class RVineStructure(*args, **kwargs)

A class for R-vine structures.

RVineStructure objects encode the tree structure of the vine, i.e. the conditioned/conditioning variables of each edge. It is represented by a triangular array. An exemplary array is

4 4 4 4
3 3 3
2 2
1

which encodes the following pair-copulas:

| tree | edge | pair-copulas |
|------|------|--------------|
| 0    | 0    | (1, 4)       |
|      | 1    | (2, 4)       |
|      | 2    | (3, 4)       |
| 1    | 0    | (1, 3; 4)    |
|      | 1    | (2, 3; 4)    |
| 2    | 0    | (1, 2; 3, 4) |

Denoting by M[i, j] the array entry in row i and column j, the pair-copula index for edge e in tree t of a d dimensional vine is (M[d - 1 - e, e], M[t, e]; M[t - 1, e], ..., M[0, e]). Less formally,

1. Start with the counter-diagonal element of column e (first conditioned variable).

2. Jump up to the element in row t (second conditioned variable).

3. Gather all entries further up in column e (conditioning set).

Internally, the diagonal is stored separately from the off-diagonal elements, which are stored as a triangular array. For instance, the off-diagonal elements off the structure above are stored as

4 4 4
3 3
2

for the structure above. The reason is that it allows for parsimonious representations of truncated models. For instance, the 2-truncated model is represented by the same diagonal and the following truncated triangular array:

4 4 4
3 3

A valid R-vine array must satisfy several conditions which are checked when RVineStructure() is called:

1. It only contains numbers between 1 and d.

2. The diagonal must contain the numbers 1, …, d.

3. The diagonal entry of a column must not be contained in any column further to the right.

4. The entries of a column must be contained in all columns to the left.

5. The proximity condition must hold: For all t = 1, …, d - 2 and e = 0, …, d - t - 1 there must exist an index j > d, such that (M[t, e], {M[0, e], ..., M[t-1, e]}) equals either (M[d-j-1, j], {M[0, j], ..., M[t-1, j]}) or (M[t-1, j], {M[d-j-1, j], M[0, j], ..., M[t-2, j]}).

An R-vine array is said to be in natural order when the anti-diagonal entries are \(1, \dots, d\) (from left to right). The exemplary arrray above is in natural order. Any R-vine array can be characterized by the diagonal entries (called order) and the entries below the diagonal of the corresponding R-vine array in natural order. Since most algorithms work with the structure in natural order, this is how RVineStructure stores the structure internally.

Attributes

dim	The dimension.
matrix	Gets the R-vine matrix representation.
order	The variable order.
trunc_lvl	The truncation level.

Methods

__init__	Default constructor for the RVineStructure class.
from_dimension	Instantiates as a D-vine for a given dimension.
from_file	Instantiates an RVineStructure from a JSON file.
from_json	Instantiates from a JSON-like str object.
from_matrix	Instantiates an RVineStructure object from a matrix representing an R-vine array.
from_order	Instantiates as a D-vine with a given ordering of the variables.
min_array	Access elements of the minimum array.
needed_hfunc1	Access elements of the needed_hfunc1 array.
needed_hfunc2	Access elements of the needed_hfunc2 array.
simulate	Randomly sample a regular vine structure.
struct_array	Accesses elements of the structure array.
to_file	Write the structure into a JSON file.
to_json	Converts the structure into a JSON-like str object.
truncate	Truncates the R-vine structure.