effect                package:effects                R Documentation

_F_u_n_c_t_i_o_n_s _F_o_r _C_o_n_s_t_r_u_c_t_i_n_g _E_f_f_e_c_t _P_l_o_t_s

_D_e_s_c_r_i_p_t_i_o_n:

     'effect' constructs an '"effect"' object for a term (usually a
     high-order term)  in a linear or generalized linear model,
     absorbing the lower-order terms marginal to the term in question,
     and averaging over other terms in the model. 

     'all.effects' identifies all of the high-order terms in a model
     and returns a list of '"effect"' objects (i.e., an object of type
     '"effect.list"').

_U_s_a_g_e:

     effect(term, mod, xlevels=list(), default.levels=10, se=TRUE, 
         confidence.level=.95, 
         transformation=list(link=family(mod)$linkfun, inverse=family(mod)$linkinv), 
         typical=mean)
         
     all.effects(mod, ...)

     ## S3 method for class 'effect':
     as.data.frame(x, row.names=NULL, optional=TRUE)

_A_r_g_u_m_e_n_t_s:

    term: the quoted name of a term, usually, but not necessarily, a
          high-order  term in the model.

     mod: an object of class '"lm"' or '"glm"'.

 xlevels: an optional list of values at which to set covariates, with
          components of the form 'covariate.name = vector.of.values'.

default.levels: number of values for covariates that are not specified
          explicitly via 'xlevels'; covariate values set by default are
          evenly spaced between the minimum and maximum values in the
          data.

      se: if 'TRUE', the default, calculate standard errors and
          confidence limits for the effects.

confidence.level: level at which to compute confidence limits based on
          the standard-normal distribution; the default is '0.95'.

transformation: a two-element list with elements 'link' and 'inverse'.
          For a generalized linear model, these are by default the link
          function and inverse-link (mean) function. For a linear
          model, these default to 'NULL'. If 'NULL', the identify
          function, 'I', is used; this effect can also be achieved by
          setting the argument to 'NULL'. The inverse-link may be used
          to transform effects when they are printed or plotted; the
          link may be used in positioning axis labels (see below). If
          the link is not given, an attempt will be made to approximate
          it from the inverse-link.

 typical: a function to be applied to the columns of the model matrix
          over which the effect is "averaged"; the default is 'mean'.

     ...: arguments to be passed down.

       x: an object of type '"effect"'.

row.names, optional: not used.

_D_e_t_a_i_l_s:

     Normally, the functions to be used directly are 'all.effects', to
     return a list of high-order effects, and the generic 'plot'
     function to plot the effects. (see 'plot.effect.list' and
     'plot.effect'). Plots are drawn using the 'xyplot' function in the
      'lattice' package. Effects may also be printed (implicitly or
     explicitly via 'print') or summarized (using 'summary') (see
     'print.effect.list', 'summary.effect.list', 'print.effect', and
     'summary.effect').

     If asked, the 'effect' function will compute effects for terms
     that have  higher-order relatives in the model, averaging over
     those terms (which rarely makes sense), or for terms that do not
     appear in the model but are higher-order relatives of terms that
     do.  For example, for the model 'Y ~ A*B + A*C + B*C', one could
     compute the effect corresponding to the absent term 'A:B:C', which
     absorbs the constant, the 'A', 'B', and 'C' main effects, and the
     three two-way interactions. In either of these cases, a warning is
     printed.

     In calculating effects, the strategy for `safe' prediction
     described in Hastie (1992: Sec. 7.3.3) is employed.

_V_a_l_u_e:

     'effect' returns an '"effect"' object with the following
     components: 

    term: the term to which the effect pertains.

 formula: the complete model formula.

response: a character string giving the response variable.

variables: a list with information about each predictor, including its
          name, whether it is a factor, and its levels or values.

     fit: a one-column matrix of fitted values, representing the effect
          on the scale of the linear predictor; this is a ravelled
          table, representing all combinations of predictor values.

       x: a data frame, the columns of which are the predictors, and
          the rows of which give all combinations of values of the
          predictors.

model.matrix: the model matrix from which the effect was calculated.

    data: a data frame with the data on which the fitted model was
          based.

discrepancy: the percentage discrepancy for the `safe' predictions of
          the original fit; should be very close to 0.

      se: a vector of standard errors for the effect, on the scale of
          the linear predictor.

lower, upper: one-column matrices of confidence limits, on the scale of
          the linear predictor.

confidence.level: corresponding to the confidence limits.

transformation: a two-element list, with element 'link' giving the link
          function, and element 'inverse' giving the inverse-link
          (mean) function.

_A_u_t_h_o_r(_s):

     John Fox jfox@mcmaster.ca.

_R_e_f_e_r_e_n_c_e_s:

     Fox, J. (1987) Effect displays for generalized linear models.
     _Sociological Methodology_ *17*, 347-361.

     Fox, J. (2003) Effect displays in R for generalised linear models.
     _Journal of Statistical Software_ *8:15*, 1-27, <<URL:
     http://www.jstatsoft.org/counter.php?id=75&url=v08/i15/effect-disp
     lays-revised.pdf&ct=1>>.

     Hastie, T. J. (1992) Generalized additive models. In Chambers, J.
     M., and Hastie, T. J. (eds.) _Statistical Models in S_, Wadsworth.

_S_e_e _A_l_s_o:

     'print.effect', 'summary.effect', 'plot.effect', 
     'print.summary.effect', 'print.effect.list',
     'summary.effect.list', 'plot.effect.list', 'xyplot'

_E_x_a_m_p_l_e_s:

     data(Cowles)
     mod.cowles <- glm(volunteer ~ sex + neuroticism*extraversion, 
         data=Cowles, family=binomial)
     eff.cowles <- all.effects(mod.cowles, xlevels=list(neuroticism=0:24, 
         extraversion=seq(0, 24, 6)))
     eff.cowles
         ## Not run: 
         model: volunteer ~ sex + neuroticism * extraversion
         
         sex effect
         sex
         female      male 
         0.4409441 0.3811941 
         
         neuroticism*extraversion effect
                 extraversion
         neuroticism          0         6        12        18        24
                 0  0.07801066 0.1871263 0.3851143 0.6301824 0.8225756
                 1  0.08636001 0.1963396 0.3870453 0.6200668 0.8083638
                 2  0.09551039 0.2058918 0.3889798 0.6098458 0.7932997
                 3  0.10551835 0.2157839 0.3909179 0.5995275 0.7773775
                . . .
                 23 0.51953129 0.4747277 0.4303273 0.3870199 0.3454282
                 24 0.54709527 0.4895731 0.4323256 0.3768303 0.3243880
         
     ## End(Not run)
     plot(eff.cowles, 'sex', ylab="Prob(Volunteer)")
         ## Not run: 
         Loading required package: lattice 
         
     ## End(Not run)

     plot(eff.cowles, 'neuroticism:extraversion', ylab="Prob(Volunteer)",
         ticks=list(at=c(.1,.25,.5,.75,.9)))

     plot(eff.cowles, 'neuroticism:extraversion', multiline=TRUE, 
         ylab="Prob(Volunteer)")
         
     plot(effect('sex:neuroticism:extraversion', mod.cowles,
         xlevels=list(neuroticism=0:24, extraversion=seq(0, 24, 6))), multiline=TRUE)
     ## Not run: 
         Warning message: 
         sex:neuroticism:extraversion does not appear in the model in: 
           effect("sex:neuroticism:extraversion", mod.cowles, 
           xlevels = list(neuroticism = 0:24,  
     ## End(Not run)

     data(Prestige)
     mod.pres <- lm(prestige ~ log(income, 10) + poly(education, 3) + poly(women, 2), 
         data=Prestige)
     eff.pres <- all.effects(mod.pres, default.levels=50)
     plot(eff.pres, ask=FALSE)

