vglm.control {VGAM} | R Documentation

## Control function for vglm

### Description

Algorithmic constants and parameters for running `vglm` are set using this function.

### Usage

    vglm.control(checkwz=TRUE, criterion = names(.min.criterion.VGAM),
                 epsilon = 1e-07, half.stepsizing = TRUE,
                 maxit = 30, stepsize = 1, save.weight = FALSE,
                 trace = FALSE, wzepsilon = .Machine$double.eps^0.75,
                 xij = NULL, ...)

### Arguments

`checkwz` | logical indicating whether the diagonal elements of the working weight matrices should be checked whether they are sufficiently positive, i.e., greater than `wzepsilon`. If not, any values less than `wzepsilon` are replaced with this value.
`criterion` | character variable describing what criterion is to be used to test for convergence. The possibilities are listed in `.min.criterion.VGAM`, but most family functions only implement a few of these.
`epsilon` | positive convergence tolerance epsilon. Roughly speaking, the Newton-Raphson/Fisher-scoring iterations are assumed to have converged when two successive `criterion` values are within `epsilon` of each other.
`half.stepsizing` | logical indicating if half-stepsizing is allowed. For example, in maximizing a log-likelihood, if the next iteration has a log-likelihood that is less than the current value of the log-likelihood, then a half step will be taken. If the log-likelihood is still less than at the current position, a quarter-step will be taken etc. Eventually a step will be taken so that an improvement is made to the convergence criterion. `half.stepsizing` is ignored if `criterion=="coefficients"`.
`maxit` | maximum number of Newton-Raphson/Fisher-scoring iterations allowed.
`stepsize` | usual step size to be taken between each Newton-Raphson/Fisher-scoring iteration. It should be a value between 0 and 1, where a value of unity corresponds to an ordinary step. A value of 0.5 means half-steps are taken. Setting a value near zero will cause convergence to be generally slow but may help increase the chances of successful convergence for some family functions.
`save.weight` | logical indicating whether the `weights` slot of a `"vglm"` object will be saved on the object. If not, it will be reconstructed when needed, e.g., `summary`. Some family functions have `save.weight=TRUE` and others have `save.weight=FALSE` in their control functions.
`trace` | logical indicating if output should be produced for each iteration.
`wzepsilon` | small positive number used to test whether the diagonals of the working weight matrices are sufficiently positive.
`xij` | A formula or a list of formulas. Each formula has a RHS giving M terms making up a covariate-dependent term (whose name is the response). That is, it creates a variable that takes on different values for each linear/additive predictor, e.g., the ocular pressure of each eye. The M terms must be unique; use `fill1`, `fill2`, `fill3`, etc. if necessary. Each formula should have a response which is taken as the name of that variable, and the M terms are enumerated in sequential order. Each of the M terms multiply each successive row of the constraint matrix. When `xij` is used, the use of `form2` is also required to give every term used by the model.
`...` | other parameters that may be picked up from control functions that are specific to the VGAM family function.

### Details

Most of the control parameters are used within `vglm.fit` and you will have to look at that to understand the full details.

Setting `save.weight=FALSE` is useful for some models because the `weights` slot of the object is the largest and so less memory is used to store the object. However, for some VGAM family function, it is necessary to set `save.weight=TRUE` because the `weights` slot cannot be reconstructed later.

### Value

A list with components matching the input names. A little error checking is done, but not much. The list is assigned to the `control` slot of `vglm` objects.

### Note

In Example 2 below there are two covariates that have linear/additive predictor specific values. These are handled using the `xij` argument.

### Author(s)

Thomas W. Yee

### References

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

### See Also

`vglm`, `fill`. The author's homepage has further documentation about the `xij` argument.

### Examples

    # Example 1.
    pneumo = transform(pneumo, let=log(exposure.time))
    vglm(cbind(normal,mild,severe) ~ let, multinomial, data=pneumo,
         crit="coef", step=0.5, trace=TRUE, eps=1e-8, maxit=40)

    # Example 2. The use of the xij argument (simple case).
    ymat = rdiric(n <- 1000, shape=rep(exp(2), len=4))
    mydat = data.frame(x1=runif(n), x2=runif(n), x3=runif(n), x4=runif(n),
                       z1=runif(n), z2=runif(n), z3=runif(n), z4=runif(n))
    mydat = transform(mydat, X=x1, Z=z1)
    mydat = round(mydat, dig=2)
    fit2 = vglm(ymat ~ X + Z,
                dirichlet(parallel=TRUE), data=mydat, trace=TRUE,
                xij = list(Z ~ z1 + z2 + z3 + z4,
                           X ~ x1 + x2 + x3 + x4),
                form2 = ~  Z + z1 + z2 + z3 + z4 +
                           X + x1 + x2 + x3 + x4)
    head(model.matrix(fit2, type="lm"))   # LM model matrix
    head(model.matrix(fit2, type="vlm"))  # Big VLM model matrix
    coef(fit2)
    coef(fit2, matrix=TRUE)
    max(abs(predict(fit2)-predict(fit2, new=mydat))) # Predicts correctly
    summary(fit2)
    ## Not run:
    # plotvgam(fit2, se=TRUE, xlab="x1", which.term=1) # Bug!
    # plotvgam(fit2, se=TRUE, xlab="z1", which.term=2) # Bug!
    plotvgam(fit2, xlab="x1") # Correct
    plotvgam(fit2, xlab="z1") # Correct
    ## End(Not run)

    # Example 3. The use of the xij argument (complex case).
    set.seed(123)
    coalminers = transform(coalminers,
                           Age = (age - 42) / 5,
                           dum1 = round(runif(nrow(coalminers)), dig=2),
                           dum2 = round(runif(nrow(coalminers)), dig=2),
                           dum3 = round(runif(nrow(coalminers)), dig=2),
                           dumm = round(runif(nrow(coalminers)), dig=2))
    BS = function(x, ..., df=3) bs(c(x,...), df=df)[1:length(x),,drop=FALSE]
    NS = function(x, ..., df=3) ns(c(x,...), df=df)[1:length(x),,drop=FALSE]

    # Equivalently...
    BS = function(x, ..., df=3) head(bs(c(x,...), df=df), length(x), drop=FALSE)
    NS = function(x, ..., df=3) head(ns(c(x,...), df=df), length(x), drop=FALSE)

    fit3 = vglm(cbind(nBnW,nBW,BnW,BW) ~ Age + NS(dum1,dum2),
                fam = binom2.or(exchang=TRUE, zero=3),
                xij = list(NS(dum1,dum2) ~ NS(dum1,dum2) +
                                           NS(dum2,dum1) +
                                           fill(NS(dum1))),
                form2 = ~  NS(dum1,dum2) + NS(dum2,dum1) + fill(NS(dum1)) +
                           dum1 + dum2 + dum3 + Age + age + dumm,
                data = coalminers, trace=TRUE)
    head(model.matrix(fit3, type="lm"))   # LM model matrix
    head(model.matrix(fit3, type="vlm"))  # Big VLM model matrix
    coef(fit3)
    coef(fit3, matrix=TRUE)
    ## Not run:
    plotvgam(fit3, se=TRUE, lcol="red", scol="blue", xlab="dum1")
    ## End(Not run)

[Package VGAM version 0.7-9 Index]