R-Vine Copula Model in Matrix Notation

Source: R/RVineMatrix.R

This function creates an RVineMatrix() object which encodes an R-vine copula model. It contains the matrix identifying the R-vine tree structure, the matrix identifying the copula families utilized and two matrices for corresponding parameter values.

RVineMatrix(
  Matrix,
  family = array(0, dim = dim(Matrix)),
  par = array(NA, dim = dim(Matrix)),
  par2 = array(NA, dim = dim(Matrix)),
  names = NULL,
  check.pars = TRUE
)

Arguments

Matrix

Lower (or upper) triangular d x d matrix that defines the R-vine tree structure.

family

Lower (or upper) triangular d x d matrix with zero diagonal entries that assigns the pair-copula families to each (conditional) pair defined by Matrix (default: family = array(0,dim=dim(Matrix))). The bivariate copula families are defined as follows:
0 = independence copula
1 = Gaussian copula
2 = Student t copula (t-copula)
3 = Clayton copula
4 = Gumbel copula
5 = Frank copula
6 = Joe copula
7 = BB1 copula
8 = BB6 copula
9 = BB7 copula
10 = BB8 copula
13 = rotated Clayton copula (180 degrees; survival Clayton'') \cr `14` = rotated Gumbel copula (180 degrees; survival Gumbel'')
16 = rotated Joe copula (180 degrees; survival Joe'') \cr `17` = rotated BB1 copula (180 degrees; survival BB1'')
18 = rotated BB6 copula (180 degrees; survival BB6'')\cr `19` = rotated BB7 copula (180 degrees; survival BB7'')
20 = rotated BB8 copula (180 degrees; ``survival BB8'')
23 = rotated Clayton copula (90 degrees)
`24` = rotated Gumbel copula (90 degrees)
`26` = rotated Joe copula (90 degrees)
`27` = rotated BB1 copula (90 degrees)
`28` = rotated BB6 copula (90 degrees)
`29` = rotated BB7 copula (90 degrees)
`30` = rotated BB8 copula (90 degrees)
`33` = rotated Clayton copula (270 degrees)
`34` = rotated Gumbel copula (270 degrees)
`36` = rotated Joe copula (270 degrees)
`37` = rotated BB1 copula (270 degrees)
`38` = rotated BB6 copula (270 degrees)
`39` = rotated BB7 copula (270 degrees)
`40` = rotated BB8 copula (270 degrees)
`104` = Tawn type 1 copula
`114` = rotated Tawn type 1 copula (180 degrees)
`124` = rotated Tawn type 1 copula (90 degrees)
`134` = rotated Tawn type 1 copula (270 degrees)
`204` = Tawn type 2 copula
`214` = rotated Tawn type 2 copula (180 degrees)
`224` = rotated Tawn type 2 copula (90 degrees)
`234` = rotated Tawn type 2 copula (270 degrees)

par

Lower (or upper) triangular d x d matrix with zero diagonal entries that assigns the (first) pair-copula parameter to each (conditional) pair defined by Matrix
(default: par = array(NA, dim = dim(Matrix))).

par2

Lower (or upper) triangular d x d matrix with zero diagonal entries that assigns the second parameter for pair-copula families with two parameters to each (conditional) pair defined by Matrix (default: par2 = array(NA, dim = dim(Matrix))).

names

A vector of names for the d variables; default: names = NULL.

check.pars

logical; default is TRUE; if FALSE, checks for family/parameter-consistency are omitted (should only be used with care).

Value

An object of class RVineMatrix(), i.e., a list with the following components:

Matrix

R-vine tree structure matrix.

family

pair-copula family matrix with values as above.

par

pair-copula parameter matrix.

par2

second pair-copula parameter matrix with parameters necessary for pair-copula families with two parameters.

names

variable names (defaults to V1, V2, ...).

MaxMat, CondDistr

additional matrices required internally for evaluating the density etc.,

type

the type of the vine copula structure; possible types are: "C-vine": all trees consist of a star; "D-vine": all trees consist of a path; "R-vine": all structures that are neither a C- nor D-vine.

tau

Kendall's tau matrix,

taildep

matrices of lower and upper tail dependence coefficients,

beta

Blomqvist's beta matrix.

Objects of this class are also returned by the RVineSeqEst(), RVineCopSelect(), and RVineStructureSelect()

functions. In this case, further information about the fit is added.

Note

For a comprehensive summary of the vine copula model, use summary(object); to see all its contents, use str(object).
The RVineMatrix() function automatically checks if the given matrix is a valid R-vine matrix (see RVineMatrixCheck()).
Although the function allows upper triangular matrices as its input, it will always store them as lower triangular matrices.

References

Dissmann, J. F., E. C. Brechmann, C. Czado, and D. Kurowicka (2013). Selecting and estimating regular vine copulae and application to financial returns. Computational Statistics & Data Analysis, 59 (1), 52-69.

Author

Jeffrey Dissmann, Thomas Nagler

Examples


# define 5-dimensional R-vine tree structure matrix
Matrix <- c(5, 2, 3, 1, 4,
            0, 2, 3, 4, 1,
            0, 0, 3, 4, 1,
            0, 0, 0, 4, 1,
            0, 0, 0, 0, 1)
Matrix <- matrix(Matrix, 5, 5)
# define R-vine pair-copula family matrix
family <- c(0, 1, 3, 4, 4,
            0, 0, 3, 4, 1,
            0, 0, 0, 4, 1,
            0, 0, 0, 0, 3,
            0, 0, 0, 0, 0)
family <- matrix(family, 5, 5)
# define R-vine pair-copula parameter matrix
par <- c(0, 0.2, 0.9, 1.5, 3.9,
         0, 0, 1.1, 1.6, 0.9,
         0, 0, 0, 1.9, 0.5,
         0, 0, 0, 0, 4.8,
         0, 0, 0, 0, 0)
par <- matrix(par, 5, 5)
# define second R-vine pair-copula parameter matrix
par2 <- matrix(0, 5, 5)

## define RVineMatrix object
RVM <- RVineMatrix(Matrix = Matrix, family = family,
                   par = par, par2 = par2,
                   names = c("V1", "V2", "V3", "V4", "V5"))

## see the object's content or a summary
str(RVM)
#> List of 11
#>  $ Matrix   : num [1:5, 1:5] 5 2 3 1 4 0 2 3 4 1 ...
#>  $ family   : num [1:5, 1:5] 0 1 3 4 4 0 0 3 4 1 ...
#>  $ par      : num [1:5, 1:5] 0 0.2 0.9 1.5 3.9 0 0 1.1 1.6 0.9 ...
#>  $ par2     : num [1:5, 1:5] 0 0 0 0 0 0 0 0 0 0 ...
#>  $ names    : chr [1:5] "V1" "V2" "V3" "V4" ...
#>  $ MaxMat   : num [1:5, 1:5] 5 2 3 4 4 0 2 3 4 1 ...
#>  $ CondDistr:List of 2
#>   ..$ direct  : logi [1:5, 1:5] FALSE TRUE TRUE TRUE TRUE FALSE ...
#>   ..$ indirect: logi [1:5, 1:5] FALSE FALSE FALSE FALSE FALSE FALSE ...
#>  $ type     : chr "R-vine"
#>  $ tau      : num [1:5, 1:5] 0 0.128 0.31 0.333 0.744 ...
#>  $ taildep  :List of 2
#>   ..$ upper: num [1:5, 1:5] 0 0 0 0.413 0.805 ...
#>   ..$ lower: num [1:5, 1:5] 0 0 0.463 0 0 ...
#>  $ beta     : num [1:5, 1:5] 0 0.128 0.309 0.331 0.748 ...
#>  - attr(*, "class")= chr "RVineMatrix"
summary(RVM)
#> tree       edge | family  cop   par  par2 |  tau   utd   ltd 
#> ------------------------------------------------------------ 
#>    1        4,5 |      4    G  3.90  0.00 | 0.74  0.81     -
#>             1,2 |      1    N  0.90  0.00 | 0.71     -     -
#>             1,3 |      1    N  0.50  0.00 | 0.33     -     -
#>             1,4 |      3    C  4.80  0.00 | 0.71     -  0.87
#>    2      1,5;4 |      4    G  1.50  0.00 | 0.33  0.41     -
#>           4,2;1 |      4    G  1.60  0.00 | 0.38  0.46     -
#>           4,3;1 |      4    G  1.90  0.00 | 0.47  0.56     -
#>    3    3,5;1,4 |      3    C  0.90  0.00 | 0.31     -  0.46
#>         3,2;4,1 |      3    C  1.10  0.00 | 0.35     -  0.53
#>    4  2,5;3,1,4 |      1    N  0.20  0.00 | 0.13     -     -
#> ---
#> type: R-vine    
#> ---
#> 1 <-> V1,   2 <-> V2,   3 <-> V3,   4 <-> V4,   5 <-> V5

## inspect the model using plots
if (FALSE) plot(RVM)  # tree structure
contour(RVM)  # contour plots of all pair-copulas


## simulate from the vine copula model
plot(RVineSim(500, RVM))