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

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,

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

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

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:

It only contains numbers between 1 and d.

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

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

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

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: Returns ——- int the dimension of the vine (number of variables).
matrix: Gets the R-vine matrix representation.
order: Returns ——- list of int the natural ordering of variables in the first tree.
trunc_lvl: Returns ——- int the truncation level (the number of trees, at most dim - 1).

Methods

`from_dimension`([d, trunc_lvl])	Instantiates as a D-vine for a given dimension.
`from_file`(filename[, check])	Instantiates an RVineStructure from a JSON or CBOR file.
`from_json`(json[, check])	Instantiates from a JSON-like str object.
`from_matrix`(mat[, check])	Instantiates an RVineStructure object from a matrix representing an R-vine array.
`from_order`(order[, trunc_lvl, check])	Instantiates as a D-vine with a given ordering of the variables.
`from_struct_array`(order, struct_array[, ...])	Instantiates from the variable order (diagonal elements of the R-vine array) and a triangular structure array (elements above the diagonal).
`from_trees`(d, trees)	Assemble an `RVineStructure` from a list-of-trees decomposition.
`get_struct_array`(self[, natural_order])	Extract structure array (all elements above the diagonal in the R-vine array).
`min_array`(self, tree, edge)	Access elements of the minimum array.
`needed_hfunc1`(self, tree, edge)	Access elements of the needed_hfunc1 array.
`needed_hfunc2`(self, tree, edge)	Access elements of the needed_hfunc2 array.
`simulate`(d[, natural_order, seeds])	Randomly sample a regular vine structure.
`struct_array`(self, tree, edge[, natural_order])	Accesses elements of the structure array.
`to_file`(self, filename)	Writes the structure into a JSON or CBOR file.
`to_json`(self)	Converts the structure into a JSON-like str object.
`truncate`(self, trunc_lvl)	Truncates the R-vine structure.

Attributes

`dim`	Returns:
`matrix`	Gets the R-vine matrix representation.
`order`	Returns:
`trunc_lvl`	Returns:

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 or CBOR 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.
`from_struct_array`	Instantiates from the variable order (diagonal elements of the R-vine array) and a triangular structure array (elements above the diagonal).
`from_trees`	Assemble an `RVineStructure` from a list-of-trees decomposition.
`get_struct_array`	Extract structure array (all elements above the diagonal in the R-vine array).
`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`	Writes the structure into a JSON or CBOR file.
`to_json`	Converts the structure into a JSON-like str object.
`truncate`	Truncates the R-vine structure.