# vglm.control

##### Control Function for vglm()

Algorithmic constants and parameters for running `vglm`

are set
using this function.

- Keywords
- models, regression

##### Usage

```
vglm.control(checkwz = TRUE, Check.rank = TRUE, Check.cm.rank = TRUE,
criterion = names(.min.criterion.VGAM),
epsilon = 1e-07, half.stepsizing = TRUE,
maxit = 30, noWarning = FALSE,
stepsize = 1, save.weights = 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.- Check.rank
logical indicating whether the rank of the VLM matrix should be checked. If this is not of full column rank then the results are not to be trusted. The default is to give an error message if the VLM matrix is not of full column rank.

- Check.cm.rank
logical indicating whether the rank of each constraint matrix should be checked. If this is not of full column rank then an error will occur. Under no circumstances should any constraint matrix have a rank less than the number of columns.

- 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 (usually Fisher-scoring) iterations allowed. Sometimes Newton-Raphson is used.

- noWarning
logical indicating whether to suppress a warning if convergence is not obtained within

`maxit`

iterations. This is ignored if`maxit = 1`

is set.- 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.weights
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.weights = TRUE`

and others have`save.weights = FALSE`

in their control functions.- trace
logical indicating if output should be produced for each iteration. Setting

`trace = TRUE`

is recommended in general because VGAM fits a very broad variety of models and distributions, and for some of them, convergence is intrinsically more difficult. Monitoring convergence can help check that the solution is reasonable or that a problem has occurred. It may suggest better initial values are needed, the making of invalid assumptions, or that the model is inappropriate for the data, etc.- 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.The function

`Select`

can be used to select variables beginning with the same character string.- …
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.weights = 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.weights = 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

Reiterating from above,
setting `trace = TRUE`

is recommended in general.

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

argument.

##### Warning

For some applications the default convergence criterion should
be tightened.
Setting something like `criterion = "coef", epsilon = 1e-09`

is one way to achieve this, and also add
`trace = TRUE`

to monitor the convergence.
Setting `maxit`

to some higher number is usually not
needed, and needing to do so suggests something is wrong, e.g.,
an ill-conditioned model, over-fitting or under-fitting.

##### References

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

##### See Also

`vglm`

,
`fill1`

.
The author's homepage has further documentation about
the `xij`

argument;
see also `Select`

.

##### Examples

```
# NOT RUN {
# 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, epsil = 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, digits = 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
# }
# 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)), digits = 2),
dum2 = round(runif(nrow(coalminers)), digits = 2),
dum3 = round(runif(nrow(coalminers)), digits = 2),
dumm = round(runif(nrow(coalminers)), digits = 2))
BS <- function(x, ..., df = 3)
sm.bs(c(x,...), df = df)[1:length(x),,drop = FALSE]
NS <- function(x, ..., df = 3)
sm.ns(c(x,...), df = df)[1:length(x),,drop = FALSE]
# Equivalently...
BS <- function(x, ..., df = 3)
head(sm.bs(c(x,...), df = df), length(x), drop = FALSE)
NS <- function(x, ..., df = 3)
head(sm.ns(c(x,...), df = df), length(x), drop = FALSE)
fit3 <- vglm(cbind(nBnW,nBW,BnW,BW) ~ Age + NS(dum1, dum2),
fam = binom2.or(exchangeable = 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")
# }
```

*Documentation reproduced from package VGAM, version 1.0-4, License: GPL-3*