HAC (version 0.1-7)

hac: Construction of hac objects

Description

hac, hac.full and as.hac provide ways to construct hac objects, which are required as input argument for several functions, e.g. plot.hac and rHAC. Due to the simple handling of hac.full, the function represents probably the most applied one, but it cannot be used for building partially nested Archimedean copulae. This gap might be closed by using hac or as.hac. Both provide identical functionality, while the former depend on a matrix and the latter on a list as major argument. The supplementary function columns.hac returns the maximal number of columns, which should be contained in the matrix X.

Usage

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

Arguments

y

a vector containing 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 with

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.

tree

a list object of the general structure list(V1,V2,theta). The argument theta, which has to be of the class numeric, represents the ini

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

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

a hac object.

X

a matrix, which should follow a certain structure. Consider a binary tree initialized at [1,1]. The first two branches go to the first and the second element of the second row. If the branches end at these points, an AC model would be returne

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

# it might be 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)
Matrix4 = matrix(c(2, 0, 0, 0, ~X1 + X4, 4, 0, 0, 0, 0, ~X2, ~X3),
nrow = 3, byrow = TRUE)
List = list(V1 = list(V1 = "X2", V2 = "X3", theta = 4), V2 = c("X1", "X4"), 
theta = 2)
# 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)
Object3 = as.hac(HAC_CLAYTON, List)
tree2str(Object1) == tree2str(Object2) # [1] TRUE
tree2str(Object3) == tree2str(Object1) # [1] TRUE
tree2str(Object1) # [1] "((X2.X3)_{4}.X1.X4)_{2}"
# Object1 and Object 2 contain identical information

Object4 = hac(HAC_CLAYTON, Matrix4)
# 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)
List = list(V1= list(V1 = c("X1", "X6"), V2 = "X2", theta = 3), V2 = list(
V1 = "X3", V2 = c("X4", "X5"), theta = 4), theta = 2)
# Matrix
#      [,1]       [,2]       [,3]       [,4]      
# [1,] 2          0          0          0         
# [2,] 3          4          0          0         
# [3,] Expression Expression Expression Expression

Object1 = hac(HAC_CLAYTON, Matrix)
Object2 = as.hac(HAC_CLAYTON, List)
tree2str(Object1) == tree2str(Object2) # [1] TRUE
plot.hac(Object1)


# 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)
List = list(V1= list(V1 = "X1", V2 = list(V1 = "X2", V2 = "X3", 
theta = 4), theta = 2), V2 = list(V1 = "X4", V2 = "X5", theta = 3), 
theta = 1)

# 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)
Object3 = as.hac(HAC_CLAYTON, List)
tree2str(Object1) == tree2str(Object2) # [1] TRUE
tree2str(Object1) == tree2str(Object3) # [1] TRUE
Object1
plot(Object1)
# the previous result implies, that it is not necessary to include vectors 
# of 0 in the matrix. Furthermore identical objects can be created by
# hac and as.hac.