vglmff-class {VGAM} | 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.
blurb
:"character"
giving
a small description of the model. Important arguments such as
parameter link functions can be expressed here.
constraints
:"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
:"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
:"expression"
to insert
code at a special position in vglm.fit
or
vgam.fit
.
This code is evaluated immediately after the fitting.
first
:"expression"
to insert
code at a special position in vglm
or
vgam
.
initialize
:"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
:"function"
which
returns the fitted values, given the linear/additive predictors.
The function must have arguments
function(eta, extra=NULL)
.
last
:"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
:"function"
which,
given the fitted values, returns the linear/additive predictors.
If present, the function must have arguments
function(mu, extra=NULL)
.
loglikelihood
:"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
:"expression"
to insert
code at a special position in vglm.fit
or
vgam.fit
.
middle2
:"expression"
to insert
code at a special position in vglm.fit
or
vgam.fit
.
summary.dispersion
:"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
:"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
:"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
:"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.
signature(x = "vglmff")
:
short summary of the family function.
VGAM family functions are not compatible with
glm
, nor gam
(from either
gam or mgcv packages).
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.
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.
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.
cratio() cratio(link="cloglog") cratio(link=cloglog, reverse=TRUE)