VGAM (version 1.0-1)

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, gsigma, nsimEI, parallel and zero.

Usage

TypicalVGAMfamilyFunction(lsigma = "loge",
                          isigma = NULL,
                          link.list = list("(Default)" = "identitylink",
                                           x2          = "loge",
                                           x3          = "logoff",
                                           x4          = "multilogit",
                                           x5          = "multilogit"),
                          earg.list = list("(Default)" = list(),
                                           x2          = list(),
                                           x3          = list(offset = -1),
                                           x4          = list(),
                                           x5          = list()),
                          gsigma = exp(-5:5),
                          parallel = TRUE,
                          ishrinkage = 0.95,
                          nointercept = NULL, imethod = 1,
                          type.fitted = c("mean", "pobs0", "pstr0", "onempstr0"),
                          probs.x = c(0.15, 0.85),
                          probs.y = c(0.25, 0.50, 0.75),
                          multiple.responses = FALSE, earg.link = FALSE,
                          whitespace = FALSE, bred = FALSE, lss = TRUE,
                          oim = FALSE, nsimEIM = 100, byrow.arg = FALSE,
                          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.

link.list, earg.list

Some VGAM family functions (such as normal.vcm) implement models with potentially lots of parameter link functions. These two arguments allow many such links and extra arguments to b

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

gsigma

Grid-search initial values can be inputted using an argument beginning with "g", e.g., "gsigma", "gshape" and "gscale". If argument isigma is inputted then that has precedence over <

parallel

A logical, or a simple formula specifying which terms have equal/unequal coefficients. The formula must be simple, i.e., additive with simple main effects terms. Interactions and nesting etc. are not handled. To handle complex formulas use the

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

type.fitted

Character. Type of fitted value returned by the fitted() methods function. The first choice is always the default. The available choices depends on what kind of family function it is. Using the first few letters of the chosen choice i

probs.x, probs.y

Numeric, with values in (0, 1). The probabilites that define quantiles with respect to some vector, usually an x or y of some sort. This is used to create two subsets of data corresponding to `low' and `high' values of x

lss

Logical. This stands for the ordering: location, scale and shape. Should the ordering of the parameters be in this order? Almost all VGAM family functions have this order by default, but in order to match the arguments of existing R fun

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

Either an integer vector, or a vector of character strings.

If an integer, then it specifies which linear/additive predictor is modelled as intercept-only. That is, the regression coefficients are set to zero for all covariates except

ishrinkage

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.

multiple.responses

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

earg.link

Sometimes the link argument can receive earg-type input, such as quasibinomial calling binomial. This argument should be generally ig

byrow.arg

Logical. Some VGAM family functions that handle multiple responses have arguments that allow input to be fed in which affect all the responses, e.g., imu for initalizing a mu parameter. In such cases it is so

bred

Logical. Some VGAM family functions will allow bias-reduction based on the work by Kosmidis and Firth. Sometimes half-stepping is a good idea; set stepsize = 0.5 and monitor convergence by setting trace = TRUE

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.

Changes relating to the code{lss} argument have very important consequences and users must beware. Good programming style is to rely on the argument names and not on the order.

Details

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

References

Yee, T. W. (2015) Vector Generalized Linear and Additive Models: With an Implementation in R. New York, USA: Springer.

Kosmidis, I. and Firth, D. (2009) Bias reduction in exponential family nonlinear models. Biometrika, 96(4), 793--804.

See Also

Links, vglmff-class, UtilitiesVGAM, normal.vcm, multilogit.

Examples

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

# Example 2
wdata <- data.frame(x2 = runif(nn <- 1000))
wdata <- transform(wdata,
         y = rweibull(nn, shape = 2 + exp(1 + x2), scale = exp(-0.5)))
fit <- vglm(y ~ x2, weibullR(lshape = logoff(offset = -2), zero = 2), data = 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), data = 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), data = cdata)
fit2 <- vglm(ymatrix ~ x2 + x3 + x4 + x5,
             cumulative(parallel = TRUE ~ x2 + x4), data = cdata)

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

# This creates potential conflict
clist <- list("(Intercept)" = diag(2), "x2" = diag(2))
fit3 <- vglm(y2 ~ x2, uninormal(zero = 2), data = udata,
             constraints = clist)  # Conflict!
coef(fit3, matrix = TRUE)  # Shows that clist[["x2"]] 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), data = pneumo)
fit2 <- vglm(cbind(normal, mild, severe) ~ let,
             sratio(whitespace = TRUE,  parallel = TRUE), data = pneumo)
head(predict(fit1), 2)  # No white spaces
head(predict(fit2), 2)  # Uses white spaces

# Example 7 ('zero' argument with character input)
set.seed(123); n <- 1000
ldata <- data.frame(x2 = runif(n))
ldata <- transform(ldata, y1 = rlogis(n, loc = 0+5*x2, scale = exp(2)))
ldata <- transform(ldata, y2 = rlogis(n, loc = 0+5*x2, scale = exp(0+1*x2)))
ldata <- transform(ldata, w1 = runif(n))
ldata <- transform(ldata, w2 = runif(n))
fit7 <- vglm(cbind(y1, y2) ~ x2,
#            logistic(zero = "location1"),  # location1 is intercept-only
#            logistic(zero = "location2"),
#            logistic(zero = "location*"),  # Not okay... all is unmatched
#            logistic(zero = "scale1"),
#            logistic(zero = "scale2"),
#            logistic(zero = "scale"),  # Both scale parameters are matched
             logistic(zero = c("location", "scale2")),  # All but scale1
#            logistic(zero = c("LOCAT", "scale2")),  # Only scale2 is matched
#            logistic(zero = c("LOCAT")),  # Nothing is matched
#            trace = TRUE,
#            weights = cbind(w1, w2),
             weights = w1,
             data = ldata)
coef(fit7, matrix = TRUE)