vinecopulib::RVineStructure class

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

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

Derived classes

class CVineStructure: A class for C-vine structures.
class DVineStructure: A class for D-vine structures.

Public static functions

static auto simulate(size_t d, bool natural_order = false, std::vector<int> seeds = std::vector<int>()) -> RVineStructure: Randomly sample a regular vine structure.

Constructors, destructors, conversion operators

RVineStructure(const size_t& d = static_cast<size_t>(1), const size_t& trunc_lvl = std::numeric_limits<size_t>::max()) explicit: Instantiates an RVineStructure object to a D-vine for a given dimension.
RVineStructure(const Eigen::Matrix<size_t, Eigen::Dynamic, Eigen::Dynamic>& mat, bool check = true) explicit: Instantiates an RVineStructure object from a matrix representing an R-vine array.
RVineStructure(const std::vector<size_t>& order, const size_t& trunc_lvl = std::numeric_limits<size_t>::max(), bool check = true) explicit: Instantiates an RVineStructure object to a D-vine with a given ordering of the variables.
RVineStructure(const std::vector<size_t>& order, const TriangularArray<size_t>& struct_array, bool natural_order = false, bool check = true): Instantiates an RVineStructure object from the variable order (diagonal elements of the R-vine array) and a triangular structure array (all elements above the diagonal).
RVineStructure(const std::string& filename, const bool check = true) explicit: Instantiates an RVineStructure from a JSON file.
RVineStructure(const nlohmann::json& input, const bool check = true) explicit: Instantiates from a nlohmann::json object.

Public functions

auto to_json() const -> nlohmann::json: Converts the structure into a nlohmann::json object.
void to_file(const std::string& filename) const: Write the structure into a JSON file.
auto get_dim() const -> size_t: Gets the dimension of the vine.
auto get_trunc_lvl() const -> size_t: Gets the truncation level of the vine.
auto get_order() const -> std::vector<size_t>: Extract the order of variables in the vine (diagonal entries in the R-vine array).
auto get_struct_array(bool natural_order = false) const -> TriangularArray<size_t>: Extract structure array (all elements above the diagonal in the R-vine array).
auto get_min_array() const -> TriangularArray<size_t>: Gets the minimum array.
auto get_needed_hfunc1() const -> TriangularArray<short unsigned>: Gets an array indicating which of the first h-functions are needed.
auto get_needed_hfunc2() const -> TriangularArray<short unsigned>: Gets an array indicating which of the second h-functions are needed.
auto get_matrix() const -> Eigen::Matrix<size_t, Eigen::Dynamic, Eigen::Dynamic>: Gets the R-vine matrix representation.
auto struct_array(size_t tree, size_t edge, bool natural_order = false) const -> size_t: Accesses elements of the structure array.
auto min_array(size_t tree, size_t edge) const -> size_t: Access elements of the minimum array.
auto needed_hfunc1(size_t tree, size_t edge) const -> bool: Access elements of the needed_hfunc1 array.
auto needed_hfunc2(size_t tree, size_t edge) const -> bool: Access elements of the needed_hfunc2 array.
void truncate(size_t trunc_lvl): Truncates the R-vine structure.
auto str() const -> std::string: Converts the structure to a string representation (most useful for printing).

Function documentation

static RVineStructure vinecopulib::RVineStructure::simulate(size_t d, bool natural_order = false, std::vector<int> seeds = std::vector<int>())

Randomly sample a regular vine structure.

Parameters
d	The dimension.
natural_order	Should the sampled structure be in natural order?
seeds	Seeds of the random number generator; if empty (default), the random number generator is seeded randomly.

vinecopulib::RVineStructure::RVineStructure(const size_t& d = static_cast<size_t>(1), const size_t& trunc_lvl = std::numeric_limits<size_t>::max()) explicit

Instantiates an RVineStructure object to a D-vine for a given dimension.

Parameters
d	The dimension.
trunc_lvl	The truncation level. By default, it is dim - 1.

vinecopulib::RVineStructure::RVineStructure(const Eigen::Matrix<size_t, Eigen::Dynamic, Eigen::Dynamic>& mat, bool check = true) explicit

Instantiates an RVineStructure object from a matrix representing an R-vine array.

Parameters
mat	A matrix representing a valid R-vine array.
check	Whether `mat` shall be checked for validity.

The matrix must contain zeros in the lower right triangle and the upper left triangle must be a valid R-vine array. Truncated vines can be encoded by putting zeros above the digonal in all rows below the truncation level. Example of a 1-truncated matrix:

vinecopulib::RVineStructure::RVineStructure(const std::vector<size_t>& order, const size_t& trunc_lvl = std::numeric_limits<size_t>::max(), bool check = true) explicit

Instantiates an RVineStructure object to a D-vine with a given ordering of the variables.

Parameters
order	The order of variables in the D-vine (diagonal entries in the R-vine array); must be a permutation of 1, ..., d.
trunc_lvl	The truncation level. By default, it is d - 1.
check	Whether `order shall be checked for validity.

vinecopulib::RVineStructure::RVineStructure(const std::vector<size_t>& order, const TriangularArray<size_t>& struct_array, bool natural_order = false, bool check = true)

Instantiates an RVineStructure object from the variable order (diagonal elements of the R-vine array) and a triangular structure array (all elements above the diagonal).

Parameters
order	The order of variables (diagonal entries in the R-vine array); must be a permutation of 1, ..., d.
struct_array	The structure array (all elements above the diagonal in the R-vine array). For truncated vines, all rows below the truncation level are omitted.
natural_order	Whether `struct_array` is already in natural order.
check	Whether `order` and `struct_array` shall be checked for validity.

vinecopulib::RVineStructure::RVineStructure(const std::string& filename, const bool check = true) explicit

Instantiates an RVineStructure from a JSON file.

Parameters
filename	The name of the JSON file to read.
check	Whether to check if the input represents a valid R-vine matrix.

The file needs to contain two values: "array" for the structure triangular array and "order" for the order vector.

vinecopulib::RVineStructure::RVineStructure(const nlohmann::json& input, const bool check = true) explicit

Instantiates from a nlohmann::json object.

Parameters
input	The nlohmann::json object to convert from (see `to_json()` for the structure of the input).
check	Whether to check if the input represents a valid R-vine structure.

nlohmann::json vinecopulib::RVineStructure::to_json() const

Converts the structure into a nlohmann::json object.

Returns	the nlohmann::json object containing the structure.

The nlohmann::json object contains two nodes: "array" for the structure triangular array and "order" for the order vector.

void vinecopulib::RVineStructure::to_file(const std::string& filename) const

Write the structure into a JSON file.

Parameters
filename	The name of the file to write.

The written file contains two values: "array" for the structure triangular array and "order" for the order vector.

TriangularArray<size_t> vinecopulib::RVineStructure::get_struct_array(bool natural_order = false) const

Extract structure array (all elements above the diagonal in the R-vine array).

Parameters
natural_order	Whether indices correspond to natural order.

TriangularArray<size_t> vinecopulib::RVineStructure::get_min_array() const

Gets the minimum array.

The minimum array is derived from an R-vine array by iteratively computing the (elementwise) minimum of two subsequent rows (starting from the top). It is used in estimation and evaluation algorithms to find the two edges in the previous tree that are joined by the current edge.

TriangularArray<short unsigned> vinecopulib::RVineStructure::get_needed_hfunc1() const

Gets an array indicating which of the first h-functions are needed.

It is usually not necessary to compute both h-functions for each pair-copula.

TriangularArray<short unsigned> vinecopulib::RVineStructure::get_needed_hfunc2() const

Gets an array indicating which of the second h-functions are needed.

It is usually not necessary to compute both h-functions for each pair-copula.

size_t vinecopulib::RVineStructure::struct_array(size_t tree, size_t edge, bool natural_order = false) const

Accesses elements of the structure array.

Parameters
tree	Tree index.
edge	Edge index.
natural_order	Whether indices correspond to natural order.

size_t vinecopulib::RVineStructure::min_array(size_t tree, size_t edge) const

Access elements of the minimum array.

Parameters
tree	Tree index.
edge	Edge index.

bool vinecopulib::RVineStructure::needed_hfunc1(size_t tree, size_t edge) const

Access elements of the needed_hfunc1 array.

Parameters
tree	Tree index.
edge	Edge index.

void vinecopulib::RVineStructure::truncate(size_t trunc_lvl)

Truncates the R-vine structure.

Parameters
trunc_lvl	The truncation level.

If the structure is already truncated at a level less than trunc_lvl, the function does nothing.