Contour Plot

DESCRIPTION:

Make a contour plot and possibly return coordinates of contour lines.

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==1:nrow(z) and y==1:ncol(z)). The result of predict, together with expand.grid, is also suitable as an argument to contour.

OPTIONAL ARGUMENTS:

nlevels
the approximate number of contour intervals desired. By default, nlevels=5. This argument 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 to 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=TRUE, contour lines are added to the current plot. You can use this to add contours with a different labex parameter, line type, etc., or to add contours to some other type of plot. By default, add=FALSE.
labex
the size of the characters used to label the contour lines, relative to the current value of the cex parameter. By default, labex=1.
save
logical flag. If TRUE, the coordinates of the contour lines are returned. By default, save=FALSE.
plotit
logical flag. If TRUE, the contour plot is plotted. You should set at least one of save and plotit to TRUE.
triangles
logical flag that selects the contour algorithm; see the DETAILS section below.
Graphical parameters may also be supplied as arguments to this function. See the help file for more details. 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 and the arguments to the function may be supplied to contour.

VALUE:

a vector of the contour levels is returned when save=FALSE. If save=TRUE, the output structure is a list with length equal to the number of contour intervals. The names of the elements identify the contour levels. Each component of the return list contains an x and y component suitable for plotting with lines.

SIDE EFFECTS:

a contour plot is drawn when plotit=TRUE.

DETAILS:

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

Each rectangular cell of 4 numbers is contoured independently. If triangles=FALSE, contour segments 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=TRUE, the cell is broken up into 4 triangles that meet at the center and the z value at the center is set to be the average of the (non-missing) corner values. We then 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:

x <- 1:10
y <- 1:10
z <- matrix(rnorm(100), nrow=10)
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) 
ozone.interp <- 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(ozone.interp, add=T, labex=0) 
text(ozone.xy, labels=ozone.median) 
title(main="Median Ozone in the North East")