R-vine structure — rvine_structure • rvinecopulib
Description: R-vine structures are compressed representations encoding the tree structure of the vine, i.e. the conditioned/conditioning variables of each edge. The functions [cvine_structure()] or [dvine_structure()] give a simpler way to construct C-vines (every tree is a star) and D-vines (every tree is a path), respectively (see Examples).

# R-vine structure

Source: `R/rvine_structure.R`
`rvine_structure.Rd`

R-vine structures are compressed representations encoding the tree structure of the vine, i.e. the conditioned/conditioning variables of each edge. The functions `[cvine_structure()]` or `[dvine_structure()]` give a simpler way to construct C-vines (every tree is a star) and D-vines (every tree is a path), respectively (see Examples).

    rvine_structure(order, struct_array = list(), is_natural_order = FALSE)

    cvine_structure(order, trunc_lvl = Inf)

    dvine_structure(order, trunc_lvl = Inf)

    rvine_matrix(matrix)

## Arguments

order

  a vector of positive integers.

struct_array

  a list of vectors of positive integers. The vectors represent rows of the r-rvine structure and the number of elements have to be compatible with the `order` vector. If empty, the model is 0-truncated.

is_natural_order

  whether `struct_array` is assumed to be provided in natural order already (a structure is in natural order if the anti- diagonal is 1, .., d from bottom left to top right).

trunc_lvl

  the truncation level

matrix

  an R-vine matrix, see Details.

## Value

Either an `rvine_structure` or an `rvine_matrix`.

## Details

The R-vine structure is essentially a lower-triangular matrix/triangular array, with a notation that differs from the one in the VineCopula package. An example 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)`

An R-vine structure can be converted to an R-vine matrix using `as_rvine_matrix()`, which encodes the same model with a square matrix filled with zeros. For instance, the matrix corresponding to the structure above is:

    4 4 4 4
    3 3 3 0
    2 2 0 0
    1 0 0 0

Similarly, an R-vine matrix can be converted to an R-vine structure using `as_rvine_structure()`.

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[1, 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 structure or matrix must satisfy several conditions which are checked when `rvine_structure()`, `rvine_matrix()`, or some coercion methods (see `as_rvine_structure()` and `as_rvine_matrix(`) are called:

1. It can only contain numbers between 1 and d (and additionally zeros for R-vine matrices).

2. The anti-diagonal must contain the numbers 1, ..., d.

3. The anti-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 = 1, ..., d - t there must exist an index j > d, such that `(M[t, e], {M[1, e], ..., M[t - 1, e]})` equals either `(M[d + 1 - j, j], {M[1, j], ..., M[t - 1, j]})` or `(M[t - 1, j], {M[d + 1 - j, j], M[1, j], ..., M[t - 2, j]})`.

Condition 5 already implies conditions 2-4, but is more difficult to check by hand.

## See also

`as_rvine_structure()`, `as_rvine_matrix()`, `plot.rvine_structure()`, `plot.rvine_matrix()`, `rvine_structure_sim()`, `rvine_matrix_sim()`

## Examples

    # R-vine structures can be constructed from the order vector and struct_array
    rvine_structure(order = 1:4, struct_array = list(
      c(4, 4, 4),
      c(3, 3),
      2
    ))
    #> 4-dimensional R-vine structure ('rvine_structure')
    #> 4 4 4 4
    #> 3 3 3
    #> 2 2
    #> 1

    # R-vine matrices can be constructed from standard matrices
    mat <- matrix(c(4, 3, 2, 1, 4, 3, 2, 0, 4, 3, 0, 0, 4, 0, 0, 0), 4, 4)
    rvine_matrix(mat)
    #> 4-dimensional R-vine matrix ('rvine_matrix')
    #> 4 4 4 4
    #> 3 3 3
    #> 2 2
    #> 1

    # coerce to R-vine structure
    str(as_rvine_structure(mat))
    #> List of 4
    #>  $ order       : num [1:4] 1 2 3 4
    #>  $ struct_array:List of 3
    #>   ..$ : int [1:3] 4 4 4
    #>   ..$ : int [1:2] 3 3
    #>   ..$ : int 2
    #>  $ d           : Named num 4
    #>   ..- attr(*, "names")= chr "dim"
    #>  $ trunc_lvl   : Named num 3
    #>   ..- attr(*, "names")= chr "trunc_lvl"
    #>  - attr(*, "class")= chr [1:2] "rvine_structure" "list"

    # truncate and construct the R-vine matrix
    mat[3, 1] <- 0
    rvine_matrix(mat)
    #> 4-dimensional R-vine matrix ('rvine_matrix'), 2-truncated
    #> 4 4 4 4
    #> 3 3 3
    #>   2
    #> 1

    # or use directly the R-vine structure constructor
    rvine_structure(order = 1:4, struct_array = list(
      c(4, 4, 4),
      c(3, 3)
    ))
    #> 4-dimensional R-vine structure ('rvine_structure'), 2-truncated
    #> 4 4 4 4
    #> 3 3 3
    #>   2
    #> 1

    # throws an error
    mat[3, 1] <- 5
    try(rvine_matrix(mat))
    #> Error in rvine_matrix_check_cpp(matrix) :
    #>   not a valid R-vine array: the upper left triangle can only contain numbers between 1 and d (number of variables).

    # C-vine structure
    cvine <- cvine_structure(1:5)
    cvine
    #> 5-dimensional R-vine structure ('rvine_structure')
    #> 5 5 5 5 5
    #> 4 4 4 4
    #> 3 3 3
    #> 2 2
    #> 1
    plot(cvine)

    # D-vine structure
    dvine <- dvine_structure(c(1, 4, 2, 3, 5))
    dvine
    #> 5-dimensional R-vine structure ('rvine_structure')
    #> 4 2 3 5 5
    #> 2 3 5 3
    #> 3 5 2
    #> 5 4
    #> 1
    plot(dvine)