Create a Family Object

DESCRIPTION:

Returns a function defining a new family object that is recognized by glm and gam. Families that already exist in S-PLUS include Gamma, binomial, gaussian, inverse.gaussian, poisson and quasi.

USAGE:

make.family(name, link, variance, name.link, name.variance) 

REQUIRED ARGUMENTS:

name
character string giving the name of the family.
link
list containing information about the link function. The list must have the following components: a function named link defining the link function for the family; a function named inverse defining the inverse of the link; a function named deriv defining the derivative of the link; and, an expression named initialize which provides initial values for the fitting algorithm. See the family.object help file for more details on initialize. The link list can also have a names component, which is a character string giving the name of the link. If name.link is not specified, the names component is required. To use a link that is already included in S-PLUS, specify the appropriate column of glm.links.
variance
list containing information about the variance function. The list must have the following components: a function named variance defining the variance function for the family; and, a function named deviance defining the deviance. The variance list can also have a names component, which is a character string giving the name of the variance. If name.variance is not specified, the names component is required. To use a variance that is already included in S-PLUS, specify the appropriate column of glm.variances.

OPTIONAL ARGUMENTS:

name.link
character string giving the name of the link function. If link does not have a names component, then name.link is required.
name.variance
character string giving the name of the variance function. If variance does not have a names component, then name.variance is required.

VALUE:

function defining a new family object that can be used as the family argument to glm and gam. For more details on the structure of a family, see the family.object help file.

BACKGROUND:

The combination of a link and variance comprise a family in generalized linear models and generalized additive models. There are many common combinations of link and variance functions, but only some are included in S-PLUS. If you would like to use a family in your analysis that is not yet part of S-PLUS, you will need to use the make.family function. The example data sets glm.links and glm.variances provide the necessary information for the link and variance functions already included in S-PLUS. The information in these data sets can be used as templates when defining your own custom links and variances.

SEE ALSO:

, , , , .

EXAMPLES:

# A family object for the negative binomial distribution
# with link log(mu/(mu+theta)) and variance mu + mu^2/theta,
# for a parameter theta.
neg.binomial <- function(theta = stop("theta must be given"))
{
        nb.link <- list(
                names = "log(mu/(mu + theta))",
                link = substitute(function(mu, th = .Theta) {
                        log(mu/(mu + th))
                },
                  frame = list(.Theta = theta)),
                inverse = substitute(function(eta, th = .Theta) 
                {
                        tmp <- care.exp(eta)
                        return((tmp * th) / (1 - tmp))
                },
                  frame = list(.Theta = theta)),
                deriv = substitute(function(mu, th = .Theta)
                {
                        d <- mu * (mu + th)
                        if(any(tiny <- (d < .Machine$double.eps))) {
                                warning("Model unstable")
                                d[tiny] <- .Machine$double.eps
                        }
                        return(th / d)
                },
                  frame = list(.Theta = theta)),
                initialize = expression(mu <- y + (y==0)/6))
        nb.variance <- list(
                names = "mu + mu^2/theta",
                variance = substitute(function(mu, th = .Theta) {
                        mu * (1 - mu/th)
                },
                  frame = list(.Theta = theta)),
                deviance = substitute(
                        function(mu, y, w, residuals = F, th = .Theta)
                {
                        devi <- 2 * w * (y * log(pmax(1,y) / mu) - 
                                (y + th) * log((y + th) / (mu + th)))
                        if(residuals) 
                                return(sign(y - mu) * sqrt(abs(devi)))
                        else 
                                return(sum(devi))
                },
                  frame = list(.Theta = theta)))
        make.family(
                name = "Negative binomial",
                link = nb.link,
                variance = nb.variance)
}