Contour Plot

DESCRIPTION:

USAGE:

contour(x, y, z, nlevels=5, levels=pretty(z, nlevels), add=F, labex=1, 
        save=F, plotit=!save, triangles=F) 

REQUIRED ARGUMENTS:

x

vector containing x coordinates of the grid over which z is evaluated. The values must be in increasing order, and missing values are not accepted.

y

vector of grid y coordinates. The values must be in increasing order, and missing values are not accepted.

z

matrix of size length(x) by length(y) giving the surface height at grid points, i.e., z[i,j] is evaluated at x[i], y[j]. The rows of z are indexed by x, and the columns by y. Missing values ( NAs) are allowed, but should generally not occur in the convex hull of the non-missing values.

The first argument may be a list with components x, y, and z. In particular, the result of interp is suitable as an argument to contour.

If the first argument is a matrix, it is assumed to be the z matrix and vectors x and y are generated ( x is 1:nrow(z), y is 1:ncol(z)). The result of predict together with expand.grid is suitable as an argument to contour.

OPTIONAL ARGUMENTS:

nlevels=

the approximate number of contour intervals desired. This is not needed if levels is specified. (For compatibility with the old contour function you may call this argument nint.)

levels=

vector of heights of contour lines. By default, approximately nlevels lines are drawn which cover the range of z. (For compatibility with the old contour function you may call this argument v.)

add=

logical flag: if TRUE (and plotit is TRUE), contour lines are added to the current plot. Use this to add contours with a different labex parameter, line type, etc., or to add contours to some other type of plot.

labex=

the size of the characters used to label the contour lines, relative to the current value of the cex parameter.

save=

logical flag: if TRUE, then the coordinates of the contour lines will be returned.

plotit=

logical flag: if TRUE, the contour plot will be plotted. You should set at least one of save and plotit to TRUE.

triangles=

logical flag that selects the contour algorithm; see DETAILS below.

Graphical parameters may also be supplied as arguments to this function (see par ). The default x and y axis labels are generated from the names of the data; set xlab and ylab to "" to get no labels. In addition, the high-level graphics arguments described under plot.default and the arguments to title may be supplied to this function.

VALUE:

a vector of the contour levels is returned when save is FALSE.

If save is TRUE, then the output structure will be a list whose length is the number of contour intervals. The names of the elements will be the contour levels. Each component of this list will contain an x and y component suitable for plotting with lines.

SIDE EFFECTS:

DETAILS:

The triangles argument selects which of two algorithms is used to create the contours. The triangle method is more wiggly but will tend to round sharp corners. The triangle method is somewhat slower, and will create a return value (when save is TRUE) that is approximately twice as large.

Each rectangular cell of 4 numbers is contoured independently. If triangles is FALSE (the default), contour segments will connect the edges of the cell crossing the contour level. At saddle point cells (all 4 edges cross a contour level), we use the triangle method to select which edges to connect.

If triangles is TRUE, then the cell is broken up into 4 triangles meeting at the center and the z value at the center is set to be the average of the (non-missing) corner values. Then we fit a plane to each triangle and contour that with straight line segments. (Triangles with missing values at the corners are ignored.)

NOTE:

Older versions of S-PLUS contained a different contour function, now called contour.old.

SEE ALSO:

EXAMPLES:

cont.lines <- contour(x, y, z, save=T) 
plot(x, y, type="n") 
for (j in seq(along=cont.lines)) 
  if (length(cont.lines[[j]]$x)) lines(cont.lines[[j]]) 
rx <- range(ozone.xy$x) 
ry <- range(ozone.xy$y) 
i <- interp(ozone.xy$x, ozone.xy$y, ozone.median)  
#interp creates a matrix of interpolated points, z, for  
# an increasing, evenly spaced sequence of points  
# over the range of the input x and y 
usa(xlim=rx, ylim=ry, lty=2, col=2) 
contour(i, add=T, labex=0) 
text(ozone.xy, ozone.median) 
title(main="Median Ozone in the North East")