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.

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

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

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

[Package VGAM version 1.1-1 Index]