vglmff-class              package:VGAM              R Documentation

_C_l_a_s_s "_v_g_l_m_f_f"

_D_e_s_c_r_i_p_t_i_o_n:

     Family functions for the 'VGAM' package

_O_b_j_e_c_t_s _f_r_o_m _t_h_e _C_l_a_s_s:

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

_S_l_o_t_s:

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

     '_b_l_u_r_b': Object of class '"character"' giving a small description
          of the model. Important arguments such as parameter link
          functions can be expressed here.


     '_c_o_n_s_t_r_a_i_n_t_s': 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'.


     '_d_e_v_i_a_n_c_e': 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'.


     '_f_i_n_i': 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.


     '_f_i_r_s_t': Object of class '"expression"' to insert code at a
          special position in 'vglm' or 'vgam'.


     '_i_n_i_t_i_a_l_i_z_e': 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'. 


     '_i_n_v_e_r_s_e': Object of class '"function"' which returns the fitted
          values, given the linear/additive predictors. The function
          must have arguments 'function(eta, extra=NULL)'.


     '_l_a_s_t': 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.


     '_l_i_n_k': 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)'.


     '_l_o_g_l_i_k_e_l_i_h_o_o_d': 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.


     '_m_i_d_d_l_e': Object of class '"expression"' to insert code at a
          special position in 'vglm.fit' or 'vgam.fit'.


     '_m_i_d_d_l_e_2': Object of class '"expression"' to insert code at a
          special position in 'vglm.fit' or 'vgam.fit'.


     '_s_u_m_m_a_r_y._d_i_s_p_e_r_s_i_o_n': 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.


     '_v_f_a_m_i_l_y': 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.


     '_d_e_r_i_v': 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 *d*i vector.
          Thus each row of the matrix returned by this slot is such a
          vector.


     '_w_e_i_g_h_t': 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 *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.


_M_e_t_h_o_d_s:

     _p_r_i_n_t 'signature(x = "vglmff")': short summary of the family
          function. 

_W_a_r_n_i_n_g:

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

_N_o_t_e:

     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.

_A_u_t_h_o_r(_s):

     Thomas W. Yee

_R_e_f_e_r_e_n_c_e_s:

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

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

_S_e_e _A_l_s_o:

     'vglm', 'vgam', 'rrvglm'.

_E_x_a_m_p_l_e_s:

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

