plot.effects: Plots of Effects and Predictor Effects

Description

plot methods for predictoreff, predictorefflist, eff, efflist and effpoly objects created by calls other methods in the effects package. The plot arguments were substantially changed in mid-2017. For more details and many examples, see the Predictor Effects Graphics Gallery vignette.

Usage

# S3 method for eff
plot(x, x.var, 
    main=paste(effect, "effect plot"),
    symbols=TRUE, lines=TRUE, axes, confint,
    partial.residuals, id, lattice, ...,
    # legacy arguments:
    multiline, z.var, rug, xlab, ylab, colors, cex, lty, lwd,
    ylim, xlim, factor.names, ci.style,
    band.transparency, band.colors, type, ticks,
    alternating, rotx, roty, grid, layout,
    rescale.axis, transform.x, ticks.x, show.strip.values,
    key.args, use.splines,
    residuals.color, residuals.pch, residuals.cex, smooth.residuals,
    residuals.smooth.color, show.fitted, span)
    
# S3 method for efflist
plot(x, selection, rows, cols, ask=FALSE, graphics=TRUE, lattice, ...)
# S3 method for predictoreff
plot(x, x.var, 
    main = paste(names(x$variables)[1], "predictor effect plot"), ...)
# S3 method for predictorefflist
plot(x, selection, rows, cols, ask = FALSE, 
    graphics = TRUE, lattice, ...)
# S3 method for effpoly
plot(x, x.var=which.max(levels),
    main=paste(effect, "effect plot"),
    symbols=TRUE, lines=TRUE, axes, confint, lattice, ...,
    # legacy arguments:
    type, multiline, rug, xlab, ylab, colors, cex, lty, lwd,
    factor.names, show.strip.values,
    ci.style, band.colors, band.transparency, style,
    transform.x, ticks.x, xlim,
    ticks, ylim, rotx, roty, alternating, grid,
    layout, key.args, use.splines)
    
# S3 method for mlm.efflist
plot(x, ...)

Value

The summary method for "eff" objects returns a "summary.eff" object with the following components (those pertaining to confidence limits need not be present):

header: a character string to label the effect.
effect: an array containing the estimated effect.
lower.header: a character string to label the lower confidence limits.
lower: an array containing the lower confidence limits.
upper.header: a character string to label the upper confidence limits.
upper: an array containing the upper confidence limits.

The plot method for "eff" objects returns a "plot.eff" object (an enhanced "trellis" object); the provided print method plots the object.

The [ method for "efflist" objects is used to subset an "efflist" object and returns an object of the same class.

Arguments

x: an object of class "predictoreff", "predictorefflist", "eff", "effpoly", "efflist", "mlm.efflist", or "summary.eff", as appropriate.
x.var: the index (number) or quoted name of the covariate or factor to place on the horizontal axis of each panel of the effect plot. The default is the predictor with the largest number of levels or values. This argument is ignored with predictoreff objects.
main: the title for the plot, printed at the top; the default title is constructed from the name of the effect.
symbols: TRUE, FALSE, or an optional list of specifications for plotting symbols; if not given, symbol properties are taken from superpose.symbol in the lattice theme. See Detailed Argument Descriptions under Details for more information.
lines: TRUE, FALSE, or an optional list of specifications for plotting lines (and possibly areas); if not given, line properties are taken from superpose.line in the lattice theme. See Detailed Argument Descriptions under Details for more information.
axes: an optional list of specifications for the x and y axes; if not given, axis properties take generally reasonable default values. See Details for more information.
confint: an optional list of specifications for plotting confidence regions and intervals; if not given, generally reasonable default values are used. See Detailed Argument Descriptions under Details for more information.
partial.residuals: an optional list of specifications for plotting partial residuals for linear and generalized linear models; if not given, generally reasonable default values are used. See Detailed Argument Descriptions under Details for more information, along with the Effect Displays with Partial Residuals vignette.
id: an optional list of specifications for identifying points when partial residuals are plotted; if not specified, no points are labelled. See Detailed Argument Descriptions under Details for more information.
lattice: an optional list of specifications for various lattice properties, such as legend placement; if not given, generally reasonable default values are used. See Detailed Argument Descriptions under Details for more information.
selection: the optional index (number) or quoted name of the effect in an efflist object to be plotted; if not supplied, a menu of high-order terms is presented or all effects are plotted.
rows, cols: Number of rows and columns in the ``meta-array'' of plots produced for an efflist object; if either argument is missing, then the meta-layout will be computed by the plot method.
ask: if selection is not supplied and ask is TRUE, a menu of high-order terms is presented; if ask is FALSE (the default), effects for all high-order terms are plotted in an array.
graphics: if TRUE (the default), then the menu of terms to plot is presented in a dialog box rather than as a text menu.
...: arguments to be passed down. For "predictoreff" or "predictorefflist" objects, the arguments passed down can include all the arguments for "eff".
multiline, z.var, rug, xlab, ylab, colors, cex, lty, lwd, ylim, xlim, factor.names, ci.style, band.transparency, band.colors, ticks, alternating, rotx, roty, grid, layout, rescale.axis, transform.x, ticks.x, show.strip.values, key.args, use.splines, type, residuals.color, residuals.pch, residuals.cex, smooth.residuals, residuals.smooth.color, show.fitted, span, style: legacy arguments retained for backwards compatibility; if specified, these will take precedence over the newer list-style arguments described above. See LegacyArguments for details.

Author

John Fox jfox@mcmaster.ca and Jangman Hong.

Details

Effects plots and predictor effects plots are produced by these methods. The plots are highly customizable using the optional arguments described here. For example, effects in a GLM are plotted on the scale of the linear predictor, but the vertical axis is labelled on the response scale. This preserves the linear structure of the model while permitting interpretation on what is usually a more familiar scale. This approach may also be used with linear models, for example to display effects on the scale of the response even if the data are analyzed on a transformed scale, such as log or square-root. See the axes argument details below to change the scale to response scale, or to linear predictor scale with tick marks labeled in response scale.

When a factor is on the x-axis, the plot method for eff objects connects the points representing the effect by line segments, creating a response ``profile.'' If you wish to suppress these lines, add lty=0 to the lines argument to the call to plot (see below and the examples).

In a polytomous multinomial or proportional-odds logit model, by default effects are plotted on the probability scale; they may alternatively be plotted on the scale of the individual-level logits.

All of the arguments to plot objects created by Effect or allEffects can also be used with objects created by predictorEffect or predictorEffects.

Detailed Argument Descriptions

For more information about these arguments and many examples, see the Predictor Effects Graphics Gallery vignette.

Maximizing the flexibility of these plot commands requires inclusion of a myriad of options. In an attempt to simplify the use of these options, they have been organized into just a few arguments that each accept a list of specifications as an argument. In a few cases the named entries in the list are themselves lists.

Each of the following arguments takes an optional list of specifications; any specification absent from the list assumes its default value. Some of the list elements are themselves lists, so in complex cases, the argument can take the form of nested lists. All of these arguments can also be used on objects created with predictorEffects.

symbols

TRUE, FALSE, or a list of options that controls the plotting symbols and their sizes for use with factors; if FALSE symbols are suppressed; if TRUE default values are used:

pch: ploting symbols, a vector of plotting characters, with the default taken from trellis.par.get("superpose.symbol")$pch, typically a vector of 1s (circles).
cex: plotting character sizes, a vector of values, with the default taken from trellis.par.get("superpose.symbol")$cex, typically a vector of 0.8s.

lines

TRUE, FALSE, or a list that controls the characteristics of lines drawn on a plot, and also whether or not multiple lines should be drawn in the same panel in the plot; if FALSE lines are suppressed; if TRUE default values are used:

multiline: display a multiline plot in each panel; the default is TRUE if there are no standard errors in the "eff" object, FALSE otherwise. For an "effpoly" object multline=TRUE causes all of the response levels to be shown in the same panel rather than in separate panels.

z.var

for linear, generalized linear or mixed models, the index (number) or quoted name of the covariate or factor for which individual lines are to be drawn in each panel of the effect plot. The default is the predictor with the smallest number of levels or values. This argument is only used for multipline plots.

lty

vector of line types, with the default taken from trellis.par.get("superpose.line")$lty, typically a vector of 1s (solid lines).

lwd

vector of line widths, with the default taken from trellis.par.get("superpose.line")$lwd, typically a vector with 2 in the first position followed by 1s.

col

a vector of line colors, with the default taken from from trellis.par.get("superpose.line")$col, used both for lines and for areas in stacked area plots for "effpoly" objects; in the latter case, the default colors for an ordered response are instead generated by sequential_hcl in the colorspace package.

splines

use splines to smooth plotted effect lines; the default is TRUE.

axes

a list with elements x, y, alternating, and grid that control axis limits, ticks, and labels. The x and y elements may themselves be lists.

The x entry is a list with elements named for predictors, with each predictor element itself a list with the following elements:

lab: axis label, defaults to the name of the predictor; may either be a text string or a list with the text label (optionally named label) as its first element and the named element cex as its second element.

lim

a two-element vector giving the axis limits, with the default determined from the data.

ticks

a list with either element at, a vector specifying locations for the ticks marks, or n, the number of tick marks.

transform

transformations to be applied to the horizontal axis of a numeric predictor, in the form of a list of two functions, with element names trans and inverse. The trans function is applied to the values of the predictor, and inverse is used for computing proper axis tick labels. The default is not to transform the predictor axis.

Two additional elements may appear in the x list, and apply to all predictors:

rotate: angle in degrees to rotate tick labels; the default is 0.
rug: display a rug plot showing the marginal distribution of a numeric predictor; the default is TRUE.

The y list contains lab, lim, ticks, and rotate elements (similar to those specified for individual predictors in the x list), along with the additional type, transform, and style elements:

type: for plotting linear or generalized linear models, "rescale" (the default) plots the vertical axis on the link scale (e.g., the logit scale for a logit model) but labels the axis on the response scale (e.g., the probability scale for a logit model); "response" plots and labels the vertical axis on the scale of the response (e.g., the probability scale for a logit model); and "link" plots and labels the vertical axis on the scale of the link (e.g., the logit scale for a logit model). For polytomous logit models, this element is either "probability" or "logit", with the former as the default.
transform: primarily for linear or linear mixed models, this argument is used to apply an arbitrary transformation to the vertical axis. For example, if fitting a linear model with response log(y), then setting transform=exp would plot exp(log(y)) = y on the vertical axis. If the response were 1/y, then use transform=function(yt) 1/yt, since the reciprocal is its own inverse. The transform argument can also be a list of two functions. For example with a response log(y), the specification transform=list(trans=log, inverse=log), type="rescale" will plot in log-scale, but will label tick marks in arithmetic scale; see the example below. The specification transform=list(trans=log, inverse=exp), type="response" is equivalent to transform=exp. When type="response" the lab argument will geneally be used to get a label for the axis that matches the untransformed response. If this argument is used with a generalized linear model or another model with a non-identity link function, the function is applied to the linear predictor, and will probably not be of interest.
style: for polytomous logit models, this element can take on the value "lines" (the default) or "stacked" for line plots or stacked-area plots, respectively.

Other elements:

alternating: if TRUE (the default), the tick labels alternate by panels in multi-panel displays from left to right and top to bottom; if FALSE, tick labels appear at the bottom and on the left.
grid: if TRUE (the default is FALSE), add grid lines to the plot.

confint

specifications to add/remove confidence intervals or regions from a plot, and to set the nominal confidence level.

style: one of "auto", "bars", "lines", "bands", and "none"; the default is "bars" for factors, "bands" for numeric predictors, and "none" for multiline plots; "auto" also produces "bars" for factors and "bands" for numeric predictors, even in multiline plots.

alpha

transparency of confidence bands; the default is 0.15.

col

colors; the default is taken from the line colors.

partial.residuals

specifications concerning the addition of partial residuals to the plot.

plot: display the partial residuals; the default is TRUE if residuals are present in the "eff" object, FALSE otherwise.

fitted

show fitted values as well as residuals; the default is FALSE.

col

color for partial residuals; the default is the second line color.

pch

plotting symbols for partial residuals; the default is 1, a circle.

cex

size of symbols for partial residuals; the default is 1.

smooth

draw a loess smooth of the partial residuals; the default is TRUE.

span

span for the loess smooth; the default is 2/3.

smooth.col

color for the loess smooth; the default is the second line color.

lty

line type for the loess smooth; the default is the first line type, normally 1 (a solid line).

lwd

line width for the loess smooth; the default is the first line width, normally 2.

id

specifications for optional point identification when partial residuals are plotted.

n: number of points to identify; default is 2 if id=TRUE and 0 if id=FALSE. Points are selected based on the Mahalanobis distances of the pairs of x-values and partial residuals from their centroid.

col

color for the point labels; default is the same as the color of the partial residuals.

cex

relative size of text for point labels; default is 0.75.

labels

vector of point labels; the default is the names of the residual vector, which is typically the row names of the data frame to which the model is fit.

lattice

the plots are drawn with the lattice package, generally by the xyplot function. These specifications are passed as arguments to the functions that actually draw the plots.

layout: the layout argument to the lattice function xyplot (or, in some cases densityplot), which is used to draw the effect display; if not specified, the plot will be formatted so that it appears on a single page.

key.args

a key, or legend, is added to the plot if multiline=TRUE. This argument is a list with components that determine the the placement and other characteristics of the key. The default if not set by the user is key.args = list(space="top", columns=2, border=FALSE, fontfamily="serif", cex.title=.80, cex=0.75). If there are more than 6 groups in the plot, columns is set to 3. For stacked-area plots, the default is a one-column key. In addition to the arguments shown explicitly below, any of the arguments listed in the xyplot documentation in the key section can be used.

space: determines the placement of the key outside the plotting area, with default space="above" for above the plot and below its title. Setting space="right" uses space to the right of the plot for the key.

x, y, corner

used to put the key on the graph itself. For example, x=.05, y=.95, corner=c(0,1) will locate the upper-left corner of the key at (.05, .95), thinking of the graph as a unit square.

columns

number of columns in the key. If space="top", columns should be 2, 3 or 4; if space="right", set columns=1.

border

if TRUE draw a border around the key; omit the border if FALSE.

fontfamily

the default is "sans" for the sans-serif font used in the rest of the plot; the alternative is "serif" for a serif font.

cex, cex.title

the default relative size of the font for labels and the title, respectively. To save space set these to be smaller than 1.

strip

a list with three elements: factor.names, which if TRUE, the default, shows conditioning variable names in the panel headers; values, which if TRUE, the default unless partial residuals are plotted, displays conditioning variable values in the panel headers, and cex, the relative size of the text displayed in the strip.

array

a list with elements row, col, nrow, ncol, and more, used to graph an effect as part of an array of plots; row, col, nrow, and ncol are used to compose the split argument and more the more argument to print.trellis. The array argument is automatically set by plot.efflist and will be ignored if used with that function.

Examples

Run this code

# also see examples in ?effect

# plot predictorEffects
mod <- lm(prestige ~ education + log(income)*type + women, Prestige)
plot(predictorEffects(mod, ~ income), axes=list(grid=TRUE))
plot(predictorEffects(mod, ~ income), lines=list(multiline=TRUE),
                                                 axes=list(grid=TRUE))
plot(predictorEffects(mod, ~ type), lines=list(multiline=TRUE),
                                                 axes=list(grid=TRUE),
                                                 confint=list(style="bars"))

mod.cowles <- glm(volunteer ~ sex + neuroticism*extraversion,
                  data=Cowles, family=binomial)
eff.cowles <- allEffects(mod.cowles, xlevels=list(extraversion=seq(0, 24, 6)))
eff.cowles
as.data.frame(eff.cowles[[2]]) # neuroticism*extraversion interaction

plot(eff.cowles, 'sex', axes=list(grid=TRUE,
                                  y=list(lab="Prob(Volunteer)"),
                                  x=list(rotate=90)),
                        lines=list(lty=0))

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))),
     axes=list(y=list(lab="Prob(Volunteer)",
        ticks=list(at=c(.1,.25,.5,.75,.9)))))

# \donttest{
    # change color of the confidence bands to 'black' with .15 transparency
plot(eff.cowles, 'neuroticism:extraversion',
     axes=list(y=list(lab="Prob(Volunteer)",
                      ticks=list(at=c(.1,.25,.5,.75,.9)))),
     confint=list(col="red", alpha=.3))

plot(eff.cowles, 'neuroticism:extraversion',
     lines=list(multiline=TRUE),
     axes=list(y=list(lab="Prob(Volunteer)")),
     lattice=list(key.args = list(x = 0.65, y = 0.99, corner = c(0, 1))))

# use probability scale in place of logit scale, all lines are black.
plot(eff.cowles, 'neuroticism:extraversion',
     lines=list(multiline=TRUE, lty=1:8, col="black"),
     axes=list(y=list(type="response", lab="Prob(Volunteer)")),
     lattice=list(key.args = list(x = 0.65, y = 0.99, corner = c(0, 1))),
     confint=list(style="bands"))

plot(effect('sex:neuroticism:extraversion', mod.cowles,
            xlevels=list(extraversion=seq(0, 24, 6))),
     lines=list(multiline=TRUE))

plot(effect('sex:neuroticism:extraversion', mod.cowles,
            xlevels=list(extraversion=seq(0, 24, 6))),
     lines=list(multiline=TRUE),
     axes=list(y=list(type="response")),
     confint=list(style="bands"),
     lattice=list(key.args = list(x=0.75, y=0.75, corner=c(0, 0))))
# }

if (require(nnet)){
    mod.beps <- multinom(vote ~ age + gender + economic.cond.national +
                             economic.cond.household + Blair + Hague + Kennedy +
                             Europe*political.knowledge, data=BEPS)
    # \donttest{
    plot(effect("Europe*political.knowledge", mod.beps,
                xlevels=list(political.knowledge=0:3)))
    # }

    plot(effect("Europe*political.knowledge", mod.beps,
                xlevels=list(political.knowledge=0:3),
                fixed.predictors=list(given.values=c(gendermale=0.5))),
         axes=list(y=list(style="stacked"), x=list(rug=FALSE), grid=TRUE),
         lines=list(col=c("blue", "red", "orange")))
}

if (require(MASS)){
    mod.wvs <- polr(poverty ~ gender + religion + degree + country*poly(age,3),
                    data=WVS)
    plot(effect("country*poly(age, 3)", mod.wvs))

    # \donttest{
    plot(effect("country*poly(age, 3)", mod.wvs), lines=list(multiline=TRUE))
    plot(effect("country*poly(age, 3)", mod.wvs),
         axes=list(y=list(style="stacked")),
         lines=list(col=c("gray75", "gray50", "gray25")))

    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)
# \donttest{
plot(eff.pres)
plot(eff.pres[1:2])
# }
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))))))
         
mod <- lm(log(prestige) ~ income:type + education, data=Prestige)
p1 <- predictorEffects(mod, ~ income)
# log-scale for response
plot(p1, lines=list(multiline=TRUE)) 
# log-scale, with arithmetic tick marks
plot(p1, lines=list(multiline=TRUE), 
     axes=list(y=list(transform=list(trans=log, inverse = exp), 
                      lab="prestige", type="rescale")))
# arithmetic scale and tick marks, with other arguments
plot(p1, lines=list(multiline=TRUE), grid=TRUE,
     lattice=list(key.args=list(space="right", border=TRUE)),
     axes=list(y=list(transform=exp, lab="prestige")))

Run the code above in your browser using DataLab

Description

Usage

Value

Arguments

Author

Details

See Also

Examples