contour               package:graphics               R Documentation

Display Contours

Description:

     Create a contour plot, or add contour lines to an existing plot.

Usage:

     contour(x, ...)
     ## Default S3 method:
     contour(x = seq(0, 1, len = nrow(z)), y = seq(0, 1, len = ncol(z)),
             z,
             nlevels = 10, levels = pretty(zlim, nlevels), labels = NULL,
             xlim = range(x, finite = TRUE),
             ylim = range(y, finite = TRUE),
             zlim = range(z, finite = TRUE),
             labcex = 0.6, drawlabels = TRUE, method = "flattest",
             vfont = c("sans serif", "plain"),
             axes = TRUE, frame.plot = axes,
             col = par("fg"), lty = par("lty"), lwd = par("lwd"),
             add = FALSE, ...)
     contourLines(x = seq(0, 1, len = nrow(z)), y = seq(0, 1, len = ncol(z)),
                  z, nlevels = 10, levels = pretty(range(z, na.rm=TRUE), nlevels))

Arguments:

     x,y: locations of grid lines at which the values in 'z' are
          measured.  These must be in ascending order.  By default,
          equally spaced values from 0 to 1 are used.  If 'x' is a
          'list', its components 'x$x' and 'x$y' are used for 'x' and
          'y', respectively. If the list has component 'z' this is used
          for 'z'.

       z: a matrix containing the values to be plotted ('NA's are
          allowed).  Note that 'x' can be used instead of 'z' for
          convenience.

 nlevels: number of contour levels desired *iff* 'levels' is not
          supplied.

  levels: numeric vector of levels at which to draw contour lines.

  labels: a vector giving the labels for the contour lines.  If 'NULL'
          then the levels are used as labels.

  labcex: 'cex' for contour labelling.

drawlabels: logical.  Contours are labelled if 'TRUE'.

  method: character string specifying where the labels will be located.
          Possible values are '"simple"', '"edge"' and '"flattest"'
          (the default). See the Details section.

   vfont: if a character vector of length 2 is specified, then Hershey
          vector fonts are used for the contour labels. The first
          element of the vector selects a typeface and the second
          element selects a fontindex (see 'text' for more
          information).

xlim, ylim, zlim: x-, y- and z-limits for the plot.

axes, frame.plot: logical indicating whether axes or a box should be
          drawn, see 'plot.default'.

     col: color for the lines drawn.

     lty: line type for the lines drawn.

     lwd: line width for the lines drawn.

     add: logical. If 'TRUE', add to a current plot.

     ...: additional graphical parameters (see 'par'). The plot aspect
          ratio 'asp' (see 'plot.window')  and the arguments to 'title'
          may also be supplied.

Details:

     'contour' is a generic function with only a default method in base
     R.

     'contourLines' draws nothing, but returns a set of contour lines.

     There is currently no documentation about the algorithm. The
     source code is in '$R_HOME/src/main/plot3d.c'.

     The methods for positioning the labels on contours are '"simple"'
     (draw at the edge of the plot, overlaying the contour line),
     '"edge"' (draw at the edge of the plot, embedded in the contour
     line, with no labels overlapping) and '"flattest"' (draw on the
     flattest section of the contour, embedded in the contour line,
     with no labels overlapping).  The second and third may not draw a
     label on every contour line.

     For information about vector fonts, see the help for 'text' and
     'Hershey'.

Value:

     'contourLines' returns a list of contours. Each contour is a list
     with elements: 

  level : The contour level.

      x : The x-coordinates of the contour.

      y : The y-coordinates of the contour.

References:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S
     Language_. Wadsworth & Brooks/Cole.

See Also:

     'filled.contour' for "color-filled" contours, 'image' and the
     graphics demo which can be invoked as 'demo(graphics)'.

Examples:

     x <- -6:16
     op <- par(mfrow = c(2, 2))
     contour(outer(x, x), method = "edge", vfont = c("sans serif", "plain"))
     z <- outer(x, sqrt(abs(x)), FUN = "/")
     ## Should not be necessary:
     z[!is.finite(z)] <- NA
     image(x, x, z)
     contour(x, x, z, col = "pink", add = TRUE, method = "edge",
             vfont = c("sans serif", "plain"))
     contour(x, x, z, ylim = c(1, 6), method = "simple", labcex = 1)
     contour(x, x, z, ylim = c(-6, 6), nlev = 20, lty = 2, method = "simple")
     par(op)

     ## Persian Rug Art:
     x <- y <- seq(-4*pi, 4*pi, len = 27)
     r <- sqrt(outer(x^2, y^2, "+"))
     opar <- par(mfrow = c(2, 2), mar = rep(0, 4))
     for(f in pi^(0:3))
       contour(cos(r^2)*exp(-r/f),
               drawlabels = FALSE, axes = FALSE, frame = TRUE)

     data("volcano")
     rx <- range(x <- 10*1:nrow(volcano))
     ry <- range(y <- 10*1:ncol(volcano))
     ry <- ry + c(-1,1) * (diff(rx) - diff(ry))/2
     tcol <- terrain.colors(12)
     par(opar); opar <- par(pty = "s", bg = "lightcyan")
     plot(x = 0, y = 0,type = "n", xlim = rx, ylim = ry, xlab = "", ylab = "")
     u <- par("usr")
     rect(u[1], u[3], u[2], u[4], col = tcol[8], border = "red")
     contour(x, y, volcano, col = tcol[2], lty = "solid", add = TRUE,
             vfont = c("sans serif", "plain"))
     title("A Topographic Map of Maunga Whau", font = 4)
     abline(h = 200*0:4, v = 200*0:4, col = "lightgray", lty = 2, lwd = 0.1)

     ## contourLines produces the same contour lines as contour
     line.list <- contourLines(x, y, volcano)
     plot(x = 0, y = 0,type = "n", xlim = rx, ylim = ry, xlab = "", ylab = "")
     u <- par("usr")
     rect(u[1], u[3], u[2], u[4], col = tcol[8], border = "red")
     contour(x, y, volcano, col = tcol[2], lty = "solid", add = TRUE,
                  vfont = c("sans serif", "plain"))
     templines <- function(clines) {
       lines(clines[[2]], clines[[3]])
     }  
     invisible(lapply(line.list, templines))
     par(opar)

