covQualNested {kergp}

Nested Qualitative Covariance

Description

Nested Qualitative Covariance

Usage

covQualNested(input = "x",
              groupList = NULL,
              group = NULL,
              nestedLevels = NULL,
              between = "Symm",
              within = "Diag",
              covBet = c("corr", "homo", "hete"), 
              covWith = c("corr", "homo", "hete"),
              compGrad = TRUE,
              contrasts = contr.helmod,
              intAsChar = TRUE)

Arguments

input

Name of the input, i.e. name of the column in the data frame when the covariance kernel is evaluated with the covMat,covQual-method method.

groupList

A list giving the groups, see Examples. Groups of size 1 are accepted. Note that the group values should be given in some order, with no gap between repeated values, see Examples.

group

Inactive if groupList is used. A factor or vector giving the groups, see Examples. Groups of size 1 are accepted. Note that the group values should be given in some order, with no gap between repeated values, see Examples.

nestedLevels

Inactive if groupList is used. A factor or a vector giving the (nested) levels within the group for each level of group. If this is missing, each element of group is assumed to correspond to one nested level within the group and the levels within the group are taken as integers in the order of group elements.

between

Character giving the type of structure to use for the between part. For now this can be one of the three choices "Diag", the diagonal structure of q1Diag, "Symm" for the general covariance of q1Symm, or "CompSymm" for the Compound Symmetry covariance of q1CompSymm. Default is Symm, corresponding to a specific correlation value for each pair of groups. On the other hand, Diag corresponds to a common correlation value for all pairs of groups.

within

Character vector giving the type of structure to use for the within part. The choices are the same as for between. The character vector is recycled to have length G so the within covariances can differ across groups. Default is "Diag", corresponding to a compound symmetry matrix.

covBet, covWith

Character vector indicating the type of covariance matrix to be used for the generator between- or within- matrices, as in q1Diag, q1Symm or q1CompSymm: correlation ("corr"), homoscedastic ("homo") or heteroscedastic ("hete"). Partial matching is allowed. This is different from the form of the resulting covariance matrix, see section Caution.

compGrad

Logical.

contrasts

Object of class "function". This function is similar to the contr.helmert or contr.treatment functions, but it must return an orthogonal matrix. For a given integer n, it returns a matrix with n rows and n - 1 columns forming a basis for the supplementary of a vector of ones in the n-dimensional Euclidean space. The contr.helmod can be used to obtain an orthogonal matrix hence defining an orthonormal basis.

intAsChar

Logical. If TRUE (default), an integer-valued input will be coerced into a character. Otherwise, it will be coerced into a factor.

Value

An object with class "covQualNested".

Caution

When covBet and covWith are zero, the resulting matrix is not a correlation matrix, due to the mode of construction. The "between" covariance matrix is a correlation but diagonal blocks are added to the extended matrix obtained by re-sizing the "between" covariance into a n \times n matrix.

Note

For now the replacement method such as 'coef<-' are inherited from the class covQuall. Consequently when these methods are used they do not update the covariance structure in the between slot nor those in the within (list) slot.

This covariance kernel involves two categorical (i.e. factor) inputs, but these are nested. It could be aliased in the future as q1Nested or q2Nested.

Examples

### Ex 1. See the vignette "groupKernel" for an example 
###       inspired from computer experiments.

### Ex 2. Below an example in data analysis.

country <- c("B", "B", "B", "F", "F" ,"F", "D", "D", "D")
cities <- c("AntWerp", "Ghent" , "Charleroi", "Paris", "Marseille",
            "Lyon", "Berlin", "Hamburg", "Munchen")
myGroupList <- list(B = cities[1:3],
                    F = cities[4:6],
                    D = cities[7:9])

## create a nested covariance. 
# first way, with argument 'groupList':

nest1 <- covQualNested(input = "ccities",
                       groupList = myGroupList,
                       between = "Symm", within = "Diag",
                       compGrad = TRUE,
                       covBet = "corr", covWith = "corr")

# second way, with arguments 'group' and 'nestedLevels'
nest2 <- covQualNested(input = "ccities",
                       group = country, nestedLevels = cities,
                       between = "Symm", within = "Diag",
                       compGrad = TRUE,
                       covBet = "corr", covWith = "corr")


## 'show' and 'plot' method as automatically invocated
nest2
plot(nest2, type = "cor")

## check that the covariance matrices match for nest1 and nest2
max(abs(covMat(nest1) - covMat(nest2)))


## When the groups are not given in order, an error occurs!

countryBad <- c("B", "B", "F", "F", "F", "D", "D", "D", "B")
cities <- c("AntWerp", "Ghent", "Paris", "Marseille", "Lyon",
            "Berlin", "Hamburg", "Munchen", "Charleroi")

nestBad <- try(covQualNested(input = "ccities",
                             group = countryBad, nestedLevels = cities,
                             between = "Symm", within = "Diag",
                             compGrad = TRUE,
                             covBet = "corr", covWith = "corr"))