covOrd: Warping-Based Covariance for an Ordinal Input

Description

Creator function for the class covOrd-class

Usage

covOrd(ordered, 
       k1Fun1 = k1Fun1Matern5_2, 
       warpFun = c("norm", "unorm", "power", "spline1", "spline2"), 
       cov = c("corr", "homo"), 
       hasGrad = TRUE, inputs = "u", 
       par = NULL, parLower = NULL, parUpper = NULL, 
       warpKnots = NULL, nWarpKnots = NULL,
       label = "Ordinal kernel", 
       intAsChar = TRUE, 
       ...)

Value

An object of class covOrd-class, inheriting from covQual-class.

Arguments

ordered: An object coerced to ordered representing an ordinal input. Only the levels and their order will be used.
k1Fun1: A function representing a 1-dimensional stationary kernel function, with no or fixed parameters.
warpFun: Character corresponding to an increasing warping function. See warpFun.
cov: Character indicating whether a correlation or homoscedastic kernel is used.
hasGrad: Object of class "logical". If TRUE, both k1Fun1 and warpFun must return the gradient as an attribute of the result.
inputs: Character: name of the ordinal input.
par, parLower, parUpper: Numeric vectors containing covariance parameter values/bounds in the following order: warping, range and variance if required (cov == "homo").
warpKnots: Numeric vector containing the knots used when a spline warping is chosen. The knots must be in [0, 1], and 0 and 1 are automatically added if not provided. The number of knots cannot be greater than the number of levels.
nWarpKnots: Number of knots when a spline warping is used. Ignored if warpKnots is given. nWarpKnots cannot be greater than the number of levels.
label: Character giving a brief description of the kernel.
intAsChar: Logical. If TRUE (default), an integer-valued input will be coerced into a character. Otherwise, it will be coerced into a factor.
...: Not used at this stage.

Details

Covariance kernel for qualitative ordered inputs obtained by warping.

Let $u$ be an ordered factor with levels $u_1, \dots, u_L$. Let $k_1$ be a 1-dimensional stationary kernel (with no or fixed parameters), $F$ a warping function i.e. an increasing function on the interval $[0,1]$ and $\theta$ a scale parameter. Then $k$ is defined by: $$k(u_i, u_j) = k_1([F(z_i) - F(z_{j})]/\theta)$$ where $z_1, \dots, z_L$ form a regular sequence from $0$ to $1$ (included). At this stage, the possible choices are:

A distribution function (cdf) truncated to $[0,1]$, among the Power and Normal cdfs.
For the Normal distribution, an unnormalized version, corresponding to the restriction of the cdf on $[0,1]$, is also implemented (warp = "unorm").
An increasing spline of degree 1 (piecewise linear function) or 2. In this case, $F$ is unnormalized. For degree 2, the implementation depends on scaling functions from DiceKriging package, which must be loaded here.

Notice that for unnormalized F, we set $\theta$ to 1, in order to avoid overparameterization.

Examples

Run this code

u <- ordered(1:6, labels = letters[1:6])

myCov <- covOrd(ordered = u, cov = "homo", intAsChar = FALSE)
myCov
coef(myCov) <- c(mean = 0.5, sd = 1, theta = 3, sigma2 = 2)
myCov

checkX(myCov, X = data.frame(u = c(1L, 3L)))
covMat(myCov, X = data.frame(u = c(1L, 3L)))

myCov2 <- covOrd(ordered = u, k1Fun1 = k1Fun1Cos, warpFun = "power")
coef(myCov2) <- c(pow = 1, theta = 1) 
myCov2

plot(myCov2, type = "cor", method = "ellipse")
plot(myCov2, type = "warp", col = "blue", lwd = 2)

myCov3 <- covOrd(ordered = u, k1Fun1 = k1Fun1Cos, warpFun = "spline1")
coef(myCov3) <- c(rep(0.5, 2), 2, rep(0.5, 2))
myCov3

plot(myCov3, type = "cor", method = "ellipse")
plot(myCov3, type = "warp", col = "blue", lwd = 2)


str(warpPower)  # details on the list describing the Power cdf
str(warpNorm)   # details on the list describing the Normal cdf