filled.contour           package:graphics           R Documentation

Level (Contour) Plots

Description:

     This function produces a contour plot with the areas between the
     contours filled in solid color (Cleveland calls this a level
     plot).  A key showing how the colors map to z values is shown to
     the right of the plot.

Usage:

     filled.contour(x = seq(0, 1, length.out = nrow(z)),
                    y = seq(0, 1, length.out = ncol(z)),
                    z,
                    xlim = range(x, finite=TRUE),
                    ylim = range(y, finite=TRUE),
                    zlim = range(z, finite=TRUE),
                    levels = pretty(zlim, nlevels), nlevels = 20,
                    color.palette = cm.colors,
                    col = color.palette(length(levels) - 1),
                    plot.title, plot.axes, key.title, key.axes,
                    asp = NA, xaxs = "i", yaxs = "i", las = 1,
                    axes = TRUE, frame.plot = axes, ...)

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.

    xlim: x limits for the plot.

    ylim: y limits for the plot.

    zlim: z limits for the plot.

  levels: a set of levels which are used to partition the range of 'z'.
           Must be *strictly* increasing (and finite).  Areas with 'z'
          values between consecutive levels are painted with the same
          color.

 nlevels: if 'levels' is not specified, the range of 'z', values is
          divided into approximately this many levels.

color.palette: a color palette function to be used to assign colors in
          the plot.

     col: an explicit set of colors to be used in the plot. This
          argument overrides any palette function specification.

plot.title: statements which add titles to the main plot.

plot.axes: statements which draw axes (and a 'box') on the main plot. 
          This overrides the default axes.

key.title: statements which add titles for the plot key.

key.axes: statements which draw axes on the plot key. This overrides
          the default axis.

     asp: the y/x aspect ratio, see 'plot.window'.

    xaxs: the x axis style.  The default is to use internal labeling.

    yaxs: the y axis style.  The default is to use internal labeling.

     las: the style of labeling to be used.  The default is to use
          horizontal labeling. 

axes, frame.plot: logicals indicating if axes and a box should be
          drawn, as in 'plot.default'.

     ...: additional graphical parameters, currently only passed to
          'title()'.

Note:

     This function currently uses the 'layout' function and so is
     restricted to a full page display.  As an alternative consider the
     'levelplot' and 'contourplot' functions from the 'lattice' package
     which work in multipanel displays.

     The output produced by 'filled.contour' is actually a combination
     of two plots; one is the filled contour and one is the legend. 
     Two separate coordinate systems are set up for these two plots,
     but they are only used internally - once the function has returned
     these coordinate systems are lost.  If you want to annotate the
     main contour plot, for example to add points, you can specify
     graphics commands in the 'plot.axes' argument.  An example is
     given below.

Author(s):

     Ross Ihaka.

References:

     Cleveland, W. S. (1993) _Visualizing Data_. Summit, New Jersey:
     Hobart.

See Also:

     'contour', 'image', 'palette'; 'contourplot' from package
     'lattice'.

Examples:

     require(grDevices) # for colours
     filled.contour(volcano, color = terrain.colors, asp = 1)# simple

     x <- 10*1:nrow(volcano)
     y <- 10*1:ncol(volcano)
     filled.contour(x, y, volcano, color = terrain.colors,
         plot.title = title(main = "The Topography of Maunga Whau",
         xlab = "Meters North", ylab = "Meters West"),
         plot.axes = { axis(1, seq(100, 800, by = 100))
                       axis(2, seq(100, 600, by = 100)) },
         key.title = title(main="Height\n(meters)"),
         key.axes = axis(4, seq(90, 190, by = 10)))# maybe also asp=1
     mtext(paste("filled.contour(.) from", R.version.string),
           side = 1, line = 4, adj = 1, cex = .66)

     # Annotating a filled contour plot
     a <- expand.grid(1:20, 1:20)
     b <- matrix(a[,1] + a[,2], 20)
     filled.contour(x = 1:20, y = 1:20, z = b,
                    plot.axes={ axis(1); axis(2); points(10,10) })

     ## Persian Rug Art:
     x <- y <- seq(-4*pi, 4*pi, len = 27)
     r <- sqrt(outer(x^2, y^2, "+"))
     filled.contour(cos(r^2)*exp(-r/(2*pi)), axes = FALSE)
     ## rather, the key *should* be labeled:
     filled.contour(cos(r^2)*exp(-r/(2*pi)), frame.plot = FALSE,
                    plot.axes = {})

