CommonVGAMffArguments {VGAM} | R Documentation

## Common VGAM family function Arguments

### Description

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

### Usage

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

### Arguments

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.

### Details

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

### Value

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

### Warning

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.

### Author(s)

T. W. Yee

### See Also

`Links`, `vglmff-class`.

### Examples

    # 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

[Package VGAM version 0.7-9 Index]