R: Summarizing, Printing, and Plotting Effects

summary.eff {effects}

R Documentation

Summarizing, Printing, and Plotting Effects

Description

summary, print, plot, and [ methods for eff, effpoly, efflist, and mlm.efflist objects. The plot arguments were substantially changed in mid-2017.

Usage

## S3 method for class 'eff'
print(x, type=c("response", "link"), ...)
## S3 method for class 'effpoly'
print(x, type=c("probability", "logits"), ...)
## S3 method for class 'efflatent'
print(x, ...)
## S3 method for class 'efflist'
print(x, ...)
## S3 method for class 'mlm.efflist'
print(x, ...)
## S3 method for class 'summary.eff'
print(x, ...)
## S3 method for class 'eff'
summary(object, type=c("response", "link"), ...)
## S3 method for class 'effpoly'
summary(object, type=c("probability", "logits"), ...)
## S3 method for class 'efflatent'
summary(object, ...)
## S3 method for class 'efflist'
summary(object, ...)
## S3 method for class 'mlm.efflist'
summary(object, ...)
## S3 method for class 'eff'
plot(x, x.var, z.var=which.min(levels),
    main=paste(effect, "effect plot"),
    symbols=TRUE, lines=TRUE, axes, confint,
    partial.residuals, id, lattice, ...,
    # legacy arguments:
    multiline, 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 class '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 class 'efflist'
plot(x, selection, rows, cols, ask=FALSE, graphics=TRUE, lattice, ...)
## S3 method for class 'mlm.efflist'
plot(x, ...)

Arguments

`x`	an object of class `"eff"`, `"effpoly"`, `"efflist"`, `"mlm.efflist"`, or `"summary.eff"`, as appropriate.
`object`	an object of class `"eff"`, `"effpoly"`, `"efflist"`, or `"mlm.efflist"`, as appropriate.
`type`	for printing or summarizing linear and generalized linear models, if `"response"` (the default), effects are printed on the scale of the response variable; if `"link"`, effects are printed on the scale of the linear predictor. For polytomous logit models, this argument takes either `"probability"` or `"logit"`, with the former as the default. The `type` argument is also a legacy argument for `plot` methods.
`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.
`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 — see the `lines` argument.
`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.
`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 effect list 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.
`multiline, 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, 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.

Details

In a generalized linear model, by default, the print and summary methods for eff objects print the computed effects on the scale of the response variable using the inverse of the link function. In a logit model, for example, this means that the effects are expressed on the probability scale.

By default, 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.

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.

Detailed Argument Descriptions

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

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 two elements: factor.names, which if TRUE, the default, shows conditioning variable names in the panel headers; and values, which if TRUE, the default unless partial residuals are plotted, displays conditioning variable values in the panel headers.

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 by plot.efflist and will be ignored if used with that function.

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.

Author(s)

John Fox jfox@mcmaster.ca and Jangman Hong.

Examples

# also see examples in ?effect

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(y=list(lab="Prob(Volunteer)"),
                                  x=list(rotate=90)),
     lines=list(lty=0), grid=TRUE)

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


    # 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)
    
    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))

    
    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)

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

[Package effects version 4.0-1 Index]