effect {effects}R Documentation

Functions For Constructing Effect Plots

Description

effect constructs an "eff" object for a term (usually a high-order term) in a linear (fit by lm or gls) or generalized linear model (fit by glm), or an "effpoly" object for a term in a multinomial or proportional-odds logit model (fit respectively by multinom or polr), absorbing the lower-order terms marginal to the term in question, and averaging over other terms in the model. The function can also be used with mixed-effects models fit with lmer from the lme4 package, or fit with lme from the nlme package. In mixed effects models the analysis is for the fixed effects only, not for random effects.

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").

Usage

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 'gls'
effect(term, mod, xlevels=list(), default.levels=10, given.values,
	se=TRUE, confidence.level=.95, transformation=NULL, 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, ...)
	
## S3 method for class 'mer'
effect(term, mod, ...)

## S3 method for class 'lme'
effect(term, mod, ...)
    
allEffects(mod, ...)

## S3 method for class 'mer'
allEffects(mod, ...)

## S3 method for class 'lme'
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, ...)

## S3 method for class 'eff'
vcov(object, ...)

Arguments

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", "gls", "glm", "multinom", "polr" "mer" or "lme".

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, this argument 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.

object

an object of class "eff" for which the covariance matrix of the effects is desired.

...

arguments to be passed down.

Details

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.

Value

For lm, glm, mer and lme, 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 "polr", as appropriate.

vcov

(for "eff" objects) a covariance matrix for the effect, on the scale of the linear predictor.

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.

Warnings and Limitations

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.

Factors cannot have colons in level names (e.g., "level:A"); the effect function will confuse the colons with interactions; rename levels to remove or replace the colons (e.g., "level.A").

Binomial generalized linear models cannot have a matrix of successes and failures on the left-hand side of the model formula; instead specify the proportion of successes (i.e., successes/(successes + failures)) as the response, and give the number of binomial trials (i.e., successes + failures) in the weights argument to glm.

Author(s)

John Fox jfox@mcmaster.ca and Jangman Hong. Extension to mer and lme objects by Sanford Weisberg sandy@umn.edu.

References

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, <http://www.jstatsoft.org/v08/i15/>.

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.", <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.

See Also

print.eff, summary.eff, plot.eff, print.summary.eff, print.effpoly, summary.effpoly, plot.effpoly, print.efflist, summary.efflist, plot.efflist, xyplot, densityplot

Examples

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)

mod.hart <- gls(fconvict ~ mconvict + tfr + partic + degrees, data=Hartnagel, 
    correlation=corARMA(p=2, q=0), method="ML")
plot(allEffects(mod.hart), ask=FALSE)

## Not run: 
data(cake, package="lme4")
require(lme4)
fm1 <- lmer(angle ~ recipe * temperature + (1|recipe:replicate), cake,
                   REML = FALSE)
plot(effect("recipe:temperature", fm1), grid=TRUE)
# lme4 and nlme conflict, so detach lme4
detach(package:lme4)
library(nlme)
cake$rep <- with(cake, paste( as.character(recipe), as.character(replicate), sep=""))
fm2 <- lme(angle ~ recipe * temperature, data=cake,
                   random = ~ 1 | rep, method="ML")
plot(effect("recipe:temperature", fm2), grid=TRUE)

## End(Not run)


[Package effects version 2.1-0 Index]