vglm.control: Control Function for vglm()
In VGAM: Vector Generalized Linear and Additive Models
vglm.control R Documentation
Control Function for vglm()
Description
Algorithmic constants and parameters for
running vglm are set
using this function.
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 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.
A formula or a list of formulas.
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.
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.
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.
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,
TypicalVGAMfamilyFunction,
fill1.
The author's homepage has further documentation about
the xij argument;
see also Select.
Examples
# Example 1.
pneumo <- transform(pneumo, let = log(exposure.time))
vglm(cbind(normal, mild, severe) ~ let, multinomial, 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), 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 ok
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)), 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) +
fill1(NS( dum1))),
form2 = ~ NS(dum1, dum2) + NS(dum2, dum1) +
fill1(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 = 2, scol = 4, xlab = "dum1")
## End(Not run)
VGAM documentation built on Sept. 18, 2024, 9:09 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| vglm.control | R Documentation |
Control Function for vglm()
Description
Algorithmic constants and parameters for
running vglm are set
using this function.
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 |
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 |
epsilon |
positive convergence tolerance epsilon. Roughly speaking,
the Newton-Raphson/Fisher-scoring iterations are assumed
to have converged when two successive |
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. |
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 |
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 |
trace |
logical indicating if output should be produced for each
iteration. Setting |
wzepsilon |
small positive number used to test whether the diagonals of the working weight matrices are sufficiently positive. |
xij |
A list of formulas.
Each formula has a RHS giving A formula or a list of formulas. The function |
... |
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.
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.
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.
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,
TypicalVGAMfamilyFunction,
fill1.
The author's homepage has further documentation about
the xij argument;
see also Select.
Examples
# Example 1.
pneumo <- transform(pneumo, let = log(exposure.time))
vglm(cbind(normal, mild, severe) ~ let, multinomial, 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), 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 ok
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)), 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) +
fill1(NS( dum1))),
form2 = ~ NS(dum1, dum2) + NS(dum2, dum1) +
fill1(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 = 2, scol = 4, xlab = "dum1")
## End(Not run)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.