# Extended image and contour plots for 2-D (and 3-D) data. `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. ```r 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 = NULL, NAcol = "white", breaks = NULL, 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 - `z`: 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 . Only when `shade` or `lighting` is toggled on does it make sense to use `z` different from `colvar`. - `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`), they should have the same dimension as `z` or be of dimension = `dim(z)+1`. - `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. - `breaks`: a set of finite numeric breakpoints for the colors; must have one more breakpoint than color and be in increasing order. Unsorted vectors will be sorted, with a warning. - `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 contour function. - `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, adj.clab, font.clab` and the axis parameters `at, labels, tick, line, pos, outer, font, lty, lwd, lwd.ticks, col.box,col.axis, col.ticks, hadj, padj, cex.axis, mgp, tck, tcl, las`. The defaults for the parameters are `side = 4, plot = TRUE, length = 1, width = 1, dist = 0, shift = 0,addlines = FALSE, col.clab = NULL, cex.clab = par("cex.lab"), side.clab= NULL, line.clab = NULL, adj.clab = NULL, font.clab = NULL`) See colkey . The default is to draw the color key on side = 4, i.e. in the right margin. If `colkey` = `NULL` then a color key will be added only if `col` is a vector. Setting `colkey = list(plot = FALSE)` will create room for the color key without drawing it. if `colkey = FALSE`, no color key legend will be added. - `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 vector, with the first values empty strings. - `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-values, z will be interpolated to two intermediary points. This uses simple linear interpolation. If `resfac` is one number then the resolution will be increased similarly in x and y-direction. - `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 with specifications of one of the following: `ambient, diffuse, specular, exponent, sr` and `alpha`. Will overrule `shade` not equal to `NA`. See examples in jet.col . - `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 daylight illumination. See persp . - `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 persp . - `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` then the facets will be transparent. It is usually faster to draw with `facets = FALSE`. - `rasterImage`: If `TRUE`, the function rasterImage will be used for plotting rather than image or polygon . This requires the `x` and `y` to be a vector with equally spaced elements. Note that by default, rasterImage linearly interpolates the image, so it will appear smoother. - `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 columns(y) and to loop over index `3`; `c(2, 1)` will do the same but the image will be transposed. `margin` should be a vector with two numbers inbetween `1`, and `3`. - `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 par (ask) and dev.interactive . - `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 . `alpha` can be given a value inbetween 0 and 1 to make colors transparent. The arguments after `...` must be matched exactly. ## 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 polygon s; 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. ## Note The first argument, `z` generally determines the color variable. For consistency with the other functions, another variable, `colvar` is also defined and set by default equal to `z`. `colvar` will only be used if `shade` or `lighting` are toggled on. In this case, `z` will be used to define the shading (orientation of each facet), while `colvar` will define the color. When `x` and `y` is a vector, the function uses R-function image . This means that the x- and y- axis will extend the x- and y- values with half a grid cell. In contrast, when `x` and `y` are a matrix, the axis will not extend the x- or y- values. See first example. ## Returns Returns nothing. ## Author(s) Karline Soetaert ## See Also jet.col , ImageOcean , Oxsat , persp3D , scatter2D for other examples where `image2D` is used. image and contour for the original R functions. `plot.image` from the fields package. ## Examples ```r # 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 = rep(x, times = 3)), 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") breaks <- seq(90, 200, by = 10) image2D(volcano, x = 1:nr, y = 1:nc, col = jet.col(length(breaks)-1), main = "volcano", clab = "height, m", breaks = breaks) ## ======================================================================= ## 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 ## ======================================================================= ## Not run: # 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") ) ## End(Not run) ## ======================================================================= ## '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 = rep(1:87, times=61)) volcx <- volcx + matrix(nrow = 87, ncol = 61, byrow = TRUE, data = rep(seq(0., 15, length.out=61), times=87)) volcy <- matrix(ncol = 87, nrow = 61, data = rep(1:61, times=87)) volcy <- t(volcy + matrix(ncol = 87, nrow = 61, byrow = TRUE, data = rep(seq(0., 25, length.out=87), times=61))) image2D(volcano, x = volcx, y = volcy) # x and y can also be of dimension dim(z)+1: ## Not run: # tilted x- and y-coordinates of 'volcano' volcx <- matrix(nrow = 88, ncol = 62, data = rep(1:88, times=62)) volcx <- volcx + matrix(nrow = 88, ncol = 62, byrow = TRUE, data = rep(seq(0., 15, length.out=62), times=88)) volcy <- matrix(ncol = 88, nrow = 62, data = rep(1:62, times=88)) volcy <- t(volcy + matrix(ncol = 88, nrow = 62, byrow = TRUE, data = rep(seq(0., 25, length.out=88), times=62))) image2D(volcano, x = volcx, y = volcy) ## End(Not run) # 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: ## Not run: image2D(z = volcano, shade = 0.2, rasterImage = TRUE) contour2D(z = volcano, col = "white", labcex = 0.8, lwd = 3, alpha = 0.5, add = TRUE) ## End(Not run) # reset plotting parameters par(mfrow = pm) ```

Image function