HAC (version 0.1-1)

hac: Construction of hac objects

Description

The function hac provides one way to construct objects of the class hac. Such objects are required as input argument for several functions, e.g. plot.hac and rHAC. The function hac.full returns also objects of the class hac. Its advantage compared to hac is its simple tractibility. The drawback is, that the function cannot be used for building partial nested Archimedean copulae. The supplementary function colums.hac returns the maximal number of columns, which should be contained in the matrix X. The function check.var tests, whether each path of the model ends with a variable or a vector of variables. The function check.par tests, whether the dependency parameter of an initial node has a lower value than the dependency parameters of successive nodes. The last two functions are called, when hac or hac.full are used and they do not return a value, if the input argument (a hac object) is correctly specified.

Usage

hac(type = HAC_GUMBEL, X, dim = NULL)
hac.full(type = HAC_GUMBEL, y, theta)
columns.hac(n)
check.var(x)
check.par(x)
## S3 method for class 'hac':
print(x, digits = 2, \dots)

Arguments

n

denotes the amount of rows of the matrix X, which has to contain at least two rows, i.e. $n \geq 2$. This implies, that a HAC (generated by this matrix) contains nodes on exact $(n - 1)$ nesting levels (hierachies).

theta

a vector containing the dependency parameters of a HAC. The parameters should be ordered from top to down. The length of theta must be equal to length(y) - 1.

y

a vector, which contains the variables. They are denoted by a formula, e.g. ~X1. If a specific node should host a group of variables one can extend the formula by adding variables

dim

a positive integer specifying the dimension of Archimedean copulae. It is not called, when a HAC is constructed.

type

defines the model. It can be chosen between HAC_CLAYTON, HAC_GUMBEL, HAC_ROTATED_GUMBEL, AC_GUMBEL and AC_CLAYTON.

x

an object of the class hac.

X

a matrix, which should follow a certain structure. It is useful to imagine a binary tree, which ``lies'' on the matrix and has its starting point at the first element of the first row. The first two paths go to the first and the second element of the seco

digits

specifying the digits, (see tree2str).

...

arguments to be passed to methods, (see print).

Value

• An object of the class hac is returned.
• type
  the specified copula type, e.g. HAC_GUMBEL.
• model
  contains the binary tree.

Details

The following matrix demonstrates ``theoretically'' how the structure of the matrix should look. The elements of the matrix refer to the element, on which they depend. So the elements in the second row depend on the 1. Node (or element [1, 1]). The further elements in the second row need to be $0$. cccccccccccc{ $i$-th column [ , 1] [ , 2] [ , 3] [ , 4] [ , 5] [ , 6] [ , 7] [ , 8] $\cdots$ [1, ] 1. Node 0 0 0 0 0 0 0 $\cdots$ $j$-th row [2, ] [1, 1] [1, 1] 0 0 0 0 0 0 $\cdots$ [3, ] [2, 1] [2, 1] [2, 2] [2, 2] 0 0 0 0 $\cdots$ [4, ] [3, 1] [3, 1] [3, 2] [3, 2] [3, 3] [3, 3] [3, 4] [3, 4] $\cdots$ $\vdots$ $\vdots$ $\vdots$ $\vdots$ $\vdots$ $\vdots$ $\vdots$ $\vdots$ $\vdots$ $\ddots$ } However, one should think about the order of the elements, since there are sometimes more than one representation, which result into the same or in a mirrored hac object (see example 2).

Examples

# maybe it is helpful to use the function plot.hac to verify the
# results (see example 2)

# Example 1: 4-dim AC
Matrix = 2.5
Object = hac(AC_CLAYTON, X = Matrix, dim = 4)
# class(Object) # [1] "hac"
tree2str(Object) # [1] "(V1.V2.V3.V4)_2.5"
plot(Object, , ylim = c(-0.4, 1.25), l = 1, h = 0.35)


# Example 2: 4-dim HAC
Matrix1 = matrix(c(2, 0, 4, ~X1 + X4, ~X2, ~X3), nrow = 3, byrow = TRUE)
y = c(~X1 + X4, ~X3, ~X2)
theta = c(2, 4)
Matrix3 = matrix(c(2, 0, 0, 0, ~X1 + X4, 4, 0, 0, 0, 0, ~X2, ~X3),
nrow = 3, byrow = TRUE)
# Matrix2
#      [,1]       [,2] [,3]       [,4]      
# [1,] 2          0    0          0         
# [2,] Expression 4    0          0         
# [3,] 0          0    Expression Expression

Object1 = hac(HAC_CLAYTON, Matrix1)
Object2 = hac.full(HAC_CLAYTON, y, theta)
tree2str(Object1) == tree2str(Object2) # [1] TRUE
tree2str(Object1) # [1] "((X2.X3)_{4}.X1.X4)_{2}"
# Object1 and Object 2 contain identical information

Object3 = hac(HAC_CLAYTON, Matrix3)
# the plots show, that the Objects are mirrored
plot.hac(Object1)
plot.hac(Object3)


# Example 3: 6-dim HAC
Matrix = matrix(c(2, 0, 0, 0, 3, 4, 0, 0, ~X1 + X6, ~X2, ~X3, ~X4 + X5),
nrow = 3, byrow = TRUE)
# Matrix
#      [,1]       [,2]       [,3]       [,4]      
# [1,] 2          0          0          0         
# [2,] 3          4          0          0         
# [3,] Expression Expression Expression Expression

Object = hac(HAC_CLAYTON, Matrix)
Object
plot.hac(Object)


# Example 4: 5-dim HAC
Matrix1 = matrix(c(1, 0, 0, 0, 2, 3, 0, 0, ~X1, 
4, ~X4, ~X5, 0, 0, ~X2, ~X3), nrow = 4, byrow = TRUE)
Matrix2 = matrix(c(1, 0, 0, 0, 0, 0, 0, 0, 2, 3, 0, 0, 0, 0, 0, 0, ~X1, 
4, ~X4, ~X5, 0, 0, 0, 0, 0, 0, ~X2, ~X3,  0, 0, 0, 0), nrow = 4,
byrow = TRUE)
# Matrix2
#      [,1]       [,2] [,3]       [,4]       [,5] [,6] [,7] [,8]
# [1,] 1          0    0          0          0    0    0    0   
# [2,] 2          3    0          0          0    0    0    0   
# [3,] Expression 4    Expression Expression 0    0    0    0   
# [4,] 0          0    Expression Expression 0    0    0    0   

Object1 = hac(HAC_CLAYTON, Matrix1)
Object2 = hac(HAC_CLAYTON, Matrix2)
tree2str(Object1) == tree2str(Object2) # [1] TRUE
Object1
plot(Object1)
# the previous result implies, that it is not necessary to include vectors 
# of 0 in the matrix