vinecopulib::RVineTrees class
#include <vinecopulib/include/vinecopulib/vinecop/rvine_trees.hpp>

A list-of-trees decomposition of an R-vine structure.

The vine is stored as one edge list per tree. Each edge holds its conditioned pair (a, b), its conditioning set C, and (optionally) the fitted pair-copula. The class converts to and from the (order, struct_array) representation used by RVineStructure, validating the proximity condition on the way back. It is the shared primitive behind Vinecop::reorient() and the structure finalization during selection.

The orientation convention is that an edge's pair-copula has its first argument aligned with the conditioned variable a; a copula is therefore flipped iff the variable placed on the matrix diagonal differs from a.

Public types

struct AugmentedEdge: One edge of the augmented (line-graph) view: its two incident node ids plus a non-owning pointer to the underlying Edge (in trees_).
struct AugmentedTree: The augmented (line-graph) view of a tree used during conversion. degrees is indexed by node id (contiguous), avoiding a std::map.
struct Decomposition: The result of to_struct_array().
struct Edge: A single edge: conditioned pair (a, b), conditioning set C, and the associated pair-copula (independence by default).
struct PairCopulaLocation: The source of a pair copula in a matrix representation.
using Tree = std::vector<Edge>
using DiagonalPolicy = std::function<size_t(size_t col, const std::vector<std::vector<size_t>>&leaf_edges)>: Chooses which variable sits on the diagonal of a given column.

Public static functions

static auto default_diagonal_policy() -> DiagonalPolicy: The default diagonal policy: the conditioned[0] (first) leaf endpoint of the first leaf edge. It is flip-free — each edge stores its pair copula aligned to conditioned[0], so placing that endpoint on the diagonal needs no flip — and it is the convention shared by select() finalization and the RVineStructure round-trip.

Constructors, destructors, conversion operators

RVineTrees()
RVineTrees(const std::vector<size_t>& order, const TriangularArray<size_t>& struct_array) explicit: Builds the tree list from an (order, struct_array) representation.
RVineTrees(const std::vector<size_t>& order, const TriangularArray<size_t>& struct_array, const std::vector<std::vector<Bicop>>& pair_copulas): Builds the tree list, attaching pair-copulas to each edge.
RVineTrees(size_t d, std::vector<Tree> trees): Builds directly from a list of trees (edges carry their pair-copula).

Public functions

auto get_trees() const -> const std::vector<Tree>&
auto to_struct_array(const DiagonalPolicy& diagonal_policy = default_diagonal_policy()) const -> Decomposition: Converts back to matrix form, choosing diagonals with diagonal_policy (default: default_diagonal_policy()) and carrying/flipping the pair-copulas.
auto to_struct_array_map(const DiagonalPolicy& diagonal_policy = default_diagonal_policy()) const -> Decomposition: Converts back to matrix form without copying pair copulas.
auto get_dim() const -> size_t
auto get_trunc_lvl() const -> size_t

Typedef documentation

using vinecopulib::RVineTrees::DiagonalPolicy = std::function<size_t(size_t col, const std::vector<std::vector<size_t>>&leaf_edges)>

Chooses which variable sits on the diagonal of a given column.

Called with the column index and, for each leaf edge of the current top tree (in iteration order), the variables that may go on the diagonal (its leaf endpoints, 1 or 2 of them). Must return one of them.

Function documentation

static DiagonalPolicy vinecopulib::RVineTrees::default_diagonal_policy()

The default diagonal policy: the conditioned[0] (first) leaf endpoint of the first leaf edge. It is flip-free — each edge stores its pair copula aligned to conditioned[0], so placing that endpoint on the diagonal needs no flip — and it is the convention shared by select() finalization and the RVineStructure round-trip.

The default diagonal policy: the conditioned[0] (first) leaf endpoint of the first leaf edge — flip-free, and shared by select() finalization and the RVineStructure round-trip.

vinecopulib::RVineTrees::RVineTrees(const std::vector<size_t>& order, const TriangularArray<size_t>& struct_array) explicit

Builds the tree list from an (order, struct_array) representation.

Parameters
order	The variable order (diagonal of the R-vine matrix).
struct_array	The structure array, labeled consistently with `order`.

vinecopulib::RVineTrees::RVineTrees(const std::vector<size_t>& order, const TriangularArray<size_t>& struct_array, const std::vector<std::vector<Bicop>>& pair_copulas)

Builds the tree list, attaching pair-copulas to each edge.

Parameters
order	The variable order (diagonal of the R-vine matrix).
struct_array	The structure array, labeled consistently with `order`.
pair_copulas	The pair-copulas, indexed `[tree][edge]`; each is stored with its first argument aligned to the diagonal variable `order[edge]`. If empty, every edge is independence; otherwise it must cover every tree of `struct_array`.

vinecopulib::RVineTrees::RVineTrees(size_t d, std::vector<Tree> trees)

Builds directly from a list of trees (edges carry their pair-copula).

Parameters
d	The dimension of the vine.
trees	One edge list per tree; `trees[t]` must have `d - 1 - t` edges for a valid vine (validated on conversion, not here).

Decomposition vinecopulib::RVineTrees::to_struct_array(const DiagonalPolicy& diagonal_policy = default_diagonal_policy()) const

Converts back to matrix form, choosing diagonals with diagonal_policy (default: default_diagonal_policy()) and carrying/flipping the pair-copulas.

Parameters
diagonal_policy	Chooses which leaf variable sits on each column's diagonal (see `DiagonalPolicy`).

Converts back to matrix form, choosing diagonals with a policy and carrying (flipping) the pair-copulas.

vinecopulib::RVineTrees class #include <vinecopulib/include/vinecopulib/vinecop/rvine_trees.hpp>