plotmo                 package:earth                 R Documentation

_P_l_o_t _M_o_d_e_l _R_e_s_p_o_n_s_e

_D_e_s_c_r_i_p_t_i_o_n:

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

_U_s_a_g_e:

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

_A_r_g_u_m_e_n_t_s:

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

_D_e_t_a_i_l_s:

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

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

     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) '$x' with named columns, or '$call$formula' ('formula' is
     required for 'degree2' plots), or '$call$x' with named columns

     b) '$y', or '$call$formula', or '$call$y'.

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

_A_u_t_h_o_r(_s):

     Stephen Milborrow. This is an early release and users are
     encouraged to send feedback - use milboATsonicPERIODnet.

_S_e_e _A_l_s_o:

     'termplot', 'plot.earth', 'plot.earth.models'

_E_x_a_m_p_l_e_s:

     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)

