CommonVGAMffArguments          package:VGAM          R Documentation

_C_o_m_m_o_n _V_G_A_M _f_a_m_i_l_y _f_u_n_c_t_i_o_n _A_r_g_u_m_e_n_t_s

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

     Here is a description of some common and typical arguments found
     in 'VGAM' family functions, e.g., 'lsigma',  'isigma', 'nsimEI',
     'parallel' and 'zero'.

_U_s_a_g_e:

     TypicalVGAMfamilyFunction(lsigma="loge", esigma=list(),
                               isigma=NULL, parallel = TRUE,
                               method.init=1, nsimEIM=100, zero=NULL)

_A_r_g_u_m_e_n_t_s:

     Almost every 'VGAM' family function has an argument list similar
     to the one given above.  Below, M is the number of linear/additive
     predictors.

  lsigma: Character. Link function applied to a parameter and not
          necessarily a mean. See 'Links' for a selection of choices.
          If there is only one parameter then this argument is often
          called 'link'.

  esigma: List. Extra argument allowing for additional information,
          specific to the link function. See 'Links' for more
          information. If there is only one parameter then this
          argument is often called 'earg'.

  isigma: Optional initial values can often be inputted using an
          argument beginning with '"i"'. For example, '"isigma"' and
          '"ilocation"', or just '"init"' if there is one parameter. A
          value of 'NULL' means a value is computed internally, i.e., a
          _self-starting_ 'VGAM' family function. If a failure to
          converge occurs make use of these types of arguments.

parallel: A logical, or formula specifying which terms have
          equal/unequal coefficients. This argument is common in 'VGAM'
          family functions for categorical responses, e.g.,
          'cumulative',  'acat',  'cratio', 'sratio'. For the
          proportional odds model ('cumulative') having parallel
          constraints applied to each explanatory variable (except for
          the intercepts) means the fitted probabilities do not become
          negative or greater than 1. However this parallelism or
          proportional-odds assumption ought to be checked.

 nsimEIM: Some 'VGAM' family functions use simulation to obtain an
          approximate expected information matrix (EIM). For those that
          do, the 'nsimEIM' argument specifies the number of random
          variates used per observation; the mean of 'nsimEIM' random
          variates is taken. Thus 'nsimEIM' controls the accuracy and a
          larger value may be necessary if the EIMs are not
          positive-definite. For intercept-only models ('y ~ 1)' the
          value of 'nsimEIM' can be smaller (since the common value
          used is also then taken as the mean over the observations),
          especially if the number of observations is large.

          Some 'VGAM' family functions provide two algorithms for
          estimating the EIM. If applicable, set 'nsimEIM=NULL' to
          choose the other algorithm.

method.init: An integer with value '1' or '2' or or '3' ... which
          specifies the initialization method for some parameters or a
          specific parameter.  If failure to converge occurs try the
          next higher value. For example, 'method.init=1' might be the
          method of moments, and 'method.init=2' might be another
          method. If no value of 'method.init' works then it will be
          necessary to use arguments such as 'isigma'.

    zero: An integer specifying which linear/additive predictor is
          modelled as intercepts-only. That is, the regression
          coefficients are set to zero for all covariates except for
          the intercept. If 'zero' is specified then it is a vector
          with values from the set {1,2,...,M}. The value 'zero=NULL'
          means model all linear/additive predictors as functions of
          the explanatory variables.

          Some 'VGAM' family functions allow the 'zero' argument to
          accept negative values; if so then its absolute value is
          recycled over each response. For example, 'zero=-2' would
          mean, for each response, the second linear/additive predictor
          is modelled as intercepts-only. A specific example is the k
          parameter in 'negbinomial'; this 'VGAM' family function can
          handle a matrix of responses.

_D_e_t_a_i_l_s:

     Full details will be given in documentation yet to be written, at
     a later date!

_V_a_l_u_e:

     An object of class '"vglmff"' (see 'vglmff-class'). The object is
     used by modelling functions such as 'vglm' and 'vgam'.

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

     The 'zero' argument is supplied for convenience but conflicts can
     arise with other arguments, e.g., the 'constraints' argument of
     'vglm' and 'vgam'. See Example 5 below for an example. If not
     sure, use, e.g., 'constraints(fit)' and 'coef(fit, matrix=TRUE)'
     to check the result of a fit 'fit'.

     'VGAM' family functions with the 'nsimEIM' may have inaccurate
     working weight matrices. If so, then the standard errors of the
     regression coefficients may be inaccurate. Thus output from
     'summary(fit)', 'vcov(fit)', etc. may be misleading.

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

     T. W. Yee

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

     'Links', 'vglmff-class'.

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

     # Example 1
     cumulative()
     cumulative(link="probit", reverse=TRUE, parallel=TRUE)

     # Example 2
     x = runif(n <- 1000)
     y = rweibull(n, shape=2+exp(1+x), scale = exp(-0.5))
     fit = vglm(y ~ x, weibull(lshape="logoff", eshape=list(offset=-2), zero=2))
     coef(fit, mat=TRUE)
     Coef(fit)

     # Example 3
     x = runif(n <- 500)
     y1 = rnbinom(n, mu=exp(3+x), size=exp(1)) # k is size
     y2 = rnbinom(n, mu=exp(2-x), size=exp(0))
     fit = vglm(cbind(y1,y2) ~ x, negbinomial(zero=-2)) # multivariate response
     coef(fit, matrix=TRUE)

     # Example 4
     ## Not run: 
     # fit1 and fit2 are equivalent
     fit1 = vglm(ymatrix ~ x2 + x3 + x4 + x5,
                 cumulative(parallel=FALSE ~ 1 + x3 + x5), mydataframe)
     fit2 = vglm(ymatrix ~ x2 + x3 + x4 + x5,
                 cumulative(parallel=TRUE ~ x2 + x4), mydataframe)
     ## End(Not run)

     # Example 5
     x = rnorm(n <- 200)
     y1 = rnorm(n, mean=1-3*x, sd=exp(1+0.2*x))
     y2 = rnorm(n, mean=1-3*x, sd=exp(1))
     args(normal1)
     fit1 = vglm(y1 ~ x, normal1)     # This is ok
     fit2 = vglm(y2 ~ x, normal1(zero=2))     # This is ok

     # This creates potential conflict
     clist = list("(Intercept)"=diag(2), "x"=diag(2))
     fit3 = vglm(y2 ~ x, normal1(zero=2), constraints=clist) # Conflict!
     coef(fit3, matrix=TRUE)   # Shows that clist[["x"]] was overwritten,
     constraints(fit3) # i.e., 'zero' seems to override the 'constraints' arg

