summary, print, plot, and [ methods for eff, effpoly,
efflist, and mlm.efflist objects.
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), multiline=is.null(x$se), rug=TRUE,
xlab, ylab, main=paste(effect, "effect plot"),
colors=palette(), symbols=1:length(colors), lines=1:length(colors),
cex=1.5, lwd=2, ylim, xlim=NULL,
factor.names=TRUE, ci.style, band.transparency=0.15, band.colors=colors,
type=c("rescale", "response", "link"), ticks=list(at=NULL, n=5),
alternating=TRUE, rotx=0, roty=0, grid=FALSE, layout, rescale.axis,
transform.x=NULL, ticks.x=NULL,
key.args=NULL,
row=1, col=1, nrow=1, ncol=1, more=FALSE,
use.splines=TRUE, partial.residuals=TRUE, show.fitted=FALSE,
residuals.color="blue", residuals.pch=1, residuals.cex=1,
smooth.residuals=TRUE, residuals.smooth.color=residuals.color, span=2/3, ...)
## S3 method for class 'effpoly'
plot(x,
type=c("probability", "logit"),
x.var=which.max(levels),
rug=TRUE,
xlab,
ylab=paste(x$response, " (", type, ")", sep=""),
main=paste(effect, "effect plot"),
colors, symbols, lines, cex=1.5, lwd=2,
factor.names=TRUE, ci.style, band.colors, band.transparency=0.3,
style=c("lines", "stacked"),
confint=(style == "lines" && !is.null(x$confidence.level)),
transform.x=NULL, ticks.x=NULL, xlim=NULL,
ylim, rotx=0, alternating=TRUE, roty=0, grid=FALSE,
layout, key.args=NULL,
row=1, col=1, nrow=1, ncol=1, more=FALSE, use.splines=TRUE, ...)
## S3 method for class 'efflist'
plot(x, selection, rows, cols, ask=FALSE, graphics=TRUE, ...)
## S3 method for class 'mlm.efflist'
plot(x, ...)
setStrip(bg=3, fg="black", clip=c("off", "on"))
restoreStrip(saved)
## S3 method for class 'efflist'
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 plotting linear or genealized linearized 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 argument takes either "probability"
or "logit", with the former as the default.
rescale.axis
this argument is deprecated — use the type argument instead. Setting
rescale.axis=TRUE is equivalent to type="rescale"; setting rescale.axis=FALSE
is equivalent to type="response". If specified, rescale.axis will override type.
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 if multiline = TRUE.
multiline
for linear, generalized linear or mixed models,
if TRUE, each panel of the display represents combinations
of values of two predictors, with one predictor (corresponding to x.var)
on the horzontal axis, and the other (corresponding to z.var) used to define
lines in the graph; defaults to TRUE if there are no standard errors in
the object being plotted, and FALSE otherwise.
confint
plot point-wise confidence bands around fitted effects (for
multinomial and proportional-odds logit models); defaults to TRUE,
in which case separate panels are used for different response levels.
rug
if TRUE, the default, a rug plot is shown giving the marginal
distribution of the predictor on the horizontal axis, if this predictor is
a covariate. The rug plot is suppressed if partial residuals are plotted.
xlab
the label for the horizontal axis of the effect plot; if missing, the
function will use the name of the predictor on the horizontal axis.
ylab
the label for the vertical axis of the effect plot; the default is
constructed from the name of the
response variable for the model from which the effect was computed.
main
the title for the plot, printed at the top; the default title is constructed from the
name of the effect.
colors
colors[1] is used to plot effects, colors[2] to plot
confidence limits when ci.style is not equal to "bands". In a mulitline plot, the successive colors correspond
to the levels of the z.var covariate or factor. In a stacked plot or a plot
without confidence bands for a
multinomial or proportional-odds logit model, the successive colors
correspond to the levels of the response factor. In all but stacked plots,
colors defaults to palette(). If colors is
shorter than the number of levels, then it is recycled, so colors="black"
will use black for all levels.
For stacked multinomial-logit plots,
colors defaults to rainbow_hcl(levels), where levels is
the number of levels of the response variable; for stacked proportional-odds model
plots, colors defautls to sequential_hcl(levels). colors
does not recycle for stacked plots.
Warning: This argument
cannot be abbreviated to col, which is used for a different
purpose (see below).
symbols, lines
corresponding to the levels of the z.var covariate
or factor on a multiline plot, or to the successive levels of the response factor
in a line plot for a polytomous logit model.
These arguments are used only if multiline = TRUE
or for polytomous logit models where the effects are plotted without confidence bands;
in these cases a legend is drawn at the top of the display. If these arguments are
too short they are recycled.
cex
character expansion for plotted symbols; default is 1.5.
lwd
line width for fitted lines.
ylim
2-element vector containing the lower and upper limits of the vertical axes;
if NULL, the default, then the vertical axes are scaled from the data.
Warning: By default, the vertical axis for a generalized linear model is on the
scale of the linear predictor (e.g., the logit scale for a logit model), not on the scale
of the response (e.g., the probability scale for a logit model), although the tick labels
are by default on the scale of the response. Consequently, the axis limits should be on the scale
of the linear predictor. E.g., for a logit model with axes to run from probabilities of 0.1 to
0.8, you can specify log(c(0.1, 0.8)/c(0.9, 0.2)).
xlim
a named list of 2-element vectors, with the names corresponding to numeric
predictors; if a numeric predictor is in the list, then when it appears on the horizontal
axis, the axis limits will be taken from the corresponding vector; if a predictor is
not in the list, or if the argument is NULL (the default), then the horizontal
axis limits are computed from the data.
factor.names
a logical value, default TRUE, that controls the inclusion of
factor names in conditioning-variable labels.
ci.style
confidence bounds can be indicated using error bars, using lines or confidence bands,
depending on the plot type.
For single line plots the default is "bars" for factors and "bands"
for variates. Style "lines" can also be used for either of these.
For multiline plots, the default is "none" for no
confidence bounds, but style "bars" or "bands" can also be used. For a variate
the option "bars" displays the error bars at
each of the levels points for which the horizontal variable was evaluated.
band.colors
A vector of colors for the color of the confidence band with ci.style="bands".
The default is band.colors=colors. For plots with one line, the choice, setting
band.colors="red" produces a pleasing result, even if color provides no additional
information in this case. If this argument is too short it is recycled.
band.transparency
For ci.style="bands", the alpha transparency of the fill color. Not all
graphic devices support transparency.
style
(for multinomial or proportional-odds logit models) "lines" (the default
for a line plot, or "stacked" for a stacked-bar or stacked-area plot. In the latter
case only fitted probabilities may be plotted and confidence envelopes cannot be shown.
ticks
a two-item list controlling the placement of tick marks on the vertical axis,
with elements at and n. If at=NULL (the default), the program
attempts to find ‘nice’ locations for the ticks, and the value of n (default,
5) gives the
approximate number of tick marks desired; if at is non-NULL, then the
value of n is ignored.
Warning: For a generalized linear model, by default the vertical axis is on the
scale of the linear predictor (e.g., the logit scale for a logit model),
but labels for tick marks are displayed on the scale of
the response (e.g., the probability scale for a logit model); at should be given
on the response scale (e.g., the probability scale for a logit model).
ticks.x
a named list of two-item lists controlling the placement of tick marks
on the horizontal axis. Each list element is named for a numeric predictor in the model,
and each sublist has elements at or n are for the ticks argument.
If a predictor doesn't appear in the list, or if ticks.x is NULL (the default),
then the tick marks are computed by the function.
transform.x
transformations to be applied to the horizontal axis, in the form of a named list,
each of whose elements is itself a list of two functions, with sublist element names trans and inverse.
The names of the list elements are numeric predictors in the model whose axes are to be transformed; the
trans function is applied to the values of the predictor, and inverse is used for computing
proper axis tick labels. If a numeric predictor is missing from transform.x then its axis is not
transformed; if the argument is NULL (the default), then no predictor axes are transformed.
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.
rotx, roty
rotation angles for the horizontal and vertical tick marks,
respectively. Default is 0.
grid
if TRUE, add grid lines to the plot. Default is FALSE.
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
additional arguments to be passed to the key trellis argument to
xyplot or densityplot,
e.g., to position the key (legend) in the plotting region; may also be used to modify
the default behavior of the key.
row, col, nrow, ncol, more
These arguments are 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.
Normally these arguments are not set by the user, but by plot.efflist.
Warning: Note that col is not used to specify colors;
use colors instead (see above).
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.
use.splines
If TRUE, the default, then any lines drawn when the horizontal
axis is not a factor use interpolating splines computed by the spline
function. If FALSE, then linear interpoliation is used. This argument is ignored if
the horizontal axis is a factor.
partial.residuals
If TRUE, the default, plot partial residuals if residuals are saved in the effect object — see Effect.
smooth.residuals
whether to show a loess smooth of the partial residuals, if
they are present; the default is TRUE. For a non-Gaussian glm model,
a non-robust loess smooth is used; for a lm model or a Gaussian glm model,
a robust smooth is employed.
span
of the xyplot smoother to be applied to partial residuals;
the default is 2/3.
show.fitted
if TRUE and partial residuals are present in the effect object, also plot the partial
fitted values (which will be shown as filled circles); the default is FALSE.
residuals.color
color for plotting partial residuals (default "blue").
residuals.smooth.color
color for plotting the smooth of the partial residuals; the default is the residuals.color.
residuals.pch
plotting symbol for partial residuals (default 1, open circles).
residuals.cex
character expansion (relative size) for symbols plotting partial residuals (default is 1).
bg
if a single numeric value (the default is 3), the color of the strips at the tops
of lattice panels are set to gray scale, with the number of graditions, if there is more than one
conditioning variable, corresponding to the value given (which will be rounded to a whole number).
This argument can also be a vector of colors, specified in any manner recognized in R (e.g, by name).
fg
foreground color or colors for the strips at the top of lattice panels (the default is
"black"); can be a single value or a vector of values of the same length as bg.
clip
"off" or "on", determines whether or not conditioning values in the strips
at the top of lattice panels are clipped on the left and right. The normal lattice default is
"on"; the default in setStrip is "off", allowing the lines representing numeric
conditioning values to be displayed more clearly at the extreme left and right of strips.
saved
a set of lattice strip specifications returned by setStrip.
...
arguments to be passed down.
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 the argument
lty=0 to the call to plot (see the examples).
In a polytomous (multinomial or proportional-odds) logit model, by default effects are plotted on the
probability scale; they may be alternatively plotted on the scale of the individual-level logits.
The setStrip and restoreStrip functions modify the strips that appear in subsequent
lattice plots, including those produced by functions in the effects package. The default call
setStrip() provides monochrome (rather than the lattice-default colored) strips with up to 3
gray-scale values corresponding to 3 conditioning variables; clipping at the left and right of strips
is also turned off by default by setStrip. restoreStrip may be used to reset
lattice strips to previously saved parameters returned by setStrip.
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 setStrip function invisibly returns a list that can supply the argument of the
restoreStrip function to restore the previous lattice strip specification.
The [ method for "efflist" objects is used to subset an "efflist" object and returns an object of the same class.