plotmo {earth}R Documentation

Plot the predicted model response

Description

Plot the predicted model response when varying one or two predictors while holding all the other predictors constant.

Usage

plotmo(object = stop("no 'object' arg"),
       degree1 = TRUE, degree2 = TRUE, ycolumn = 1,
       caption = if(do.par) NULL else "",
       ylim = NULL, clip = TRUE, inverse.func = NULL,
       col.response = 0, pch.response = 1,
       trace = FALSE, grid.func = median,
       ndegree1 = 500, lty.degree1 = 1, col.degree1 = 1,
       se = 0, col.shade = "lightblue", col.se = 0, lty.se = 2,
       func = NULL, col.func = "pink", pch.func = 20, nrug = 0,
       type2 = "persp", ngrid = 20,
       col.persp = "lightblue", col.image = grey(0:9/10),
       do.par = TRUE, main = NULL, theta = NA, phi = 30, shade = 0.5,
       ticktype = "simple", xlab = "", ylab = "", cex = NULL, ...)

Arguments

To start off, look at the arguments object, degree1, degree2, ylim, clip, and se.

object Model object. This is the only required argument.
degree1 Index vector specifying main effect plots to include. Default is TRUE, meaning all. Perhaps the easiest way to use this argument (and degree2) is to first plot all figures to see how the figures are numbered, then replot, using degree1 to select the figures you want.
degree2 Index vector specifying interaction plots to include. Default is TRUE, meaning all.
ycolumn Specify which column of the response to plot if the model has multiple responses. Default is 1.
caption Overall caption. The default value is if(do.par) NULL else "". Values are:
"string" string
"" no caption
NULL generate a caption from object$call and the response name.
trace Set to TRUE to trace operation. Useful for tracking down error messages. Default is FALSE.
ylim Values are:

NULL (default) all y axes have same limits (where "y" is actually "z" on degree2 plots). The limits are the min and max values of y across all (degree1 and degree2) plots. If col.response!=0 then the original response is included in the min and max calculation.

NA each graph has its own y limits.

c(ymin,ymax) all graphs have the specified y limits.

clip Plot only values that are in the range of the response of the original data. Default is TRUE.
inverse.func Function applied to the predicted response before plotting. Default is NULL, meaning do not apply a function. For example, you could use inverse.func=exp if your model formula is log(y)~x. Note, however, that is usually unnecessary to use inverse.func for models such as glm with family=binomial, because the plotted response is already a probability.
col.response Colour of response values (actually, the response sites in degree2 plots). Here ‘response’ refers to the original data used to build the model. Default is 0, meaning don't plot the response. Ignored by persp plots.
pch.response Plot character for col.response. Default is 1.
grid.func Function applied to x columns to calculate the values for numeric predictors not on the axes. (For factor predictors the first level is always used). Default is median. Examples:
plotmo(a, grid.func = mean) # mean instead of median
grid.func <- function(x) quantile(x)[2]   # 25% quantile
plotmo(a, grid.func = grid.func)
The following arguments are for degree1 (main effect) plots
ndegree1 Maximum number of points in each degree1 plot. Default is 500. Special value -1 means use nrow(x).
lty.degree1 Line type of degree 1 plots. Default is 1.
col.degree1 Colour of degree 1 plots. Default is 1.
nrug Number of points in (jittered) rug. Default is 0 meaning no rug. Special value -1 for all i.e. nrow(x).
se Draw standard error bands at plus and minus se times the pointwise standard errors. Default is 0, meaning no standard error bands. A common value is 2. The predict method for object must be callable with se.fit=TRUE (examples are predict.lm but not predict.earth).
col.shade Colour of se shading. Default is "lightblue". Set to 0 for no shading.
col.se Colour of se lines. Default is 0 meaning no lines just shading.
lty.se Line type of se lines. Default is 2.
func Superimpose func(x) if func is not NULL. Default is NULL. This is useful if you are comparing the model to a known function. Note that func is called with a single argument which is a dataframe with columns in the same order as the predictors in the formula or x used to build the model. Set trace=TRUE to see the column names and first few rows of this dataframe.
col.func Colour of func points. Default is "pink".
pch.func Plot character for func points. Default is 20.

The following arguments are for degree2 plots
type2 Degree2 plot type. One of "persp" (default), "contour", or "image".
col.persp Colour of persp surface. Default is "lightblue". Set to 0 for no colour.
col.image Colours of image plot. Default is grey(0:9/10). The default excludes grey(1) because that is the "colour" of clipped values, see clip.
ngrid Grid side length for degree2 plots. Default is 20.

The following settings are related to par() and are included so you can override the defaults.
do.par Call par() for global settings as appropriate. Default is TRUE. Set to FALSE if you want to append figures to an existing plot.
main Title of each plot. Default is NULL, meaning generate figure headings automatically.
theta Rotation argument for persp. Default is NA, meaning automatically rotate each graph so the highest corner is furthest away.
phi Phi argument for persp. Default is 30.
shade Shade arg for persp. Default is 0.5.
ticktype Ticks on persp plot. One of simple or detailed. Default is "simple".
xlab Horizontal axis label on degree1 plots (for degree2 plots the abscissa labels are always the predictor names). Default is "", meaning none, which gives more plottable area. Set to NULL to use the predictor names as labels. If you use NULL, you may want to set main="" to avoid redundant labeling.
ylab Vertical axis label. Default is "", meaning none, which gives more plottable area.
cex Character expansion.
... Extra arguments passed to plotting functions called by plotmo. Using arguments here may cause warnings which can often be safely ignored.

Details

Plotmo is a general purpose model plotting function (but comes with the earth package). It is intended for models with quantitative responses.

Limitations

NAs are not yet allowed. To prevent confusing error messages from plotmo, a safe strategy is to build your model with na.action=na.fail before calling plotmo.

Weights are currently ignored, with a warning.

Factors are not plotted in degree2 plots.

To avoid confusing error messages from plotmo, keep the original formula you used to build the model simple. By default (i.e. when using get.x.default and get.pairs.default), plotmo parses the input formula using gsub. This crude approach is not infallible but works for the common formulae. It determines which predictors are paired by looking for forms such as "x1:x2" or "x1*x2" in the model formula.

Variable names containing $ are not supported. The work around is to build the model using temporary variables or to use attach.

Plotmo can get confused by predictors in formulae which use indexing, such as x[,3]. The symptom is usually a message along the lines
Error in model.frame: invalid type (list) for variable 'x[,3]'.

A mesage like
Warning in model.frame.default: 'newdata' had 50 rows but variable(s) found have 31 rows
means that model.frame.default cannot find all the variables in the data frame created by plotmo.

Details of Operation

Let's say the model object has three predictors, x1, x2, and x3 (all numeric) and plotmo is about to plot the degree1 plot for x2. Plotmo first builds an input matrix with ndegree1 rows and with column names x1, x2, and x3. It sets all entries for the x1 column to x1's median value (actually, the value returned by grid.func applied to x1). Likewise for the x3 column. It sets the x2 column to an equally spaced sequence of values from min(x2) to max(x2). Finally, it calls predict(type="response") with the newly created input matrix, and plots the predicted values against the sequence of x2 values.

Operation is similar for degree2 plots: all columns of the input matrix for predict are set to their medians except for the columns of the two predictors being plotted.

Note that plotmo calls predict with new data and type="response", whereas termplot calls predict with type="terms".

Minimum Requirements

Plotmo requires the following of the model object. These requirements are for default operation, which can be changed as described in the next section.

1) object must have a predict method that supports type=response.

2) for standard error bands (see the se argument), object must have a predict method that can be called with se.fit=TRUE.

3) object must have the following two components (which are searched for in the order given for each):

Extending plotmo

Plotmo calls the following generic functions, all defined in the file plotmo.R:

plotmo.prolog
get.x
get.y
plotmo.predict
get.singles
get.pairs

Thus plotmo can be extended by writing new method functions, although the default functions may suffice for your object's class. See the source comments for details.

FAQ

I want to add lines or points to a plot created by plotmo. and am having trouble getting my axis scaling right. Help?

Use do.par=FALSE. With do.par=FALSE, the axis scales match the axis labels. With do.par=TRUE, plot.earth restores the par parameters and axis scales to what they were before calling plot.earth. This usually means that the x- and y-axis scales are both 0 to 1.

Author(s)

Stephen Milborrow. Users are encouraged to send feedback — use milboATsonicPERIODnet http://www.milbo.users.sonic.net.

See Also

termplot, plot.earth, plot.earth.models

Examples

data(ozone1)
a <- earth(O3 ~ ., data = ozone1, degree = 2)
plotmo(a)

# example with some arguments:
# plotmo(a, caption = "example", ylim = NULL, degree1 = c(1,2,4),
#   degree2 = 4, col.response = 3, clip = FALSE, ticktype = "d", theta = -30)

# examples using functions other than earth:
#
# plotmo(lm(O3 ~ log(temp) + humidity*temp, data=ozone1), se=2)
#
# library(gam)
# data(airquality)
# airquality <- na.omit(airquality)  # plotmo doesn't know how to deal with NAs
# plotmo(gam(Ozone^(1/3) ~ lo(Solar.R) + lo(Wind, Temp), data = airquality))
#
# library(mgcv)
# plotmo(gam(O3 ~ s(doy) + s(humidity,temp), data=ozone1), se=2, ylim=NA)

[Package earth version 1.3-4 Index]