plotmo {earth} | R Documentation |
Plot the model response when varying one or two predictors while holding all the other predictors at their median values. This function is is intended for models with quantitative responses.
plotmo(object = stop("no 'object' arg"), degree1 = TRUE, degree2 = TRUE, sub.caption = if(do.par) NULL else "", ylim = NULL, clip = TRUE, col.response = 0, pch.response = 1, trace = FALSE, inverse.func = NULL, 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, ...)
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.
|
sub.caption |
Overall caption. The default value is
if(do.par) NULL else "" . Values are:"string" string"" no captionNULL generate a caption from object$call .
|
trace |
Use TRUE to trace operation. 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 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 original data.
Default is TRUE .
|
col.response |
Colour of response values (actually, the response sites in interaction 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.
|
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.
|
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 |
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 typical 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" .
Use 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" .
Use 0 for no colour.
|
col.image |
Colours of image plot. Default is grey(0:9/10) .
The default excludes 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 .
Use 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
let this function choose the rotation (it rotates 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.
Use 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.
|
Plotmo
is a general purpose model plotting function
(but comes with the earth
package).
Limitations
NAs are not yet allowed.
To prevent confusing error messages from plotmo
,
a safe stategy 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.
Variable names containing $ are not supported.
If the predicted response (from plotmo
's call to
predict
) has multiple columns then only the first column is used.
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.
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 components
(which are searched for in the order given):
a) $call$formula
(formula
is required for degree2
plots),
or $call$x
with named columns, or $x
with named columns.
b) $call$formula
, or $call$y
, or $y
.
Extending plotmo
Plotmo
calls the following generic functions, all defined in
the file plotmo.R
:
plotmo.prolog
get.x
get.y
plotmo.predict
(the default simply calls 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 examples below and see the source comments for details.
Stephen Milborrow. This is an early release and users are encouraged to send feedback — use milboATsonicPERIODnet.
termplot
,
plot.earth
,
plot.earth.models
data(ozone1) a <- earth(O3 ~ ., data = ozone1, degree = 2) plotmo(a) # example with some arguments: # plotmo(a, sub.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)