# 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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | ```
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 |

`x, y ` |
Vectors or matrix with x and y values.
If a vector |

`colvar ` |
Only used when |

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

`NAcol ` |
Color to be used for |

`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 |

`colkey ` |
A logical, The default is to draw the color key on side = 4, i.e. in the right margin.
If |

`clab ` |
Only if |

`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 |

`lighting ` |
If not Will overrule 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 |

`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, |

`facets ` |
If |

`rasterImage ` |
If |

`add ` |
Logical. If |

`plot ` |
Logical. If |

`margin ` |
A vector giving the subscripts which the |

`ask ` |
A logical; if |

`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 |

`...` |
additional arguments passed to the plotting methods image, rasterImage, polygon and contour.
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 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.

### Value

Returns nothing.

### 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.

### Author(s)

Karline Soetaert <karline.soetaert@nioz.nl>

### 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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 | ```
# 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")
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 = 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)
# 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 = 1:88)
volcx <- volcx + matrix(nrow = 88, ncol = 62,
byrow = TRUE, data = seq(0., 15, length.out = 62))
volcy <- matrix(ncol = 88, nrow = 62, data = 1:62)
volcy <- t(volcy + matrix(ncol = 88, nrow = 62,
byrow = TRUE, data = seq(0., 25, length.out = 88)))
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)
``` |