Description

Family functions for the VGAM package

Objects from the Class

Objects can be created by calls of the form new("vglmff", ...).

Slots

In the following, M is the number of linear/additive predictors.

blurb:

Object of class "character" giving a small description of the model. Important arguments such as parameter link functions can be expressed here.

charfun:

Object of class "function" which returns the characteristic function or variance function (usually for some GLMs only). The former uses a dummy variable x. Both use the linear/additive predictors. The function must have arguments function(x, eta, extra = NULL, varfun = FALSE). The eta and extra arguments are used to obtain the parameter values. If varfun = TRUE then the function returns the variance function, else the characteristic function (default). Note that one should check that the infos slot has a list component called charfun which is TRUE before attempting to use this slot. This is an easier way to test that this slot is operable.

constraints:

Object of class "expression" which sets up any constraint matrices defined by arguments in the family function. A zero argument is always fed into cm.zero.vgam, whereas other constraints are fed into cm.vgam.

deviance:

Object of class "function" returning the deviance of the model. This slot is optional. If present, the function must have arguments function(mu, y, w, residuals = FALSE, eta, extra = NULL). Deviance residuals are returned if residuals = TRUE.

fini:

Object of class "expression" to insert code at a special position in vglm.fit or vgam.fit. This code is evaluated immediately after the fitting.

first:

Object of class "expression" to insert code at a special position in vglm or vgam.

infos:

Object of class "function" which returns a list with components such as M1. At present only a very few VGAM family functions have this feature implemented. Those that do do not require specifying the M1 argument when used with rcim.

initialize:

Object of class "expression" used to perform error checking (especially for the variable y) and obtain starting values for the model. In general, etastart or mustart are assigned values based on the variables y, x and w.

linkinv:

Object of class "function" which returns the fitted values, given the linear/additive predictors. The function must have arguments function(eta, extra = NULL).

last:

Object of class "expression" to insert code at a special position (at the very end) of vglm.fit() or vgam.fit(). This code is evaluated after the fitting. The list misc is often assigned components in this slot, which becomes the misc slot on the fitted object.

linkfun:

Object of class "function" which, given the fitted values, returns the linear/additive predictors. If present, the function must have arguments function(mu, extra = NULL). Most VGAM family functions do not have a linkfun function. They largely are for classical exponential families, i.e., GLMs.

loglikelihood:

Object of class "function" returning the log-likelihood of the model. This slot is optional. If present, the function must have arguments function(mu, y, w, residuals = FALSE, eta, extra = NULL). The argument residuals can be ignored because log-likelihood residuals aren't defined.

middle:

Object of class "expression" to insert code at a special position in vglm.fit or vgam.fit.

middle2:

Object of class "expression" to insert code at a special position in vglm.fit or vgam.fit.

simslot:

Object of class "function" to allow simulate to work.

hadof:

Object of class "function"; experimental.

summary.dispersion:

Object of class "logical" indicating whether the general VGLM formula (based on a residual sum of squares) can be used for computing the scaling/dispersion parameter. It is TRUE for most models except for nonlinear regression models.

vfamily:

Object of class "character" giving class information about the family function. Although not developed at this stage, more flexible classes are planned in the future. For example, family functions sratio, cratio, cumulative, and acat all operate on categorical data, therefore will have a special class called "VGAMcat", say. Then if fit was a vglm object, then coef(fit) would print out the vglm coefficients plus "VGAMcat" information as well.

deriv:

Object of class "expression" which returns a M-column matrix of first derivatives of the log-likelihood function with respect to the linear/additive predictors, i.e., the score vector. In Yee and Wild (1996) this is the \bold{d}i vector. Thus each row of the matrix returned by this slot is such a vector.

weight:

Object of class "expression" which returns the second derivatives of the log-likelihood function with respect to the linear/additive predictors. This can be either the observed or expected information matrix, i.e., Newton-Raphson or Fisher-scoring respectively. In Yee and Wild (1996) this is the \bold{W}i matrix. Thus each row of the matrix returned by this slot is such a matrix. Like the weights slot of vglm/vgam, it is stored in matrix-band form, whereby the first M columns of the matrix are the diagonals, followed by the upper-diagonal band, followed by the band above that, etc. In this case, there can be up to M(M+1) columns, with the last column corresponding to the (1,M) elements of the weight matrices.

validfitted, validparams:

Functions that test that the fitted values and all parameters are within range. These functions can issue a warning if violations are detected.

Methods

print

signature(x = "vglmff"): short summary of the family function.

Warning

VGAM family functions are not compatible with glm, nor gam() (from either gam or mgcv).

Note

With link functions etc., one must use substitute to embed the options into the code. There are two different forms: eval(substitute(expression({...}), list(...))) for expressions, and eval(substitute( function(...) { ... }, list(...) )) for functions.

The extra argument in linkinv, linkfun, deviance, loglikelihood, etc. matches with the argument extra in vglm, vgam and rrvglm. This allows input to be fed into all slots of a VGAM family function.

The expression derivative is evaluated immediately prior to weight, so there is provision for re-use of variables etc. Programmers must be careful to choose variable names that do not interfere with vglm.fit, vgam.fit() etc.

Programmers of VGAM family functions are encouraged to keep to previous conventions regarding the naming of arguments, e.g., link is the argument for parameter link functions, zero for allowing some of the linear/additive predictors to be an intercept term only, etc.

In general, Fisher-scoring is recommended over Newton-Raphson where tractable. Although usually slightly slower in convergence, the weight matrices from using the expected information are positive-definite over a larger parameter space.

Author(s)

Thomas 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.

See Also

vglm, vgam, rrvglm, rcim.

Examples