CommonVGAMffArguments {VGAM}R Documentation

Common VGAM family function Arguments

Description

Here is a description of some common and typical arguments found in VGAM family functions, e.g., lsigma, isigma, nsimEI, parallel and zero.

Usage

TypicalVGAMfamilyFunction(lsigma="loge", esigma=list(),
                          isigma=NULL, parallel = TRUE,
                          shrinkage.init = 0.95,
                          method.init=1, nsimEIM=100, zero=NULL)

Arguments

Almost every VGAM family function has an argument list similar to the one given above. Below, M is the number of linear/additive predictors.

lsigma Character. Link function applied to a parameter and not necessarily a mean. See Links for a selection of choices. If there is only one parameter then this argument is often called link.
esigma List. Extra argument allowing for additional information, specific to the link function. See Links for more information. If there is only one parameter then this argument is often called earg.
isigma Optional initial values can often be inputted using an argument beginning with "i". For example, "isigma" and "ilocation", or just "init" if there is one parameter. A value of NULL means a value is computed internally, i.e., a self-starting VGAM family function. If a failure to converge occurs make use of these types of arguments.
parallel A logical, or formula specifying which terms have equal/unequal coefficients. This argument is common in VGAM family functions for categorical responses, e.g., cumulative, acat, cratio, sratio. For the proportional odds model (cumulative) having parallel constraints applied to each explanatory variable (except for the intercepts) means the fitted probabilities do not become negative or greater than 1. However this parallelism or proportional-odds assumption ought to be checked.
nsimEIM Some VGAM family functions use simulation to obtain an approximate expected information matrix (EIM). For those that do, the nsimEIM argument specifies the number of random variates used per observation; the mean of nsimEIM random variates is taken. Thus nsimEIM controls the accuracy and a larger value may be necessary if the EIMs are not positive-definite. For intercept-only models (y ~ 1) the value of nsimEIM can be smaller (since the common value used is also then taken as the mean over the observations), especially if the number of observations is large.
Some VGAM family functions provide two algorithms for estimating the EIM. If applicable, set nsimEIM=NULL to choose the other algorithm.
method.init An integer with value 1 or 2 or 3 or ... which specifies the initialization method for some parameters or a specific parameter. If failure to converge occurs try the next higher value, and continue until success. For example, method.init=1 might be the method of moments, and method.init=2 might be another method. If no value of method.init works then it will be necessary to use arguments such as isigma. For many VGAM family functions it is advisable to try this argument with all possible values to safeguard against problems such as converging to a local solution. VGAM family functions with this argument usually correspond to a model or distribution that is relatively hard to fit successfully, therefore care is needed to ensure the global solution is obtained. So using all possible values that this argument supplies is a good idea.
zero An integer specifying which linear/additive predictor is modelled as intercepts-only. That is, the regression coefficients are set to zero for all covariates except for the intercept. If zero is specified then it is a vector with values from the set {1,2,...,M}. The value zero=NULL means model all linear/additive predictors as functions of the explanatory variables.
Some VGAM family functions allow the zero argument to accept negative values; if so then its absolute value is recycled over each response. For example, zero=-2 would mean, for each response, the second linear/additive predictor is modelled as intercepts-only. A specific example is the k parameter in negbinomial; this VGAM family function can handle a matrix of responses.
shrinkage.init Shrinkage factor s used for obtaining initial values. Numeric, between 0 and 1. In general, the formula used is something like s*mu + (1-s)*y where mu is a measure of central tendency such as a weighted mean or median, and y is the response vector. The the initial values are slight perturbations of the mean towards the actual data. For many type of models this method seems to work well and is often reasonably robust to outliers in the response. Often this argument is only used if the argument method.init is assigned a certain value.

Details

Full details will be given in documentation yet to be written, at a later date!

Value

An object of class "vglmff" (see vglmff-class). The object is used by modelling functions such as vglm and vgam.

Warning

The zero argument is supplied for convenience but conflicts can arise with other arguments, e.g., the constraints argument of vglm and vgam. See Example 5 below for an example. If not sure, use, e.g., constraints(fit) and coef(fit, matrix=TRUE) to check the result of a fit fit.

VGAM family functions with the nsimEIM may have inaccurate working weight matrices. If so, then the standard errors of the regression coefficients may be inaccurate. Thus output from summary(fit), vcov(fit), etc. may be misleading.

Author(s)

T. W. Yee

See Also

Links, vglmff-class.

Examples

# Example 1
cumulative()
cumulative(link="probit", reverse=TRUE, parallel=TRUE)

# Example 2
x = runif(n <- 1000)
y = rweibull(n, shape=2+exp(1+x), scale = exp(-0.5))
fit = vglm(y ~ x, weibull(lshape="logoff", eshape=list(offset=-2), zero=2))
coef(fit, mat=TRUE)
Coef(fit)

# Example 3
x = runif(n <- 500)
y1 = rnbinom(n, mu=exp(3+x), size=exp(1)) # k is size
y2 = rnbinom(n, mu=exp(2-x), size=exp(0))
fit = vglm(cbind(y1,y2) ~ x, negbinomial(zero=-2)) # multivariate response
coef(fit, matrix=TRUE)

# Example 4
## Not run: 
# fit1 and fit2 are equivalent
fit1 = vglm(ymatrix ~ x2 + x3 + x4 + x5,
            cumulative(parallel=FALSE ~ 1 + x3 + x5), mydataframe)
fit2 = vglm(ymatrix ~ x2 + x3 + x4 + x5,
            cumulative(parallel=TRUE ~ x2 + x4), mydataframe)
## End(Not run)

# Example 5
x = rnorm(n <- 200)
y1 = rnorm(n, mean=1-3*x, sd=exp(1+0.2*x))
y2 = rnorm(n, mean=1-3*x, sd=exp(1))
args(normal1)
fit1 = vglm(y1 ~ x, normal1)     # This is ok
fit2 = vglm(y2 ~ x, normal1(zero=2))     # This is ok

# This creates potential conflict
clist = list("(Intercept)"=diag(2), "x"=diag(2))
fit3 = vglm(y2 ~ x, normal1(zero=2), constraints=clist) # Conflict!
coef(fit3, matrix=TRUE)   # Shows that clist[["x"]] was overwritten,
constraints(fit3) # i.e., 'zero' seems to override the 'constraints' arg

[Package VGAM version 0.7-9 Index]