family                 package:stats                 R Documentation

_F_a_m_i_l_y _O_b_j_e_c_t_s _f_o_r _M_o_d_e_l_s

_D_e_s_c_r_i_p_t_i_o_n:

     Family objects provide a convenient way to specify the details of
     the models used by functions such as 'glm'.  See the documentation
     for 'glm' for the details on how such model fitting takes place.

_U_s_a_g_e:

     family(object, ...)

     binomial(link = "logit")
     gaussian(link = "identity")
     Gamma(link = "inverse")
     inverse.gaussian(link = "1/mu^2")
     poisson(link = "log")
     quasi(link = "identity", variance = "constant")
     quasibinomial(link = "logit")
     quasipoisson(link = "log")

_A_r_g_u_m_e_n_t_s:

    link: a specification for the model link function. The 'gaussian'
          family accepts the links '"identity"', '"log"' and
          '"inverse"'; the 'binomial' family the links '"logit"',
          '"probit"', '"cauchit"', (corresponding to logistic, normal
          and Cauchy CDFs respectively) '"log"' and '"cloglog"'
          (complementary log-log); the 'Gamma' family the links
          '"inverse"', '"identity"' and '"log"'; the 'poisson' family
          the links '"log"', '"identity"',  and '"sqrt"' and the
          'inverse.gaussian' family the links '"1/mu^2"', '"inverse"',
          '"identity"' and '"log"'.

          The 'quasi' family allows the links '"logit"', '"probit"',
          '"cloglog"',  '"identity"', '"inverse"', '"log"', '"1/mu^2"'
          and '"sqrt"'. The function 'power' can also be used to create
          a power link function for the 'quasi' family. 

variance: for all families, other than 'quasi', the variance function
          is determined by the family.  The 'quasi' family will accept
          the specifications '"constant"', '"mu(1-mu)"', '"mu"',
          '"mu^2"' and '"mu^3"' for the variance function.

  object: the function 'family' accesses the 'family' objects which are
          stored within objects created by modelling functions (e.g.,
          'glm').

     ...: further arguments passed to methods.

_D_e_t_a_i_l_s:

     'family' is a generic function with methods for classes '"glm"'
     and '"lm"' (the latter returning 'gaussian()').

     The 'quasibinomial' and 'quasipoisson' families differ from the
     'binomial' and 'poisson' families only in that the dispersion
     parameter is not fixed at one, so they can "model"
     over-dispersion.  For the binomial case see McCullagh and Nelder
     (1989, pp. 124-8).  Although they show that there is (under some
     restrictions) a model with variance proportional to mean as in the
     quasi-binomial model, note that 'glm' does not compute
     maximum-likelihood estimates in that model.  The behaviour of S is
     closer to the quasi- variants.

_V_a_l_u_e:

     An object of class '"family"' (which has a concise print method).
     This is a list with elements 

  family: character: the family name.

    link: character: the link name.

 linkfun: function: the link.

 linkinv: function: the inverse of the link function.

variance: function: the variance as a function of the mean.

dev.resids: function giving the deviance residuals as a function of
          '(y, mu, wt)'.

     aic: function giving the AIC value if appropriate (but 'NA' for
          the quasi- families).  See 'logLik' for the assumptions made
          about the dispersion parameter.

  mu.eta: function: derivative 'function(eta)' dmu/deta.

initialize: expression.  This needs to set up whatever data objects are
          needed for the family as well as 'n' (needed for AIC in the
          binomial family) and 'mustart' (see 'glm'.

valid.mu: logical function.  Returns 'TRUE' if a mean vector 'mu' is
          within the domain of 'variance'.

valid.eta: logical function.   Returns 'TRUE' if a linear predictor
          'eta' is within the domain of 'linkinv'.

_A_u_t_h_o_r(_s):

     The design was inspired by S functions of the same names described
     in Hastie & Pregibon (1992) (except 'quasibinomial' and
     'quasipoisson').

_R_e_f_e_r_e_n_c_e_s:

     McCullagh P. and Nelder, J. A. (1989) _Generalized Linear Models._
     London: Chapman and Hall.

     Dobson, A. J. (1983) _An Introduction to Statistical Modelling._
     London: Chapman and Hall.

     Cox, D. R. and  Snell, E. J. (1981). _Applied Statistics;
     Principles and Examples._ London: Chapman and Hall.

     Hastie, T. J. and Pregibon, D. (1992) _Generalized linear models._
     Chapter 6 of _Statistical Models in S_ eds J. M. Chambers and T.
     J. Hastie, Wadsworth & Brooks/Cole.

_S_e_e _A_l_s_o:

     'glm', 'power', 'make.link'.

_E_x_a_m_p_l_e_s:

     nf <- gaussian()# Normal family
     nf
     str(nf)# internal STRucture

     gf <- Gamma()
     gf
     str(gf)
     gf$linkinv
     gf$variance(-3:4) #- == (.)^2

     ## quasipoisson. compare with example(glm)
     counts <- c(18,17,15,20,10,20,25,13,12)
     outcome <- gl(3,1,9)
     treatment <- gl(3,3)
     d.AD <- data.frame(treatment, outcome, counts)
     glm.qD93 <- glm(counts ~ outcome + treatment, family=quasipoisson())
     glm.qD93
     anova(glm.qD93, test="F")
     summary(glm.qD93)
     ## for Poisson results use
     anova(glm.qD93, dispersion = 1, test="Chisq")
     summary(glm.qD93, dispersion = 1)

     ## tests of quasi
     x <- rnorm(100)
     y <- rpois(100, exp(1+x))
     glm(y ~x, family=quasi(var="mu", link="log"))
     # which is the same as
     glm(y ~x, family=poisson)
     glm(y ~x, family=quasi(var="mu^2", link="log"))
     ## Not run: glm(y ~x, family=quasi(var="mu^3", link="log")) # should fail
     y <- rbinom(100, 1, plogis(x))
     # needs to set a starting value for the next fit
     glm(y ~x, family=quasi(var="mu(1-mu)", link="logit"), start=c(0,1))

