VGAM (version 0.9-6)

vglm: Fitting Vector Generalized Linear Models

Description

vglm is used to fit vector generalized linear models (VGLMs). This is a very large class of models that includes generalized linear models (GLMs) as a special case.

Usage

vglm(formula, family, data = list(), weights = NULL, subset = NULL, 
     na.action = na.fail, etastart = NULL, mustart = NULL, 
     coefstart = NULL, control = vglm.control(...), offset = NULL, 
     method = "vglm.fit", model = FALSE, x.arg = TRUE, y.arg = TRUE, 
     contrasts = NULL, constraints = NULL, extra = list(), 
     form2 = NULL, qr.arg = TRUE, smart = TRUE, ...)

Arguments

formula

a symbolic description of the model to be fit. The RHS of the formula is applied to each linear predictor. Different variables in each linear predictor can be chosen by specifying constraint matrices.

family

a function of class "vglmff" (see vglmff-class) describing what statistical model is to be fitted. This is called a ``VGAM family function''. See

data

an optional data frame containing the variables in the model. By default the variables are taken from environment(formula), typically the environment from which vglm is called.

weights

an optional vector or matrix of (prior fixed and known) weights to be used in the fitting process. If the VGAM family function handles multiple responses ($Q > 1$ of them, say) then weights can be a matrix with $Q$ columns

subset

an optional logical vector specifying a subset of observations to be used in the fitting process.

na.action

a function which indicates what should happen when the data contain NAs. The default is set by the na.action setting of options, and is na.fail if that is u

etastart

starting values for the linear predictors. It is a $M$-column matrix with the same number of rows as the response. If $M = 1$ then it may be a vector. Note that etastart and the output of predict(fit) should be comparable

mustart

starting values for the fitted values. It can be a vector or a matrix; if a matrix, then it has the same number of rows as the response. Usually mustart and the output of fitted(fit) should be comparable. Some family fu

coefstart

starting values for the coefficient vector. The length and order must match that of coef(fit).

control

a list of parameters for controlling the fitting process. See vglm.control for details.

offset

a vector or $M$-column matrix of offset values. These are a priori known and are added to the linear/additive predictors during fitting.

method

the method to be used in fitting the model. The default (and presently only) method vglm.fit() uses iteratively reweighted least squares (IRLS).

model

a logical value indicating whether the model frame should be assigned in the model slot.

x.arg, y.arg

logical values indicating whether the model matrix and response vector/matrix used in the fitting process should be assigned in the x and y slots. Note the model matrix is the LM model matrix; to get the VGLM model matrix

contrasts

an optional list. See the contrasts.arg of model.matrix.default.

constraints

an optional list of constraint matrices. The components of the list must be named with the term it corresponds to (and it must match in character format exactly). There are two types of input: "lm"-type and "vlm"-type. T

extra

an optional list with any extra information that might be needed by the VGAM family function.

form2

The second (optional) formula. If argument xij is used (see vglm.control) then form2 needs to have all terms in the model. Also, some VGAM family fun

qr.arg

logical value indicating whether the slot qr, which returns the QR decomposition of the VLM model matrix, is returned on the object.

smart

logical value indicating whether smart prediction (smartpred) will be used.

...

further arguments passed into vglm.control.

Value

• An object of class "vglm", which has the following slots. Some of these may not be assigned to save space, and will be recreated if necessary later.
• extra
  the list extra at the end of fitting.
• family
  the family function (of class "vglmff").
• iter
  the number of IRLS iterations used.
• predictors
  a $M$-column matrix of linear predictors.
• assign
  a named list which matches the columns and the (LM) model matrix terms.
• call
  the matched call.
• coefficients
  a named vector of coefficients.
• constraints
  a named list of constraint matrices used in the fitting.
• contrasts
  the contrasts used (if any).
• control
  list of control parameter used in the fitting.
• criterion
  list of convergence criterion evaluated at the final IRLS iteration.
• df.residual
  the residual degrees of freedom.
• df.total
  the total degrees of freedom.
• dispersion
  the scaling parameter.
• effects
  the effects.
• fitted.values
  the fitted values, as a matrix. This is often the mean but may be quantiles, or the location parameter, e.g., in the Cauchy model.
• misc
  a list to hold miscellaneous parameters.
• model
  the model frame.
• na.action
  a list holding information about missing values.
• offset
  if non-zero, a $M$-column matrix of offsets.
• post
  a list where post-analysis results may be put.
• preplot
  used by plotvgam, the plotting parameters may be put here.
• prior.weights
  initially supplied weights (the weights argument). Also see weightsvglm.
• qr
  the QR decomposition used in the fitting.
• R
  the R matrix in the QR decomposition used in the fitting.
• rank
  numerical rank of the fitted model.
• residuals
  the working residuals at the final IRLS iteration.
• ResSS
  residual sum of squares at the final IRLS iteration with the adjusted dependent vectors and weight matrices.
• smart.prediction
  a list of data-dependent parameters (if any) that are used by smart prediction.
• terms
  the terms object used.
• weights
  the working weight matrices at the final IRLS iteration. This is in matrix-band form.
• x
  the model matrix (linear model LM, not VGLM).
• xlevels
  the levels of the factors, if any, used in fitting.
• y
  the response, in matrix form.
• This slot information is repeated at vglm-class.

WARNING

See warnings in vglm.control. Also, see warnings under weights above regarding sampling weights from complex sampling designs.

Details

A vector generalized linear model (VGLM) is loosely defined as a statistical model that is a function of $M$ linear predictors. The central formula is given by $$\eta_j = \beta_j^T x$$ where $x$ is a vector of explanatory variables (sometimes just a 1 for an intercept), and $\beta_j$ is a vector of regression coefficients to be estimated. Here, $j=1,\ldots,M$, where $M$ is finite. Then one can write $\eta=(\eta_1,\ldots,\eta_M)^T$ as a vector of linear predictors.

Most users will find vglm similar in flavour to glm. The function vglm.fit actually does the work.

References

Yee, T. W. and Hastie, T. J. (2003) Reduced-rank vector generalized linear models. Statistical Modelling, 3, 15--41.

Yee, T. W. and Wild, C. J. (1996) Vector generalized additive models. Journal of the Royal Statistical Society, Series B, Methodological, 58, 481--493.

Yee, T. W. (2008) The VGAM Package. R News, 8, 28--39.

Documentation accompanying the VGAM package at http://www.stat.auckland.ac.nz/~yee contains further information and examples.

See Also

vglm.control, vglm-class, vglmff-class, smartpred, vglm.fit, fill, rrvglm, vgam. Methods functions include coef.vlm, constraints.vlm, hatvaluesvlm, predictvglm, summary.vglm, AIC.vglm, lrtest_vglm, etc.

Examples

# Example 1. See help(glm)
print(d.AD <- data.frame(treatment = gl(3, 3),
                         outcome = gl(3, 1, 9),
                         counts = c(18,17,15,20,10,20,25,13,12)))
vglm.D93 <- vglm(counts ~ outcome + treatment, family = poissonff,
                 data = d.AD, trace = TRUE)
summary(vglm.D93)


# Example 2. Multinomial logit model
pneumo <- transform(pneumo, let = log(exposure.time))
vglm(cbind(normal, mild, severe) ~ let, multinomial, data = pneumo)


# Example 3. Proportional odds model
fit3 <- vglm(cbind(normal, mild, severe) ~ let, propodds, data = pneumo)
coef(fit3, matrix = TRUE) 
constraints(fit3)
model.matrix(fit3, type = "lm")  # LM model matrix
model.matrix(fit3)               # Larger VGLM (or VLM) model matrix


# Example 4. Bivariate logistic model 
fit4 <- vglm(cbind(nBnW, nBW, BnW, BW) ~ age, binom2.or, coalminers)
coef(fit4, matrix = TRUE)
depvar(fit4)  # Response are proportions
weights(fit4, type = "prior")


# Example 5. The use of the xij argument (simple case).
# The constraint matrix for 'op' has one column.
nn <- 1000
eyesdat <- round(data.frame(lop = runif(nn),
                            rop = runif(nn),
                             op = runif(nn)), digits = 2)
eyesdat <- transform(eyesdat, eta1 = -1 + 2 * lop,
                              eta2 = -1 + 2 * lop)
eyesdat <- transform(eyesdat,
           leye = rbinom(nn, size = 1, prob = logit(eta1, inverse = TRUE)),
           reye = rbinom(nn, size = 1, prob = logit(eta2, inverse = TRUE)))
head(eyesdat)
fit5 <- vglm(cbind(leye, reye) ~ op,
             binom2.or(exchangeable = TRUE, zero = 3),
             data = eyesdat, trace = TRUE,
             xij = list(op ~ lop + rop + fill(lop)),
             form2 = ~  op + lop + rop + fill(lop))
coef(fit5)
coef(fit5, matrix = TRUE)
constraints(fit5)