vglmff-class {VGAM} | R Documentation

## Class “vglmff”

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

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

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

`inverse`:
  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.

`link`:
  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)`.

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

`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 di 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 Wi 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.

### 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 packages).

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

A unified method of handling arguments is to use `match.arg`. This allows, for example, `vglm(..., family = cratio(link=logit))` and `vglm(..., family = cratio(link="logi"))` to be equivalent (Nb. there is a `logit` function).

The `extra` argument in `inverse`, `link`, `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.

http://www.stat.auckland.ac.nz/~yee contains further information on how to write VGAM family functions. The file is amongst other VGAM PDF documentation.

### See Also

`vglm`, `vgam`, `rrvglm`.

### Examples

    cratio()
    cratio(link="cloglog")
    cratio(link=cloglog, reverse=TRUE)

[Package VGAM version 0.7-9 Index]