VGAM (version 0.8-7)

CommonVGAMffArguments: Common VGAM family function Arguments

Description

Here is a description of some common and typical arguments found in many 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,
                          nointercept = NULL, imethod = 1,
                          prob.x = c(0.15, 0.85), mv = FALSE,
                          whitespace = FALSE,
                          oim = FALSE, nsimEIM = 100, zero = NULL)

Arguments

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 m

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,

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 nsi

imethod

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 succ

prob.x

Numeric, of length two. The probabilites that define quantiles with respect to some vector, usually an x of some sort. This is used to create two subsets of data corresponding to `low' and `high' values of x. Each value is separatel

whitespace

Logical. Should white spaces (" ") be used in the labelling of the linear/additive predictors? Setting TRUE usually results in more readability but it occupies more columns of the output.

oim

Logical. Should the observed information matrices (OIMs) be used for the working weights? In general, setting oim = TRUE means the Newton-Raphson algorithm, and oim = FALSE means Fisher-scoring. The latter uses the EIM,

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

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 res

nointercept

An integer-valued vector specifying which linear/additive predictors have no intercepts. Any values must be from the set {1,2,...,$M$}. A value of NULL means no such constraints.

mv

Logical. Some VGAM family functions allow a multivariate or vector response. If so, then usually the response is a matrix with columns corresponding to the individual response variables. They are all fitted simultaneously. Arguments s

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.

The arguments zero and nointercept can be inputted with values that fail. For example, multinomial(zero = 2, nointercept = 1:3) means the second linear/additive predictor is identically zero, which will cause a failure.

Be careful about the use of other potentially contradictory constraints, e.g., multinomial(zero = 2, parallel = TRUE ~ x3). If in doubt, apply constraints() to the fitted object to check.

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.

Details

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

See Also

Links, vglmff-class.

Examples

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

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

# Example 3; multivariate (multiple) response
ndata <- data.frame(x = runif(nn <- 500))
ndata <- transform(ndata,
           y1 = rnbinom(nn, mu = exp(3+x), size = exp(1)), # k is size
           y2 = rnbinom(nn, mu = exp(2-x), size = exp(0)))
fit <- vglm(cbind(y1, y2) ~ x, negbinomial(zero = -2), ndata)
coef(fit, matrix = TRUE)

# Example 4
# 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)

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

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

# Example 6 ('whitespace' argument)
pneumo = transform(pneumo, let = log(exposure.time))
fit1 = vglm(cbind(normal, mild, severe) ~ let,
            sratio(whitespace = FALSE, parallel = TRUE), pneumo)
fit2 = vglm(cbind(normal, mild, severe) ~ let,
            sratio(whitespace = TRUE,  parallel = TRUE), pneumo)
head(predict(fit1), 2) # No white spaces
head(predict(fit2), 2) # Uses white spaces