gnm (version 0.9-3)

Nonlin: Specify a Special Nonlinear Term in a Model Formula

Description

A symbolic wrapper, for use in the formula argument to gnm, to indicate a nonlinear term that requires a plug-in function.

Usage

Nonlin(functionCall)

Arguments

functionCall

a call to a plug-in function that provides the objects required to fit the nonlinear term.

Value

• An object of class "Nonlin" which is a list of deparsed expressions representing the variables in the nonlinear term, with the call to the plug-in function as an attribute.

Details

gnm used to use plug-in functions to handle nonlinear terms that could not be specified by Mult. Now all nonlinear terms should be specified by functions of class "nonlin", see nonlin.function for more details.

User-defined plug-in functions will still work, but support for plug-in functions is likely to be withdrawn in future versions. Meanwhile this page is maintained for help with old code.

The functionCall argument of Nonlin specifies the call to the plug-in function that returns objects and functions used by gnm to fit the desired term.

Plug-in functions should return a list with at least the following three components: [object Object],[object Object],[object Object] and optionally one further component [object Object]

Nonlin identifies variables in the term from the call to the plug-in function and returns deparsed expressions representing these variables, so that they can be added to the model frame. By default, expressions passed to unspecified arguments of the plug-in function are deparsed.

If the default action of Nonlin will not capture the required variables, a companion function must exist in the environment of the plug-in function, which takes a call to the plug-in function and returns the necessary deparsed expressions. The name of this function must be the name of the plug-in function suffixed with Variables, e.g. PlugInFunctionVariables would be the companion function for PlugInFunction.

The call to the plug-in function is evaluated in the environment of the model frame and in the enclosing environment of the parent frame of the call to gnm. To access the model frame directly from within a plug-in function (e.g. for use with model.matrix), use getModelFrame.

References

Goodman, L. A. (1979) Simple Models for the Analysis of Association in Cross-Classifications having Ordered Categories. J. Am. Stat. Assoc., 74(367), 537-552.

See Also

gnm, getModelFrame, MultHomog, Dref, Mult

Examples

set.seed(1)
data(occupationalStatus)

## Definition of old MultHomog plug-in function
MultHomogPlugIn <- function(...){
    designList <- lapply(list(...), nnet:::class.ind)

    ## get labels for all levels
    allLevels <- lapply(designList, colnames)
    labels <- unique(unlist(allLevels))
    nLevels <- length(labels)

    ## expand design matrices if necessary
    if (!all(mapply(identical, allLevels, list(labels)))) {
        labels <- sort(labels)
        M <- matrix(0, nrow = nrow(designList[[1]]), ncol = nLevels,
                    dimnames = list(NULL, labels))
        designList <- lapply(designList, function(design, M) {
            M[,colnames(design)] <- design
            M}, M)
    }

    pprod <- function(...) {
        factorList <- list(...)
        nFactors <- length(factorList)
        if (nFactors == 0) return(1)
        else if (nFactors == 1) return(factorList[[1]])
        else {
            tryProduct <- try(factorList[[1]] * do.call("Recall", factorList[-1]),
                              silent = TRUE)
            if (inherits(tryProduct, "try-error"))
                stop("multiplication not implemented for types of argument supplied")
            else tryProduct
        }
    }
        
    predictor <- function(coef) {
        do.call("pprod", lapply(designList, "%*%", coef))
    }

    localDesignFunction <- function(coef, ind = NULL, ...) {
        X <- 0
        vList <- lapply(designList, "%*%", coef)
        for (i in seq(designList)) {
            if (is.null(ind)) 
                X <- X + designList[[i]] * drop(do.call("pprod", vList[-i]))
            else
                X <- X + designList[[i]][, ind] *
                    drop(do.call("pprod", vList[-i]))
        }
        X
    }

    list(labels = labels, predictor = predictor,
         localDesignFunction = localDesignFunction)
}


##  Fit an association model with homogeneous row-column effects
RChomog <- gnm(Freq ~ origin + destination + Diag(origin, destination) +
               Nonlin(MultHomogPlugIn(origin, destination)), family = poisson,
               data = occupationalStatus)