Description Usage Arguments Details Value Warnings and Limitations Author(s) References See Also Examples
Effect
and effect
construct an "eff"
object for a term (usually a highorder term) in a regression that models a response as a linear function of main effects and interactions of factors and covariates. These models include, among others, linear models (fit by lm
and gls
), and generalized linear models (fit by glm
), for which an "eff"
object is created, and multinomial and proportionalodds logit models (fit respectively by multinom
and polr
), for which an "effpoly"
object is created. The computed effect absorbs the lowerorder terms marginal to the term in question, and averages over other terms in the model. For multivariate linear models (of class "mlm"
, fit by lm
), the functions construct a list of "eff"
objects, separately for the various response variables in the model.
effect
builds the required object by specifying explicitly a focal term like "a:b"
for an a
by b
interaction. Effect
in contrast specifies the predictors in a term, for example c("a", "b")
, rather than the term itself. Effect
is consequently more flexible and robust than effect
, and will succeed with some models for which effect
fails. The effect
function works by constructing a call to Effect
and continues to be included in effects so older code that uses it will not break.
The Effect
and effect
functions can also be used with many other models; see Effect.default
and the Regression Models Supported by the effects Package vignette.
allEffects
identifies all of the highorder terms in a model and returns a list of "eff"
or "effpoly"
objects (i.e., an object of class "efflist"
).
For information on computing and displaying predictor effects, see predictorEffect
and plot.predictoreff
.
For further information about plotting effects, see plot.eff
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46  effect(term, mod, vcov.=vcov, ...)
## Default S3 method:
effect(term, mod, vcov.=vcov, ...)
Effect(focal.predictors, mod, ...)
## S3 method for class 'lm'
Effect(focal.predictors, mod, xlevels=list(),
fixed.predictors, vcov. = vcov, se=TRUE,
residuals=FALSE, quantiles=seq(0.2, 0.8, by=0.2),
x.var=NULL, ...,
#legacy arguments:
given.values, typical, offset, confint, confidence.level,
partial.residuals, transformation)
## S3 method for class 'multinom'
Effect(focal.predictors, mod,
xlevels=list(), fixed.predictors,
vcov. = vcov, se=TRUE, ...,
#legacy arguments:
confint, confidence.level, given.values, typical)
## S3 method for class 'polr'
Effect(focal.predictors, mod,
xlevels=list(), fixed.predictors,
vcov.=vcov, se=TRUE, latent=FALSE, ...,
#legacy arguments:
confint, confidence.level, given.values, typical)
## S3 method for class 'svyglm'
Effect(focal.predictors, mod, fixed.predictors, ...)
## S3 method for class 'merMod'
Effect(focal.predictors, mod, ..., KR=FALSE)
## S3 method for class 'poLCA'
Effect(focal.predictors, mod, ...)
## S3 method for class 'mlm'
Effect(focal.predictors, mod, response, ...)
allEffects(mod, ...)
## Default S3 method:
allEffects(mod, ...)

term 
the quoted name of a term, usually, but not necessarily, a highorder term in the model. The term must be given exactly as it appears in the printed model, although either colons ( 
focal.predictors 
a character vector of one or more predictors in the model in any order. 
mod 
a regression model object. If no specific method exists for the class of 
xlevels 
this argument is used to set the number of levels for any focal numeric predictor (that is predictors that are not factors, character variables, or logical variables, all of which are treated as factors). If More generally, If partial residuals are computed, then the focal predictor that is to appear on the horizontal axis of an effect plot is evaluated at 100 equally spaced values along its full range, and, by default, other numeric predictors are evaluated at the quantiles specified in the 
fixed.predictors 
an optional list of specifications affecting the values at which fixed predictors for an effect are set, potentially including:

vcov. 
Effect methods generally use the matrix returned by 
se 

residuals 
if 
quantiles 
quantiles at which to evaluate numeric focal predictors not on the horizontal axis, used only when partial residuals are displayed; superseded if the 
x.var 
the (quoted) name or index of the numeric predictor to define the horizontal axis of an effect plot for a linear or generalized linear model; the default is 
latent 
if 
x 
an object of class 
KR 
if 
response 
for an 
... 
arguments to be passed down. 
confint, confidence.level, given.values, typical, offset, partial.residuals, transformation 
legacy arguments retained for backwards compatibility; if present, these arguments take precedence over the 
Normally, the functions to be used directly are allEffects
, to return a list of highorder effects, and the generic plot
function to plot the effects (see plot.efflist
, plot.eff
, and plot.effpoly
). Alternatively, Effect
can be used to vary a subset of predictors over their ranges, while other predictors are held to typical values.
Plotting methods for effect objects call 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 higherorder relatives in the model, averaging over those terms (which rarely makes sense), or for terms that do not appear in the model but are higherorder 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 twoway interactions. In either of these cases, a warning is printed.
See predictorEffects
for an alternative paradigm for defining effects.
For "lm"
, "glm"
, "svyglm"
, "lmerMod"
, "glmerMod"
, and "lme"
, model objects, effect
and Effect
return an "eff"
object, and for "multinom"
, "polr"
, "clm"
, "clmm"
, and "clm2"
models, an "effpoly"
object, with the components listed below. For an "mlm"
object with one response specified, an "eff"
object is returned, otherwise an "efflist"
object is returned, containing one "eff"
object for each response
.
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 
variables 
a list with information about each predictor, including its name, whether it is a factor, and its levels or values. 
fit 
(for 
prob 
(for 
logit 
(for 
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. Note: except for 
offset 
value to which the offset is fixed; 
model 
(for 
vcov 
(for 
se 
(for 
se.prob, se.logit 
(for 
lower, upper 
(for 
lower.prob, upper.prob, lower.logit, upper.logit 
(for 
confidence.level 
for the confidence limits. 
transformation 
(for 
residuals 
(working) residuals for linear or generalized linear models (and some similar models), to be used by 
x.var 
the name of the predictor to appear on the horizontal axis of an effect plot made from the returned object; will usually be 
family 
for a 
link 
the value returned by 
allEffects
returns an "efflist"
object, a list of "eff"
or "effpoly"
objects corresponding to the highorder terms of the model.
If mod
is of class "poLCA"
(from the poLCA package), representing a polytomous latent class model, effects are computed for the predictors given the estimated latent classes. The result is of class "eff"
if the latent class model has 2 categories and of class "effpoly"
with more than 2 categories.
The Effect
function handles factors and covariates differently, and is likely to be 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 y ~ 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.
The effect
function doesn't work with factors that 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"
). Level names with colons are perfectly fine for use with Effect
.
The functions in the effects package work properly with predictors that are numeric variables, factors, character variables, or logical variables; consequently, e.g., convert dates to numeric. Character predictors and logical predictors are treated as factors, the latter with "levels" "FALSE"
and "TRUE"
.
Empty cells in crossedfactors are now permitted for "lm"
, "glm"
, and "multinom"
models. For "multinom"
models with two or more crossed factors with an empty cell, stacked area plots apparently do not work because of a bug in the barchart
function in the lattice package. However, the default line plots do work.
Offsets in linear and generalized linear models are supported, as are offsets in mixed models fit by lmer
or glmer
, but must be supplied through the offset
argument to lm
, glm
, lmer
or glmer
; offsets supplied via calls to the offset
function on the righthand side of the model formula are not supported.
Fitting ordinal mixed models using clmm
or clmm2
permits many options, including a variety of link functions, scale functions, nominal regressors, and various methods for setting thresholds. Effects are currently generated only for the default values of the arguments scale
, nominal
, link
, and threshold
, which is equivalent to fitting an ordinalresponse mixedeffects model with a logit link. Effect
can also be used with objects created by clm
or clm2
, fitting ordinal response models with the same links permitted by polr
in the MASS package, with no random effects, and with results similar to those from polr
.
Calling any of these functions from within a userwritten function may result in errors due to R's scoping rules. See the vignette embedding.pdf
in the car package for a solution to this problem.
John Fox jfox@mcmaster.ca, Sanford Weisberg sandy@umn.edu and Jangman Hong.
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, doi: 10.18637/jss.v008.i15.
Fox, J. and R. Andersen (2006). Effect displays for multinomial and proportionalodds logit models. Sociological Methodology 36, 225–255.
Fox, J. and J. Hong (2009). Effect displays in R for multinomial and proportionalodds logit models:? Extensions to the effects package. Journal of Statistical Software 32:1, 1–24, doi: 10.18637/jss.v032.i01.
Fox, J. and S. Weisberg (2019). An R Companion to Applied Regression, third edition, Thousand Oaks: Sage.
Fox, J. and S. Weisberg (2018). Visualizing Fit and Lack of Fit in Complex Regression Models with Predictor Effect Plots with Partial Residuals. Journal of Statistical Software 87:9, 1–27, doi: 10.18637/jss.v087.i09.
Hastie, T. J. (1992). Generalized additive models. In Chambers, J. M., and Hastie, T. J. (eds.) Statistical Models in S, Wadsworth.
Weisberg, S. (2014). Applied Linear Regression, 4th edition, Wiley, http://z.umn.edu/alr4ed.
LegacyArguments
. For information on printing, summarizing, and plotting effects:
print.eff
, summary.eff
, plot.eff
,
print.summary.eff
,
print.effpoly
, summary.effpoly
, plot.effpoly
,
print.efflist
, summary.efflist
,
plot.efflist
, xyplot
,
densityplot
, and the Effect Displays with Partial Residuals and Regression Models Supported by the effects Package vignettes.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251  mod.cowles < glm(volunteer ~ sex + neuroticism*extraversion,
data=Cowles, family=binomial)
eff.cowles < allEffects(mod.cowles, xlevels=list(extraversion=seq(0, 24, 6)),
fixed.predictors=list(given.values=c(sexmale=0.5)))
eff.cowles
as.data.frame(eff.cowles[[2]])
# the following are equivalent:
eff.ne < effect("neuroticism*extraversion", mod.cowles)
Eff.ne < Effect(c("neuroticism", "extraversion"), mod.cowles)
all.equal(eff.ne$fit, Eff.ne$fit)
plot(eff.cowles, 'sex', axes=list(y=list(lab="Prob(Volunteer)")))
plot(eff.cowles, 'neuroticism:extraversion',
axes=list(y=list(lab="Prob(Volunteer)",
ticks=list(at=c(.1,.25,.5,.75,.9)))))
plot(Effect(c("neuroticism", "extraversion"), mod.cowles,
se=list(type="Scheffe"),
xlevels=list(extraversion=seq(0, 24, 6)),
fixed.predictors=list(given.values=c(sexmale=0.5))),
axes=list(y=list(lab="Prob(Volunteer)",
ticks=list(at=c(.1,.25,.5,.75,.9)))))
plot(eff.cowles, 'neuroticism:extraversion', lines=list(multiline=TRUE),
axes=list(y=list(lab="Prob(Volunteer)")))
plot(effect('sex:neuroticism:extraversion', mod.cowles,
xlevels=list(extraversion=seq(0, 24, 6))),
lines=list(multiline=TRUE))
# a nested model:
mod < lm(log(prestige) ~ income:type + education, data=Prestige)
plot(Effect(c("income", "type"), mod, transformation=list(link=log, inverse=exp)),
axes=list(y=list(lab="prestige")))
if (require(nnet)){
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(political.knowledge=0:3)))
plot(Effect(c("Europe", "political.knowledge"), mod.beps,
xlevels=list(Europe=1:11, political.knowledge=0:3),
fixed.predictors=list(given.values=c(gendermale=0.5))),
lines=list(col=c("blue", "red", "orange")),
axes=list(x=list(rug=FALSE), y=list(style="stacked")))
plot(effect("Europe*political.knowledge", mod.beps, # equivalent
xlevels=list(Europe=1:11, political.knowledge=0:3),
fixed.predictors=list(given.values=c(gendermale=0.5))),
lines=list(col=c("blue", "red", "orange")),
axes=list(x=list(rug=FALSE), y=list(style="stacked")))
}
if (require(MASS)){
mod.wvs < polr(poverty ~ gender + religion + degree + country*poly(age,3),
data=WVS)
plot(effect("country*poly(age, 3)", mod.wvs))
plot(Effect(c("country", "age"), mod.wvs),
axes=list(y=list(style="stacked")))
plot(effect("country*poly(age, 3)", mod.wvs),
axes=list(y=list(style="stacked"))) # equivalent
plot(effect("country*poly(age, 3)", latent=TRUE, mod.wvs))
plot(effect("country*poly(age, 3)", latent=TRUE, mod.wvs,
se=list(type="scheffe"))) # Scheffetype confidence envelopes
}
mod.pres < lm(prestige ~ log(income, 10) + poly(education, 3) + poly(women, 2),
data=Prestige)
eff.pres < allEffects(mod.pres, xlevels=50)
plot(eff.pres)
plot(eff.pres[1],
axes=list(x=list(income=list(
transform=list(trans=log10, inverse=function(x) 10^x),
ticks=list(at=c(1000, 2000, 5000, 10000, 20000))
))))
# linear model with logresponse and logpredictor
# to illustrate transforming axes and setting tick labels
mod.pres1 < lm(log(prestige) ~ log(income) + poly(education, 3) + poly(women, 2),
data=Prestige)
# effect of the logpredictor
eff.log < Effect("income", mod.pres1)
# effect of the logpredictor transformed to the arithmetic scale
eff.trans < Effect("income", mod.pres1, transformation=list(link=log, inverse=exp))
#variations:
# yaxis: scale is log, tick labels are log
# xaxis: scale is arithmetic, tick labels are arithmetic
plot(eff.log)
# yaxis: scale is log, tick labels are log
# xaxis: scale is log, tick labels are arithmetic
plot(eff.log, axes=list(x=list(income=list(
transform=list(trans=log, inverse=exp),
ticks=list(at=c(5000, 10000, 20000)),
lab="income, logscale"))))
# yaxis: scale is log, tick labels are arithmetic
# xaxis: scale is arithmetic, tick labels are arithmetic
plot(eff.trans, axes=list(y=list(lab="prestige")))
# yaxis: scale is arithmetic, tick labels are arithmetic
# xaxis: scale is arithmetic, tick labels are arithmetic
plot(eff.trans, axes=list(y=list(type="response", lab="prestige")))
# yaxis: scale is log, tick labels are arithmetic
# xaxis: scale is log, tick labels are arithmetic
plot(eff.trans, axes=list(
x=list(income=list(
transform=list(trans=log, inverse=exp),
ticks=list(at=c(1000, 2000, 5000, 10000, 20000)),
lab="income, logscale")),
y=list(lab="prestige, logscale")),
main="Both response and X in logscale")
# yaxis: scale is arithmetic, tick labels are arithmetic
# xaxis: scale is log, tick labels are arithmetic
plot(eff.trans, axes=list(
x=list(
income=list(transform=list(trans=log, inverse=exp),
ticks=list(at=c(1000, 2000, 5000, 10000, 20000)),
lab="income, logscale")),
y=list(type="response", lab="prestige")))
if (require(nlme)){ # for gls()
mod.hart < gls(fconvict ~ mconvict + tfr + partic + degrees, data=Hartnagel,
correlation=corARMA(p=2, q=0), method="ML")
plot(allEffects(mod.hart))
detach(package:nlme)
}
if (require(lme4)){
data(cake, package="lme4")
fm1 < lmer(angle ~ recipe * temperature + (1recipe:replicate), cake,
REML = FALSE)
plot(Effect(c("recipe", "temperature"), fm1))
plot(effect("recipe:temperature", fm1),
axes=list(grid=TRUE)) # equivalent (plus grid)
if (any(grepl("pbkrtest", search()))) detach(package:pbkrtest)
detach(package:lme4)
}
if (require(nlme) && length(find.package("lme4", quiet=TRUE)) > 0){
data(cake, package="lme4")
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(c("recipe", "temperature"), fm2))
plot(effect("recipe:temperature", fm2),
axes=list(grid=TRUE)) # equivalent (plus grid)
}
detach(package:nlme)
if (require(poLCA)){
data(election)
f2a < cbind(MORALG,CARESG,KNOWG,LEADG,DISHONG,INTELG,
MORALB,CARESB,KNOWB,LEADB,DISHONB,INTELB)~PARTY*AGE
nes2a < poLCA(f2a,election,nclass=3,nrep=5)
plot(Effect(c("PARTY", "AGE"), nes2a),
axes=list(y=list(style="stacked")))
}
# mlm example
if (require(heplots)) {
data(NLSY, package="heplots")
mod < lm(cbind(read,math) ~ income+educ, data=NLSY)
eff.inc < Effect("income", mod)
plot(eff.inc)
eff.edu < Effect("educ", mod)
plot(eff.edu, axes=list(x=list(rug=FALSE), grid=TRUE))
plot(Effect("educ", mod, response="read"))
detach(package:heplots)
}
# svyglm() example (adapting an example from the survey package)
if (require(survey)){
data("api")
dstrat<svydesign(id=~1, strata=~stype, weights=~pw,
data=apistrat, fpc=~fpc)
mod < svyglm(sch.wide ~ ell + meals + mobility, design=dstrat,
family=quasibinomial())
plot(allEffects(mod),
axes=list(y=list(lim=log(c(0.4, 0.99)/c(0.6, 0.01)),
ticks=list(at=c(0.4, 0.75, 0.9, 0.95, 0.99)))))
}
# component + residual plot examples
Prestige$type < factor(Prestige$type, levels=c("bc", "wc", "prof"))
mod.prestige.1 < lm(prestige ~ income + education, data=Prestige)
plot(allEffects(mod.prestige.1, residuals=TRUE)) # standard C+R plots
plot(allEffects(mod.prestige.1, residuals=TRUE,
se=list(type="scheffe"))) # with Scheffetype confidence bands
mod.prestige.2 < lm(prestige ~ type*(income + education), data=Prestige)
plot(allEffects(mod.prestige.2, residuals=TRUE))
mod.prestige.3 < lm(prestige ~ type + income*education, data=Prestige)
plot(Effect(c("income", "education"), mod.prestige.3, residuals=TRUE),
partial.residuals=list(span=1))
# artificial data
set.seed(12345)
x1 < runif(500, 75, 100)
x2 < runif(500, 75, 100)
y < 10 + 5*x1 + 5*x2 + x1^2 + x2^2 + x1*x2 + rnorm(500, 0, 1e3)
Data < data.frame(y, x1, x2)
mod.1 < lm(y ~ poly(x1, x2, degree=2, raw=TRUE), data=Data)
# raw=TRUE necessary for safe prediction
mod.2 < lm(y ~ x1*x2, data=Data)
mod.3 < lm(y ~ x1 + x2, data=Data)
plot(Effect(c("x1", "x2"), mod.1, residuals=TRUE)) # correct model
plot(Effect(c("x1", "x2"), mod.2, residuals=TRUE)) # wrong model
plot(Effect(c("x1", "x2"), mod.3, residuals=TRUE)) # wrong model
