R: Surface plot(s) of a fitted linear model

contour.lm {rsm} | R Documentation

## Surface plot(s) of a fitted linear model

### Description

`contour`, `image`, and `persp` methods that display the fitted surface for an `lm` object involving two or more numerical predictors.

### Usage

    ## S3 method for class 'lm'
    contour(x, form, at, bounds, zlim, xlabs, hook,
        plot.it = TRUE, atpos = 1, decode = TRUE, image = FALSE,
        img.col = terrain.colors(50), ...)

    ## S3 method for class 'lm'
    image(x, form, at, bounds, zlim, xlabs, hook,
        atpos = 1, decode = TRUE, ...)

    ## S3 method for class 'lm'
    persp(x, form, at, bounds, zlim, zlab, xlabs,
        col = "white", contours = NULL, hook, atpos = 3, decode = TRUE,
        theta = -25, phi = 20, r = 4, border = NULL, box = TRUE,
        ticktype = "detailed", ...)

### Arguments

`x` | A `lm` object.
`form` | A formula, or a list of formulas.
`at` | Optional named list of fixed values to use for surface slices. For example, if the predictor variables are `x1`, `x2`, and `x3`, the contour plot of `x2` versus `x1` would be based on the fitted surface sliced at the `x3` value specified in `at`; the contour plot of `x3` versus `x1` would be sliced at the `at` value for `x2`; etc. If not provided, `at` defaults to the mean value of each numeric variable.
`bounds` | Optional named list of bounds or grid values to use for the variables having the same names. See details.
`zlim` | `zlim` setting passed to parent methods `contour`, `image`, or `persp`. The same `zlim` is used in all plots when several are produced. If not provided, the range of values across all plotted surfaces is used.
`zlab` | Optional label for the vertical axis.
`xlabs` | Alternate labels for predictor axes (see Details).
`hook` | Optional list that can contain functions `pre.plot` and `post.plot`. May be used to add annotations or to re-route the graphs to separate files (see Details).
`atpos` | Determines where `at` values are displayed. A value of 1 (or 2) displays it as part of the x (or y) axis label. A value of 3 displays it as a subtitle below the plot. A value of 0 suppresses it. Any other nonzero value will cause the label to be generated but not displayed; it can be accessed via a `hook` function.
`decode` | This has an effect only if `x` is an `rsm` object or other model object that supports `coded.data`. In such cases, if `decode` is `TRUE`, the coordinate axes are transformed to their decoded values.
`image` | Set to `TRUE` if you want an image plot overlaid by contours.
`img.col` | Color map to use when `image=TRUE`.
`plot.it` | If `TRUE`, no plot is produced, just the return value.
`col` | Color or colors used for facets in the perspective plot (see details).
`contours` | If non-`NULL`, specifications for added contour lines in perspective plot.
`theta, phi` | Viewing angles passed to `persp` (different defaults).
`r` | Viewing distance passed to `persp` (different default).
`border, box` | Options passed to `persp`.
`ticktype` | Option passed to `persp` (different default).
`...` | Additional arguments passed to `contour`, `image`, or `persp`. Note, however, that a `ylab` is ignored, with a message to Use `xlabs` instead.

### Details

`form` may be a single formula or a list of formulas. A simple formula like `x2 ~ x1` will produce a contour plot of the fitted regression surface for combinations of `x2` (vertical axis) and `x1` (horizontal axis). A list of several such simple formulas will produce a contour plot for each formula. A two-sided formula produces contour plots for each left-hand variable versus each right-hand variable (except when they are the same); for example, `x1+x3 ~ x2+x3` is equivalent to `list(x1~x2, x3~x2, x1~x3)`. A one-sided formula produces contour plots for each pair of variables. For example, `~ x1+x2+x3` is equivalent to `list(x2~x1, x3~x1, x3~x2)`.

For any variables not in the `bounds` argument, a grid of 26 equally-spaced values in the observed range of that variable is used. If you specify a vector of length 2, it is interpreted as the desired range for that variable and a grid of 26 equally-spaced points is generated. If it is a vector of length 3, the first two elements are used as the range, and the third as the number of grid points. If it is a vector of length 4 or more, those values are used directly as the grid values.

The results are based on the predicted values of the linear model over the specified grid. If there are `factor`s among the predictors, the predictions are made over all levels (or combinations of levels) of those factors, and then averaged together. (However, the user may include factors in `at` to restrict this behavior.)

By default, the predictor axes are labeled using the variable names in `form`, unless `x` is an `rsm` or other object that supports `coded.data`, in which case either the decoded variable names or the variable-coding formulas are used to generate axis labels, depending on whether `decode` is `TRUE` or `FALSE`. These axis labels are replaced by the entries in `xlabs` if provided. One must be careful using this to make sure that the names are mapped correctly. The entries in `xlabs` should match the respective unique variable names in `form`, after sorting them in (case-insensitive) alphabetical order (not necessarily in order of appearance). Note that if `form` is changed, it may also be necessary to change `xlabs`.

Please note that with models fitted to coded data, coded values should be used in `at` or `bounds`, regardless of whether `decode` is `TRUE` or `FALSE`. However, any elements that are added afterward via `points`, `lines`, etc., must be specified in terms of whatever coordinate system is present in the plots.

In `persp`, contour lines may be added via the `contours` argument. It may be a boolean or character value, or a `list`. If boolean and `TRUE`, default black contour lines are added to the bottom surface of the box. Character values of `"top"`, `"bottom"` add black contour lines to the specified surface of the box. `contours = "colors"` puts contour lines on the bottom using the same colors as those at the same height on the surface. Other character values of `contours` are taken to be the desired color of the contour lines, plotted at the bottom. If `contours` is a named `list`, its elements (all are optional) are used as follows:

`z`

  Height where the contour lines are plotted. May be `"bottom"` (default), `"top"`, or a numeric value.

`col`

  Color of the lines. If not specified, they will be black. May be integer color values, color names, or `"colors"` to match the surface colors.

`lwd`

  Line width; default is 1.

Since these functions often produce several plots, the `hook` argument is provided if special setups or annotations are needed for each plot. It should be a list that defines one or both of the functions `pre.plot` and `post.plot`. Both of these functions have one argument, the character vector `labs` for that plot (see Value documentation).

Additional examples and discussion of these plotting functions is available via `vignette("rsm-plots")`.

### Value

A `list` containing information that is plotted. Each list item is itself a `list` with the following components:

`x, y` | The values used for the x and y axes
`z` | The matrix of fitted response values
`labs` | Character vector of length 5: Elements 1 and 2 are the x and y axis labels, elements 3 and 4 are their original variable names, and element 5 is the slice label (empty if `atpos` is 0)
`zlim` | The computed or provided `zlim` values
`transf` | (`persp` only) The 3D transformation for `trans3d`

### Author(s)

Russell V. Lenth

### References

Lenth RV (2009) “Response-Surface Methods in R, Using rsm”, Journal of Statistical Software, 32(7), 1–17. http://www.jstatsoft.org/v32/i07/.

### See Also

`contour`

### Examples

    library (rsm)
    heli.rsm <- rsm (ave ~ block + SO(x1, x2, x3, x4), data = heli)

    # Plain contour plots
    par (mfrow = c (2,3))
    contour (heli.rsm, ~x1+x2+x3+x4, at = xs(heli.rsm))

    # Same but with image overlay, slices at origin and block 2,
    # and no slice labeling
    contour (heli.rsm, ~x1+x2+x3+x4, at = list(block="2"),
        atpos = 0, image = TRUE)

    # Default perspective views
    persp (heli.rsm, ~x1+x2+x3+x4, at = xs(heli.rsm))

    # Same plots, souped-up with facet coloring and axis labeling
    persp (heli.rsm, ~x1+x2+x3+x4, at = xs(heli.rsm),
        contours = "col", col = rainbow(40), zlab = "Flight time",
      xlabs = c("Wing area", "Wing length", "Body width", "Body length"))

    ## Not run:
    ### Hints for creating graphics files for use in publications...

    # Save perspective plots in one PDF file (will be six pages long)
    pdf(file = "heli-plots.pdf")
    persp (heli.rsm, ~x1+x2+x3+x4, at = xs(heli.rsm))
    dev.off()

    # Save perspective plots in six separate PNG files
    png.hook = list(
        pre.plot = function(lab)
            png(file = paste(lab[3], lab[4], ".png", sep = "")),
        post.plot = function(lab)
            dev.off())
    persp (heli.rsm, ~x1+x2+x3+x4, at = xs(heli.rsm), hook = png.hook)

    ## End(Not run)

[Package rsm version 2.9 Index]