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 '"eff"' object for a term (usually a
     high-order term)  in a linear or generalized linear model, or an
     '"effpoly"' object for a term in a multinomial or
     proportional-odds logit model,  absorbing the lower-order terms
     marginal to the term in question, and averaging over other terms
     in the model. 

     'allEffects' identifies all of the high-order terms in a model and
     returns a list of '"eff"' or '"effpoly"' objects (i.e., an object
     of type '"efflist"').

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

     effect(term, mod, ...)

     ## S3 method for class 'lm':
     effect(term, mod, xlevels=list(), default.levels=10, given.values, 
             se=TRUE, confidence.level=.95, 
         transformation=list(link=family(mod)$linkfun, inverse=family(mod)$linkinv), 
         typical=mean, ...)
         
     ## S3 method for class 'multinom':
     effect(term, mod, confidence.level=.95, xlevels=list(), default.levels=10, 
             given.values, se=TRUE, typical=mean, ...)
                     
     ## S3 method for class 'polr':
     effect(term, mod, confidence.level=.95, xlevels=list(), default.levels=10, 
             given.values, se=TRUE, typical=mean, latent=FALSE, ...)
         
     allEffects(mod, ...)

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

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

     ## S3 method for class 'efflatent':
     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. The term must be given exactly
          as it appears in the printed model, although either colons
          (':') or asterisks ('*') may be used for interactions.

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

 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.

given.values: a numeric vector of named elements, setting particular
          columns of the model matrix to specific values for terms
          _not_ appearing in an effect; if specified, takes precedence
          over the application of the function given in the 'typical'
          argument (below). Care must be taken in specifying these
          values - e.g., for a factor, the values of all contrasts
          should be given and these should be consistent with each
          other.

      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'.

  latent: if 'TRUE', effects in a proportional-odds logit model are
          computed on the scale of the latent response; if 'FALSE' 
          (the default) effects are computed as individual-level
          probabilities and logits.

       x: an object of class '"eff"' or '"effpoly"'.

row.names, optional: not used.

     ...: arguments to be passed down.

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

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

     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:

     For 'lm' and 'glm', 'effect' returns an '"eff"' object, and for
     'multinom' and 'polr', an '"effpoly"' object, with the following
     components: 

    term: the term to which the effect pertains.

 formula: the complete model formula.

response: a character string giving the name of the response variable.

y.levels: (for '"effpoly"' objects) levels of the polytomous response
          variable.

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

     fit: (for '"eff"' objects) 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.

    prob: (for '"effpoly"' objects) a matrix giving fitted
          probabilities for the effect for the various levels of the
          the response (columns) and combinations of the focal
          predictors (rows).

   logit: (for '"effpoly"' objects) a matrix giving fitted logits for
          the effect for the various levels of the the response
          (columns) and combinations of the focal predictors (rows).

       x: a data frame, the columns of which are the predictors in the
          effect, and the rows of which give all combinations of values
          of these 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.

   model: (for '"effpoly"' objects) '"multinom"' or '"polor"', as
          appropriate.

      se: (for '"eff"' objects) a vector of standard errors for the
          effect, on the scale of the linear predictor.

se.prob, se.logit: (for '"effpoly"' objects) matrices of standard
          errors for the effect, on the probability and logit scales.

lower, upper: (for '"eff"' objects) one-column matrices of confidence
          limits, on the scale of the linear predictor.

lower.prob, upper.prob, lower.logit, upper.logit: (for '"effpoly"'
          objects) matrices of confidence limits for the fitted logits
          and probabilities; the latter are computed by transforming
          the former.

confidence.level: for the confidence limits.

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


     'effectList' returns a list of '"eff"' or '"effpoly"' objects
     corresponding to the high-order terms of the model.

_W_a_r_n_i_n_g:

     The 'effect' function handles factors and covariates differently,
     and becomes confused if one is changed to the other in a model
     formula. Consequently, formulas that include calls to 'as.factor',
     'factor', or 'numeric' (as, e.g., in 'as.factor(income)') will
     cause errors. Instead, create the modified variables outside of
     the model formula (e.g., 'fincome <- as.factor(income)') and use
     these in the model formula.

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

     John Fox jfox@mcmaster.ca and Jangman Hong.

_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-displays-revised.pdf&ct=1>>.

     Fox, J. and R. Andersen (2006) Effect displays for multinomial and
     proportional-odds logit models. _Sociological Methodology_  *36*,
     225-255.

     Fox, J. and J. Hong (2009). Effect displays in R for multinomial
     and proportional-odds logit models:  Extensions to the effects
     package. _Journal of Statistical Software_ *32:1*, 1-24.", <<URL:
     http://www.jstatsoft.org/v32/i01/>>.

     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.eff', 'summary.eff', 'plot.eff',  'print.summary.eff', 
     'print.effpoly', 'summary.effpoly', 'plot.effpoly',
     'print.efflist', 'summary.efflist', 'plot.efflist', 'xyplot', 
     'densityplot'

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

     mod.cowles <- glm(volunteer ~ sex + neuroticism*extraversion, 
         data=Cowles, family=binomial)
     eff.cowles <- allEffects(mod.cowles, xlevels=list(neuroticism=0:24, 
         extraversion=seq(0, 24, 6)), given.values=c(sexmale=0.5))
     eff.cowles

     plot(eff.cowles, 'sex', ylab="Prob(Volunteer)")

     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)

     mod.beps <- multinom(vote ~ age + gender + economic.cond.national +
                                     economic.cond.household + Blair + Hague + Kennedy +
                                     Europe*political.knowledge, data=BEPS)
     plot(effect("Europe*political.knowledge", mod.beps, 
             xlevels=list(Europe=1:11, political.knowledge=0:3)))
             
     plot(effect("Europe*political.knowledge", mod.beps, 
                     xlevels=list(Europe=1:11, political.knowledge=0:3),
                     given.values=c(gendermale=0.5)),
             style="stacked", colors=c("blue", "red", "orange"), rug=FALSE)
             
     mod.wvs <- polr(poverty ~ gender + religion + degree + country*poly(age,3),
             data=WVS)
     plot(effect("country*poly(age, 3)", mod.wvs))

     plot(effect("country*poly(age, 3)", mod.wvs), style="stacked")
             
     plot(effect("country*poly(age, 3)", latent=TRUE, mod.wvs))

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

