gnm: gnm – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

Fitting Generalized Nonlinear Models

Description

gnm fits generalised nonlinear models using an over-parameterized representation. Nonlinear terms are specified by calls to functions of class "nonlin".

Usage

gnm(formula, eliminate = NULL, ofInterest = NULL, constrain = numeric(0),
    constrainTo = numeric(length(constrain)), family = gaussian, 
    data = NULL, subset, weights, na.action,  method = "gnmFit", 
    checkLinear = TRUE, offset, start = NULL, etastart = NULL,
    mustart = NULL, tolerance = 1e-06, iterStart = 2, iterMax = 500,
    trace = FALSE, verbose = TRUE, model = TRUE, x = TRUE,
    termPredictors = FALSE, ridge = 1e-08, ...)

Arguments

`formula`	a symbolic description of the nonlinear predictor.
`eliminate`	a factor to be included as the first term in the model. `gnm` will exploit the structure of this factor to improve computational efficiency. See details.
`ofInterest`	optional coefficients of interest, specified by a regular expression, a numeric vector of indices, a character vector of names, or "[?]" to select from a Tk dialog. If `NULL`, it is assumed that all non-`eliminate`d coefficients are of interest.
`constrain`	(non-eliminated) coefficients to constrain, specified by a regular expression, a numeric vector of indices, a logical vector, a character vector of names, or "[?]" to select from a Tk dialog.
`constrainTo`	a numeric vector of the same length as `constrain` specifying the values to constrain to. By default constrained parameters will be set to zero.
`family`	a specification of the error distribution and link function to be used in the model. This can be a character string naming a family function; a family function, or the result of a call to a family function. See `family` and `wedderburn` for possibilities.
`data`	an optional data frame containing the variables in the model. If not found in `data`, the variables are taken from `environment(formula)`, typically the environment from which `gnm` is called.
`subset`	an optional vector specifying a subset of observations to be used in the fitting process.
`weights`	an optional vector of weights to be used in the fitting process.
`na.action`	a function which indicates what should happen when the data contain `NA`s. If `data` is a contingency table, the default is `"exclude"`. Otherwise the default is first, any `na.action` attribute of `data`; second, any `na.action` setting of `options`, and third, `na.fail`.
`method`	the method to be used: either `"gnmFit"` to fit the model using the default maximum likelihood algorithm, `"coefNames"` to return a character vector of names for the coefficients in the model, `"model.matrix"` to return the model matrix, `"model.frame"` to return the model frame, or the name of a function providing an alternative fitting algorithm.
`checkLinear`	logical: if `TRUE` `glm.fit` is used when the predictor is found to be linear
`offset`	this can be used to specify an a priori known component to be added to the predictor during fitting. `offset` terms can be included in the formula instead or as well, and if both are specified their sum is used.
`start`	a vector of starting values for the parameters in the model; if a starting value is `NA`, the default starting value will be used. Starting values need not be specified for eliminated parameters.
`etastart`	starting values for the linear predictor.
`mustart`	starting values for the vector of means.
`tolerance`	a positive numeric value specifying the tolerance level for convergence.
`iterStart`	a positive integer specifying the number of start-up iterations to perform.
`iterMax`	a positive integer specifying the maximum number of main iterations to perform.
`trace`	a logical value indicating whether the deviance should be printed after each iteration.
`verbose`	logical: if `TRUE` and model includes nonlinear terms, progress indicators are printed as the model is fitted, including a diagnostic error message if the algorithm fails.
`model`	logical: if `TRUE` the model frame is returned.
`x`	logical: if `TRUE` the local design matrix from the last iteration is included as a component of returned model object.
`termPredictors`	logical: if `TRUE`, a matrix is returned with a column for each term in the model, containing the additive contribution of that term to the predictor.
`ridge`	numeric, a positive value for the ridge constant to be used in the fitting algorithm
`...`	further arguments passed to fitting function.

Details

Models for gnm are specified by giving a symbolic description of the nonlinear predictor, of the form response ~ terms. The response is typically a numeric vector, see later in this section for alternatives. The usual symbolic language may be used to specify any linear terms, see formula for details.

Nonlinear terms may be specified by calls to functions of class "nonlin". There are several "nonlin" functions in the gnm package. Some of these specify simple mathematical functions of predictors: Exp, Mult, and Inv. Others specify more specialised nonlinear terms, in particular MultHomog specifies homogeneous multiplicative interactions and Dref specifies diagonal reference terms. Users may also define their own "nonlin" functions, see nonlin.function for details.

The eliminate argument may be used to specify a factor that is to be included as the first term in the model (since an intercept is then redundant, none is fitted). The structure of the factor is exploited to improve computational efficiency — substantially so if the eliminated factor has a large number of levels. Use of eliminate is designed for factors that are required in the model but are not of direct interest (e.g., terms needed to fit multinomial-response models as conditional Poisson models). See backPain for an example.

The ofInterest argument may be used to specify coefficients of interest, the indices of which are returned in the ofInterest component of the model object. print() displays of the model object or its components obtained using accessor functions such as coef() etc, will only show these coefficients. In addition methods for "gnm" objects which may be applied to a subset of the parameters are by default applied to the coefficients of interest. See ofInterest for accessor and replacement functions.

For contingency tables, the data may be provided as an object of class "table" from which the frequencies will be extracted to use as the response. In this case, the response should be specified as Freq in the model formula. The "predictors", "fitted.values", "residuals", "prior.weights", "weights", "y" and "offset" components of the returned gnm fit will be tables with the same format as the data, completed with NAs where necessary.

For binomial models, the response may be specified as a factor in which the first level denotes failure and all other levels denote success, as a two-column matrix with the columns giving the numbers of successes and failures, or as a vector of the proportions of successes.

The gnm fitting algorithm consists of two stages. In the start-up iterations, any nonlinear parameters that are not specified by either the start argument of gnm or a plug-in function are updated one parameter at a time, then the linear parameters are jointly updated before the next iteration. In the main iterations, all the parameters are jointly updated, until convergence is reached or the number or iterations reaches iterMax. To solve the (typically rank-deficient) least squares problem at the heart of the gnm fitting algorithm, the design matrix is standardized and regularized (in the Levenberg-Marquardt sense) prior to solving; the ridge argument provides a degree of control over the regularization performed (smaller values may sometimes give faster convergence but can lead to numerical instability).

Convergence is judged by comparing the squared components of the score vector with corresponding elements of the diagonal of the Fisher information matrix. If, for all components of the score vector, the ratio is less than tolerance^2, or the corresponding diagonal element of the Fisher information matrix is less than 1e-20, iterations cease. If the algorithm has not converged by iterMax iterations, exitInfo can be used to print information on the parameters which failed the convergence criteria at the last iteration.

By default, gnm uses an over-parameterized representation of the model that is being fitted. Only minimal identifiability constraints are imposed, so that in general a random parameterization is obtained. The parameter estimates are ordered so that those for any linear terms appear first.

getContrasts may be used to obtain estimates of specified scaled contrasts, if these contrasts are identifiable. For example, getContrasts may be used to estimate the contrasts between the first level of a factor and the rest, and obtain standard errors.

If appropriate constraints are known in advance, or have been determined from a gnm fit, the model may be (re-)fitted using the constrain argument to specify coefficients which should be set to values specified by constrainTo. Constraints should only be specified for non-eliminated parameters. update provides a convenient way of re-fitting a gnm model with new constraints.

Value

If method = "gnmFit", gnm returns NULL if the algorithm has failed and an object of class "gnm" otherwise. A "gnm" object inherits first from "glm" then "lm" and is a list containing the following components:

`call`	the matched call.
`formula`	the formula supplied.
`constrain`	a numeric vector specifying any coefficients that were constrained in the fitting process.
`constrainTo`	a numeric vector of the same length as `constrain` specifying the values which constrained parameters were set to.
`family`	the `family` object used.
`prior.weights`	the case weights initially supplied.
`terms`	the `terms` object used.
`data`	the `data` argument.
`na.action`	the `na.action` attribute of the model frame
`xlevels`	a record of the levels of the factors used in fitting.
`y`	the response used.
`offset`	the offset vector used.
`coefficients`	a named vector of non-eliminated coefficients, with an attribute `"eliminated"` specifying the eliminated coefficients if `eliminate` is non-`NULL`.
`eliminate`	the `eliminate` argument.
`ofInterest`	a named numeric vector of indices corresponding to non-eliminated coefficients, or `NULL`.
`predictors`	the fitted values on the link scale.
`fitted.values`	the fitted mean values, obtained by transforming the predictors by the inverse of the link function.
`deviance`	up to a constant, minus twice the maximised log-likelihood. Where sensible, the constant is chosen so that a saturated model has deviance zero.
`aic`	Akaike's An Information Criterion, minus twice the maximized log-likelihood plus twice the number of parameters (so assuming that the dispersion is known).
`iter`	the number of main iterations.
`conv`	logical indicating whether the main iterations converged, with an attribute for use by `exitInfo` if `FALSE`.
`weights`	the working weights, that is, the weights used in the last iteration.
`residuals`	the working residuals, that is, the residuals from the last iteration.
`df.residual`	the residual degrees of freedom.
`rank`	the numeric rank of the fitted model.

The list may also contain the components model, x, or termPredictors if requested in the arguments to gnm.

If a table was passed to data and the default for na.action was not overridden, the list will also contain a table.attr component, for use by the extractor functions.

If a binomial gnm model is specified by giving a two-column response, the weights returned by prior.weights are the total numbers of cases (factored by the supplied case weights) and the component y of the result is the proportion of successes.

The function summary.gnm may be used to obtain and print a summary of the results, whilst plot.gnm may be used for model diagnostics.

The generic functions formula, family, terms, coefficients, fitted.values, deviance, extractAIC, weights, residuals, df.residual, model.frame, model.matrix, vcov and termPredictors maybe used to extract components from the object returned by gnm or to construct the relevant objects where necessary.

Note that the generic functions weights and residuals do not act as straight-forward accessor functions for gnm objects, but return the prior weights and deviance residuals respectively, as for glm objects.

Note

Regular expression matching is performed using grep with default settings.

Author(s)

Heather Turner and David Firth

References

Cautres, B, Heath, A F and Firth, D (1998). Class, religion and vote in Britain and France. La Lettre de la Maison Francaise 8.

Examples

###  Analysis of a 4-way contingency table
set.seed(1)
print(cautres)

##  Fit a "double UNIDIFF" model with the religion-vote and class-vote
##  interactions both modulated by nonnegative election-specific
##  multipliers.
doubleUnidiff <- gnm(Freq ~ election:vote + election:class:religion
                     + Mult(Exp(election), religion:vote) +
                     Mult(Exp(election), class:vote), family = poisson,
                     data = cautres)

##  Examine the multipliers of the class-vote log odds ratios
ofInterest(doubleUnidiff) <- pickCoef(doubleUnidiff, "class:vote[).]")
coef(doubleUnidiff)
## Coefficients of interest:
## Mult(Exp(.), class:vote).election1 
##                        -0.38357138 
## Mult(Exp(.), class:vote).election2 
##                         0.29816599 
## Mult(Exp(.), class:vote).election3 
##                         0.06580307 
## Mult(Exp(.), class:vote).election4 
##                        -0.02174104

##  Re-parameterize by setting first multiplier to zero
getContrasts(doubleUnidiff, ofInterest(doubleUnidiff))
##                                     estimate        SE
## Mult(Exp(.), class:vote).election1 0.0000000 0.0000000
## Mult(Exp(.), class:vote).election2 0.6817374 0.2401644
## Mult(Exp(.), class:vote).election3 0.4493745 0.2473521
## Mult(Exp(.), class:vote).election4 0.3618301 0.2534754
##                                       quasiSE    quasiVar
## Mult(Exp(.), class:vote).election1 0.22854401 0.052232363
## Mult(Exp(.), class:vote).election2 0.07395886 0.005469913
## Mult(Exp(.), class:vote).election3 0.09475938 0.008979340
## Mult(Exp(.), class:vote).election4 0.10934798 0.011956981

##  Same thing but with last multiplier as reference category:
getContrasts(doubleUnidiff, rev(ofInterest(doubleUnidiff)))
##                                       estimate        SE
## Mult(Exp(.), class:vote).election4  0.00000000 0.0000000
## Mult(Exp(.), class:vote).election3  0.08754436 0.1446833
## Mult(Exp(.), class:vote).election2  0.31990727 0.1320022
## Mult(Exp(.), class:vote).election1 -0.36183013 0.2534754
##                                       quasiSE    quasiVar
## Mult(Exp(.), class:vote).election4 0.10934798 0.011956981
## Mult(Exp(.), class:vote).election3 0.09475938 0.008979340
## Mult(Exp(.), class:vote).election2 0.07395886 0.005469913
## Mult(Exp(.), class:vote).election1 0.22854401 0.052232363

##  Re-fit model with first multiplier set to zero
doubleUnidiffConstrained <-
    update(doubleUnidiff, constrain = ofInterest(doubleUnidiff)[1])

##  Examine the multipliers of the class-vote log odds ratios
coef(doubleUnidiffConstrained)[ofInterest(doubleUnidiff)]
##  ...as using 'getContrasts' (to 4 d.p.).

gnm

Generalized Nonlinear Models

v1.1-1

GPL-2 | GPL-3

Authors

Heather Turner [aut, cre] (<https://orcid.org/0000-0002-1256-3375>), David Firth [aut] (<https://orcid.org/0000-0003-0302-2312>), Brian Ripley [ctb], Bill Venables [ctb], Douglas M. Bates [ctb], Martin Maechler [ctb] (<https://orcid.org/0000-0002-8685-9910>)

Initial release

gnm