RVineStructure

class RVineStructure

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__

Creates a new instance of the class.

simulate

Randomly sample a regular vine structure.

str

Converts the structure to a string representation (most useful for printing).

struct_array

Accesses elements of the structure array.

to_json

Write the structure into a JSON file.

truncate

Truncates the R-vine structure.