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,
                               shrinkage.init = 0.95,
                               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 '3' or ... which
          specifies the initialization method for some parameters or a
          specific parameter. If failure to converge occurs try the
          next higher value, and continue until success. 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'. For many 'VGAM' family functions
          it is advisable to try this argument with all possible values
          to safeguard against problems such as converging to a local
          solution. 'VGAM' family functions with this argument usually
          correspond to a model or distribution that is relatively hard
          to fit successfully, therefore care is needed to ensure the
          global solution is obtained. So using all possible values
          that this argument supplies is a good idea.

    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.

shrinkage.init: Shrinkage factor s used for obtaining initial values.
          Numeric, between 0 and 1. In general, the formula used is
          something like s*mu + (1-s)*y where mu is a measure of
          central tendency such as a weighted mean or median, and y is
          the response vector. The the initial values are slight
          perturbations of the mean towards the actual data. For many
          type of models this method seems to work well and is often
          reasonably robust to outliers in the response. Often this
          argument is only used if the argument 'method.init' is
          assigned a certain value.

_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

