2D image and contour plots: Extended image and contour plots for 2-D (and 3-D) data.

Description

image2D extends R's image function. Input can be a matrix (2-D) or an array (3-D) or a list. contour2D extends R's contour function.

Usage

image2D (z, ...)
contour2D (z, x = seq(0, 1, length.out = nrow(z)),
         y = seq(0, 1, length.out = ncol(z)), ...,
         col = NULL, NAcol = NULL, 
         colkey = NULL, resfac = 1,
         clab = NULL, add = FALSE, plot = TRUE)

## S3 method for class 'matrix':
image2D(z, x = seq(0, 1, length.out = nrow(z)), 
               y = seq(0, 1, length.out = ncol(z)), colvar = z, ...,
               col = jet.col(100), NAcol = "white", 
               border = NA, facets = TRUE, contour = FALSE, 
               colkey = NULL, resfac = 1, clab = NULL, 
               lighting = FALSE, shade = NA, ltheta = -135, lphi = 0,
               theta = 0, rasterImage = FALSE,
               add = FALSE, plot = TRUE) 

## S3 method for class 'array':
image2D(z, margin = c(1, 2), subset, ask = NULL, ...) 
## S3 method for class 'list':
image2D(z, ...)

Arguments

Matrix (2-D) or array (3-D) or a list with matrices or arrays, with z-values. By default colvar is equal to z, hence z also defines the variable used to color the image.

x, y

Vectors or matrix with x and y values. If a vector x should be of length equal to nrow(z) and y should be of length equal to ncol(z). If a matrix (only for image2D), the

colvar

Only used when shade or lighting is toggled on. The variable used to color the image.

col

Color palette to be used for the image function or for the contours. See details.

NAcol

Color to be used for NA values of z; for image2D, the default is ``white'', for contour2D, the default is to do nothing.

contour

If TRUE, then a contour plot will be added to the image plot, unless x, y are a matrix. Also allowed is to pass a list with arguments for the

colkey

A logical, NULL (default), or a list with parameters for the color key (legend). List parameters should be one of

side, plot, length, width, dist, shift, addlines, col.clab, cex.clab,
      side.clab, line.clab

clab

Only if colkey is not NULL or FALSE, the label to be written on top of the color key. The label will be written at the same level as the main title. To lower it, clab can be made a vecto

resfac

Resolution factor, one value or a vector of two numbers, for the x and y- values respectively. A value > 1 will increase the resolution. For instance, if resfac equals 3 then for each adjacent pair of x- and y-v

lighting

If not FALSE the facets will be illuminated, and colors may appear more bright. To switch on lighting, the argument lighting should be either set to TRUE (using default settings) or it can be a list

shade

the degree of shading of the surface facets. Values of shade close to one yield shading similar to a point light source model and values close to zero produce no shading. Values in the range 0.5 to 0.75 provide an approximation to daylig

ltheta, lphi

if finite values are specified for ltheta and lphi, the surface is shaded as though it was being illuminated from the direction specified by azimuth ltheta and colatitude lphi. See

theta

The angle defining the azimuthal direction. Implemented for consistency with the other functions based on persp.

border

The color of the lines drawn around the surface facets. The default, NA, will disable the drawing of borders.

facets

If TRUE, then col denotes the color of the surface facets. If FALSE, then the surface facets are colored ``white'' and the border will be colored as specified by col. If NA<

rasterImage

If TRUE, the function rasterImage will be used for plotting rather than image or polygon. This requires the x

add

Logical. If TRUE, then the points will be added to the current plot. If FALSE a new plot is started.

plot

Logical. If TRUE (default), a plot is created, otherwise (for 3D plots) the viewing transformation matrix is returned (as invisible).

margin

A vector giving the subscripts which the image function will be applied over. The image function will loop over the index that is not in margin. For instance, c(1, 2), indicates to plot rows(x) and c

ask

A logical; if TRUE, the user is asked before each plot, if NULL the user is only asked if more than one page of plots is necessary and the current graphics device is set interactive, see

subset

Either a logical expression indicating over which elements to loop, or a vector or integers denoting the indices of the elements over which to loop. Missing values are taken as FALSE.

...

additional arguments passed to the plotting methods image, rasterImage, polygon and contour.

Value

Returns nothing.

Details

image2D is an extension to the default image plot that has the possibility to add a color key and contourlines, and to increase the resolution in order to make smoother images. It also uses a different color scheme, it can deal with decreasing x- and y- values and x and y can be a matrix. In the latter case, the image will be drawn as a set of polygons; if x and y are a vector, either R-function image or rasterImage will be used. image2D.array and image2D.list are versions that accept a 3 dimensional array respectively a list with z-matrices as their first argument to produce multiple plots. For argument col of the image2D function, both NA and NULL are allowed, in which case the color will be white, and no color key will be drawn. To set the ranges of the z-variable, both arguments zlim (as in image) and clim (as in the other plot3D functions) are accepted. Upon returning from the image2D and contour2D functions, the figure coordinates are defined by the main figure (excluding the color key). Thus, one can safely add other plotting elements.

Examples

Run this code

# save plotting parameters
 pm <- par("mfrow")

## =======================================================================
## Difference between x or y a vector/matrix and rasterImage
## =======================================================================

 par(mfrow = c(2, 2))
 x <- y <- 1:3
 z <- matrix (nrow = 3, ncol = 3, data = 1:9)
 image2D(z, x, y, border = "black")
 image2D(z, x, y, rasterImage = TRUE, border = "black")
 image2D(z, x = matrix(nrow = 3, ncol = 3, data = x), 
       y, border = "black")
 image2D(z, x, y, border = "black", theta = 45)

## =======================================================================
## shading, light, adding contours, points and lines
## =======================================================================

 par(mfrow = c(2, 2))
 nr <- nrow(volcano)
 nc <- ncol(volcano)

 image2D(volcano, x = 1:nr, y = 1:nc, lighting = TRUE, 
       main = "volcano", clab = "height, m")

 abline(v = seq(10, 80, by = 10))
 abline(h = seq(10, 60, by = 10))
 points(50, 30, pch = 3, cex = 5, lwd = 3, col = "white")

 image2D(z = volcano, x = 1:nr, y = 1:nc, lwd = 2, shade = 0.2,
       main = "volcano", clab = "height, m")

 image2D(volcano, x = 1:nr, y = 1:nc, contour = TRUE, shade = 0.5, lphi = 0,
       col = "lightblue", main = "volcano")

 image2D(volcano, x = 1:nr, y = 1:nc, col = jet.col(12),
       main = "volcano", clab = "height, m")

## =======================================================================
## Contour plots
## =======================================================================

 par(mfrow = c(2, 2))
 V <- volcano - 150
 
# default, no color key
 contour2D(z = V, colkey = FALSE, lwd = 2)

# imposed levels
 contour2D(z = V, lwd = 2, levels = seq(-40, 40, by = 20))

# negative levels dashed
 contour2D(z = V, col = "black", lwd = 2, 
           levels = seq(0, 40, by = 20))
 contour2D(z = V, col = "black", lwd = 2, lty = 2, 
           levels = seq(-40, -20, by = 20), add = TRUE)

# no labels, imposed number of levels, colorkey
 contour2D(z = V, lwd = 2, nlevels = 20, drawlabels = FALSE, 
           colkey = list(at = seq(-40, 40, by = 20)))

## =======================================================================
## A large data set, input is an array
## =======================================================================

 par(mfrow = c(1, 1))
 image2D(z = Oxsat$val[, , 1], x = Oxsat$lon, y = Oxsat$lat,
       main = "surface oxygen saturation data 2005", NAcol = "black", 
       clab = c("","","%"))

# images at first 9 depths - use subset to select them
 image2D(z = Oxsat$val, subset = 1:9, 
       x = Oxsat$lon, y = Oxsat$lat,
       margin = c(1, 2), NAcol = "black", 
       xlab = "longitude", ylab = "latitude", 
       zlim = c(0, 115),
       main = paste("depth ", Oxsat$depth[1:9], "m"),
       mfrow = c(3, 3))

# images at latitude - depth section - increase resolution
 z <- Oxsat$val[,  Oxsat$lat > - 5 & Oxsat$lat < 5, ]
 image2D(z = z, x = Oxsat$lon, y = Oxsat$depth,
       margin = c(1, 3), NAcol = "black", 
       resfac = 3, ylim = c(5000, 0))
  
# show position of transects 
 image2D(z = Oxsat$val[ , ,1], 
       x = Oxsat$lon, y = Oxsat$lat,
       NAcol = "black")
 abline(h = Oxsat$lat[Oxsat$lat > - 5 & Oxsat$lat < 5])      

## =======================================================================
## Image of a list of matrices
## =======================================================================

 listvolcano <- list(volcano = volcano, logvolcano = log(volcano)) 
 image2D(listvolcano, x = 1:nr, y = 1:nc, contour = TRUE,
       main = c("volcano", "log(volcano)"), 
       clab = list("height, m", "log(m)"),
       zlim = list(c(80, 200), c(4.4, 5.5)))

## =======================================================================
## Image of a list of arrays
## =======================================================================

# crude conversion from oxsat to oxygen 
 listoxygen <- list(Oxsat$val, Oxsat$val/100 * 360)
  
 image2D(z = listoxygen, 
       x = Oxsat$lon, y = Oxsat$lat,
       margin = c(1, 2), NAcol = "black", 
       main = c("Oxygen saturation ", " Oxygen concentration"),
       mtext = paste("depth ", Oxsat$depth, " m")
       )

## =======================================================================
## 'x', 'y' and 'z' are matrices
## =======================================================================

 par(mfrow = c(2, 1))

# tilted x- and y-coordinates of 'volcano'
 volcx <- matrix(nrow = 87, ncol = 61, data = 1:87)
 volcx <- volcx + matrix(nrow = 87, ncol = 61, 
        byrow = TRUE, data = seq(0., 15, length.out = 61))

 volcy <- matrix(ncol = 87, nrow = 61, data = 1:61)
 volcy <- t(volcy + matrix(ncol = 87, nrow = 61, 
        byrow = TRUE, data = seq(0., 25, length.out = 87)))

 image2D(volcano, x = volcx, y = volcy)

# use of panel function
 image2D(volcano, x = volcx, y = volcy, NAcol = "black", 
       panel.first = substitute(box(col = "lightgrey", lwd = 30)))
                                    
## =======================================================================
## Image with NAs and logs
## =======================================================================

 par(mfrow = c(2, 2))
# normal volcano
 image2D(volcano, clab = c("height", "m"))

# logarithmic z-axis
 image2D(volcano, log = "z", clab = c("height", "m"),
     main = "log='z'")

# Including NAs
 VOLC <- volcano - 110
 VOLC [VOLC <= 0] <- NA
 image2D(VOLC, main = "including NAs and rescaled")

# both
 image2D(VOLC, NAcol = "black", log = "z", zlim = c(1, 100),
     main = "NAs and log = 'z'")

## =======================================================================
## Image with contour specification (alpha sets the transparency)
## =======================================================================

 par(mfrow = c(1, 1))
 image2D(volcano, shade = 0.2, rasterImage = TRUE,
   contour = list(col = "white", labcex = 0.8, lwd = 3, alpha = 0.5))
# same:
image2D(z = volcano, shade = 0.2, rasterImage = TRUE)
 contour2D(z = volcano, col = "white", labcex = 0.8, 
   lwd = 3, alpha = 0.5, add = TRUE)
# reset plotting parameters
 par(mfrow = pm)

Run the code above in your browser using DataLab