gnm {gnm} | R Documentation |
gnm
fits generalised nonlinear models using an
over-parameterised representation. gnm
is able to fit models
incorporating multiplicative interactions as standard and can fit other
types of nonlinear effects via “plug-in” functions (see details).
gnm(formula, eliminate = NULL, ofInterest = NULL, constrain = numeric(0), constrainTo = numeric(length(constrain)), family = gaussian, data = NULL, subset, weights, na.action, method = "gnmFit", offset, start = NULL, tolerance = 1e-6, iterStart = 2, iterMax = 500, trace = FALSE, verbose = TRUE, model = TRUE, x = TRUE, termPredictors = FALSE, lsMethod = "qr", ridge = 1e-8, ...)
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 missing, it is
assumed that all non-eliminate d coefficients are of interest. |
constrain |
coefficients to constrain, specified by a regular expression, a numeric vector of indices, 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. 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. |
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. |
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 progress indicators are
printed as the model is fitted, including a diagnostic error message
if the algorithm restarts. |
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. |
lsMethod |
character: must be one of "chol" or "qr". |
ridge |
numeric, a positive value for the ridge constant to be used in the fitting algorithm |
... |
further arguments passed to fitting function. |
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.
gnm
has the in-built capability to handle multiplicative
interactions, which can be specified in the model formula using the
symbolic wrapper Mult
; e.g. Mult(A, B)
specifies a
multiplicative interaction between factors A
and
B
. The family of multiplicative interaction models include
row-column association models for contingency tables (e.g., Agresti,
2002, Sec 9.6), log-multiplicative or UNIDIFF models (Erikson and
Goldthorpe, 1992; Xie, 1992), and GAMMI models (van Eeuwijk, 1995).
Other nonlinear terms may be incorporated in the model via
plug-in functions that provide the objects required by gnm
to
fit the desired term. Such terms are specified in the model formula
using the symbolic wrapper Nonlin
;
e.g. Nonlin(PlugInFunction(A, B))
specifies a term to be fitted
by the plug-in function PlugInFunction
involving factors
A
and B
. The gnm package includes plug-in
functions for multiplicative interactions with homogeneous effects
(MultHomog
) and diagonal reference terms (Dref
). Users
may also define their own plug-in functions, see Nonlin
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 eliminate
d 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 NA
s 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
. The
lsMethod
argument specifies
what numerical method is to be used to solve the
(typically rank-deficient) least squares problem at the heart of the
gnm
fitting algorithm: the options are
direct solution using a QR decomposition ("qr"
), and matrix
inversion via Cholesky decomposition ("chol"
). In both cases,
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). If lsMethod
is
left unspecified, the default is "qr"
, unless eliminate
is used in which case the default lsMethod
used is "chol"
.
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
contrasts, if these contrasts are identifiable. In particular,
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 zero. Constraints should only be specified for non-eliminated
parameters. update
provides a convenient way of re-fitting a
gnm
model with new constraints.
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. |
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 coefficients. |
eliminate |
the number of eliminated parameters. |
ofInterest |
a named numeric vector of indices, 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 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.
Regular expression matching is performed using grep
with
default settings.
Heather Turner, David Firth
Agresti, A (2002). Categorical Data Analysis (2nd ed.) New York: Wiley.
Cautres, B, Heath, A F and Firth, D (1998). Class, religion and vote in Britain and France. La Lettre de la Maison Francaise 8.
Erikson, R and Goldthorpe, J H (1992). The Constant Flux. Oxford: Clarendon Press.
van Eeuwijk, F A (1995). Multiplicative interaction in generalized linear models. Biometrics 51, 1017-1032.
Xie, Y (1992). The log-multiplicative layer effect model for comparing mobility tables. American Sociological Review 57, 380-395.
formula
for the symbolic language used to specify
formulae.
Diag
and Symm
for specifying special types
of interaction.
Mult
, Nonlin
, Dref
and
MultHomog
for incorporating nonlinear terms in the
formula
argument to gnm
.
residuals.glm
and the generic functions
coef
, fitted
, etc. for extracting
components from gnm
objects.
exitInfo
to print more information on last iteration
when gnm
has not converged.
getContrasts
to estimate (identifiable) contrasts from a
gnm
model.
### Analysis of a 4-way contingency table set.seed(1) data(cautres) 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 - 1), religion:vote - 1) + Mult(Exp(election - 1), class:vote - 1), family = poisson, data = cautres) ## Examine the multipliers of the class-vote log odds ratios coefs.of.interest <- pickCoef(doubleUnidiff, "Mult2.*election") coef(doubleUnidiff)[coefs.of.interest] ## Mult2.Factor1.election1 Mult2.Factor1.election2 ## -0.5724370 0.1092972 ## Mult2.Factor1.election3 Mult2.Factor1.election4 ## -0.1230682 -0.2105843 ## Re-parameterize by setting Mult2.Factor1.election1 to zero getContrasts(doubleUnidiff, coefs.of.interest) ## estimate SE quasiSE quasiVar ## Mult2.Factor1.election1 0.0000000 0.0000000 0.22854380 0.052232270 ## Mult2.Factor1.election2 0.6817370 0.2401642 0.07395880 0.005469905 ## Mult2.Factor1.election3 0.4493740 0.2473519 0.09475932 0.008979329 ## Mult2.Factor1.election4 0.3618262 0.2534753 0.10934823 0.011957035 ## Same thing but with election 4 as reference category: getContrasts(doubleUnidiff, rev(coefs.of.interest)) ## estimate SE quasiSE quasiVar ## Mult2.Factor1.election4 0.00000000 0.0000000 0.10934823 0.011957035 ## Mult2.Factor1.election3 0.08754785 0.1446834 0.09475932 0.008979329 ## Mult2.Factor1.election2 0.31991082 0.1320023 0.07395880 0.005469905 ## Mult2.Factor1.election1 -0.36182617 0.2534753 0.22854380 0.052232270 ## Re-fit model with Mult2.Factor1.election1 set to zero doubleUnidiffConstrained <- update(doubleUnidiff, constrain = coefs.of.interest[1]) ## Examine the multipliers of the class-vote log odds ratios coef(doubleUnidiffConstrained)[coefs.of.interest] ## ...as using 'getContrasts' (to 4 d.p.).