vglmff-class | R Documentation |

Family functions for the VGAM package

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

.

In the following, `M`

is the number of linear/additive
predictors.

`start1`

:-
Object of class

`"expression"`

to insert code at a special position (the very start) in`vglm.fit`

or`vgam.fit`

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

. `rqresslot`

:-
Object of class

`"function"`

returning the randomized quantile residuals of the distibution. This slot is optional. If present, the function must have arguments`function(mu, y, w, eta, extra = NULL)`

. `fini1`

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

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

`signature(x = "vglmff")`

: short summary of the family function.

VGAM family functions are not compatible with
`glm`

, nor `gam()`

(from either gam or mgcv).

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.

Thomas W. Yee

Yee, T. W. and Wild, C. J. (1996).
Vector generalized additive models.
*Journal of the Royal Statistical Society, Series B, Methodological*,
**58**, 481–493.

`vglm`

,
`vgam`

,
`rrvglm`

,
`rcim`

.

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

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.