constraints: Constraint Matrices

Description Usage Arguments Details Value Note Author(s) References See Also Examples

Description

Extractor function for the constraint matrices of objects in the VGAM package.

Usage

1
2
3
4
constraints(object, ...)
constraints.vlm(object, type = c("lm", "term"), all = TRUE, which,
                matrix.out = FALSE, colnames.arg = TRUE,
                rownames.arg = TRUE, ...)

Arguments

object

Some VGAM object, for example, having class vglmff-class.

type

Character. Whether LM- or term-type constraints are to be returned. The number of such matrices returned is equal to nvar(object, type = "lm") and the number of terms, respectively.

all, which

If all = FALSE then which gives the integer index or a vector of logicals specifying the selection.

matrix.out

Logical. If TRUE then the constraint matrices are cbind()ed together. The result is usually more compact because the default is a list of constraint matrices.

colnames.arg, rownames.arg

Logical. If TRUE then column and row names are assigned corresponding to the variables.

...

Other possible arguments such as type.

Details

Constraint matrices describe the relationship of coefficients/component functions of a particular explanatory variable between the linear/additive predictors in VGLM/VGAM models. For example, they may be all different (constraint matrix is the identity matrix) or all the same (constraint matrix has one column and has unit values).

VGLMs and VGAMs have constraint matrices which are known. The class of RR-VGLMs have constraint matrices which are unknown and are to be estimated.

Value

The extractor function constraints() returns a list comprising of constraint matrices—usually one for each column of the VLM model matrix, and in that order. The list is labelled with the variable names. Each constraint matrix has M rows, where M is the number of linear/additive predictors, and whose rank is equal to the number of columns. A model with no constraints at all has an order M identity matrix as each variable's constraint matrix.

For vglm and vgam objects, feeding in type = "term" constraint matrices back into the same model should work and give an identical model. The default are the "lm"-type constraint matrices; this is a list with one constraint matrix per column of the LM matrix. See the constraints argument of vglm, and the example below.

Note

In all VGAM family functions zero = NULL means none of the linear/additive predictors are modelled as intercepts-only. Other arguments found in certain VGAM family functions which affect constraint matrices include parallel and exchangeable.

The constraints argument in vglm and vgam allows constraint matrices to be inputted. If so, then constraints(fit, type = "lm") can be fed into the constraints argument of the same object to get the same model.

The xij argument does not affect constraint matrices; rather, it allows each row of the constraint matrix to be multiplied by a specified vector.

Author(s)

T. W. Yee

References

Yee, T. W. and Wild, C. J. (1996). Vector generalized additive models. Journal of the Royal Statistical Society, Series B, Methodological, 58, 481–493.

Yee, T. W. and Hastie, T. J. (2003). Reduced-rank vector generalized linear models. Statistical Modelling, 3, 15–41.

See Also

is.parallel, is.zero, trim.constraints. VGLMs are described in vglm-class; RR-VGLMs are described in rrvglm-class.

Arguments such as zero and parallel found in many VGAM family functions are a way of creating/modifying constraint matrices conveniently, e.g., see zero. See CommonVGAMffArguments for more information.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
# Fit the proportional odds model:
pneumo <- transform(pneumo, let = log(exposure.time))
(fit1 <- vglm(cbind(normal, mild, severe) ~ sm.bs(let, 3),
              cumulative(parallel = TRUE, reverse = TRUE), data = pneumo))
coef(fit1, matrix = TRUE)
constraints(fit1)  # Parallel assumption results in this
constraints(fit1, type = "term")  # Same as the default ("vlm"-type)
is.parallel(fit1)

# An equivalent model to fit1 (needs the type "term" constraints):
clist.term <- constraints(fit1, type = "term")  # "term"-type constraints
# cumulative() has no 'zero' argument to set to NULL (a good idea
# when using the 'constraints' argument):
(fit2 <- vglm(cbind(normal, mild, severe) ~ sm.bs(let, 3), data = pneumo,
              cumulative(reverse = TRUE), constraints = clist.term))
abs(max(coef(fit1, matrix = TRUE) -
        coef(fit2, matrix = TRUE)))  # Should be zero

# Fit a rank-1 stereotype (RR-multinomial logit) model:
fit <- rrvglm(Country ~ Width + Height + HP, multinomial, data = car.all)
constraints(fit)  # All except the first are the estimated A matrix

Example output

Loading required package: stats4
Loading required package: splines

Call:
vglm(formula = cbind(normal, mild, severe) ~ sm.bs(let, 3), family = cumulative(parallel = TRUE, 
    reverse = TRUE), data = pneumo)


Coefficients:
 (Intercept):1  (Intercept):2 sm.bs(let, 3)1 sm.bs(let, 3)2 sm.bs(let, 3)3 
     -19.10457      -20.00722       22.83129       15.95020       19.82301 

Degrees of Freedom: 16 Total; 11 Residual
Residual deviance: 2.231924 
Log-likelihood: -23.69281 
               logitlink(P[Y>=2]) logitlink(P[Y>=3])
(Intercept)             -19.10457          -20.00722
sm.bs(let, 3)1           22.83129           22.83129
sm.bs(let, 3)2           15.95020           15.95020
sm.bs(let, 3)3           19.82301           19.82301
$`(Intercept)`
     [,1] [,2]
[1,]    1    0
[2,]    0    1

$`sm.bs(let, 3)1`
     [,1]
[1,]    1
[2,]    1

$`sm.bs(let, 3)2`
     [,1]
[1,]    1
[2,]    1

$`sm.bs(let, 3)3`
     [,1]
[1,]    1
[2,]    1

$`(Intercept)`
     [,1] [,2]
[1,]    1    0
[2,]    0    1

$`sm.bs(let, 3)`
     [,1]
[1,]    1
[2,]    1

  (Intercept) sm.bs(let, 3) 
        FALSE          TRUE 

Call:
vglm(formula = cbind(normal, mild, severe) ~ sm.bs(let, 3), family = cumulative(reverse = TRUE), 
    data = pneumo, constraints = clist.term)


Coefficients:
 (Intercept):1  (Intercept):2 sm.bs(let, 3)1 sm.bs(let, 3)2 sm.bs(let, 3)3 
     -19.10457      -20.00722       22.83129       15.95020       19.82301 

Degrees of Freedom: 16 Total; 11 Residual
Residual deviance: 2.231924 
Log-likelihood: -23.69281 
[1] 0
$`(Intercept)`
      [,1] [,2] [,3] [,4] [,5] [,6] [,7] [,8] [,9]
 [1,]    1    0    0    0    0    0    0    0    0
 [2,]    0    1    0    0    0    0    0    0    0
 [3,]    0    0    1    0    0    0    0    0    0
 [4,]    0    0    0    1    0    0    0    0    0
 [5,]    0    0    0    0    1    0    0    0    0
 [6,]    0    0    0    0    0    1    0    0    0
 [7,]    0    0    0    0    0    0    1    0    0
 [8,]    0    0    0    0    0    0    0    1    0
 [9,]    0    0    0    0    0    0    0    0    1

$Width
           [,1]
 [1,] 1.0000000
 [2,] 0.3941182
 [3,] 0.2926068
 [4,] 0.3737394
 [5,] 0.4649922
 [6,] 0.5202984
 [7,] 0.7834323
 [8,] 0.6651169
 [9,] 0.2945245

$Height
           [,1]
 [1,] 1.0000000
 [2,] 0.3941182
 [3,] 0.2926068
 [4,] 0.3737394
 [5,] 0.4649922
 [6,] 0.5202984
 [7,] 0.7834323
 [8,] 0.6651169
 [9,] 0.2945245

$HP
           [,1]
 [1,] 1.0000000
 [2,] 0.3941182
 [3,] 0.2926068
 [4,] 0.3737394
 [5,] 0.4649922
 [6,] 0.5202984
 [7,] 0.7834323
 [8,] 0.6651169
 [9,] 0.2945245

VGAM documentation built on Jan. 16, 2021, 5:21 p.m.