Produces a "ragged" image plot
Description
This code produces an image plot in the case in which there
is not a known response value z
for every possible combination
of x
and y
. This ragged image plot is a variant of an
image plot which is not complete across the entire rectangle of the
gridded area.
Usage
1 2  ragged.image(x, y, z, zlim = range(z, na.rm = TRUE), add = FALSE,
col = heat.colors(12), xlab, ylab, plt.beyond.zlim = FALSE, ...)

Arguments
x 
xcoordinates of grid cell centers at which response values

y 
ycoordinates of grid cell centers at which response values

z 
Response values recorded at the grid cell centers whose
coordinates are given by ( 
zlim 
Vector of minimum and maximum values of 
add 
If FALSE (default), the ragged image will begin a new plot. If TRUE, adds ragged image to a preexisting plot. 
col 
Color range to use for the ragged image, with the first
color assigned to zlim[1] and last color assigned to zlim[2].
Default is "heat.colors(12)", as it is for 
xlab 
The label for the xaxis. If not specified by the user,
defaults to the expression the user named as parameter 
ylab 
The label for the yaxis. If not specified by the user,
defaults to the expression the user named as parameter 
plt.beyond.zlim 
IF TRUE, and if 
... 
Any additional parameters to be passed to the

Details
This code produces a ragged image plot. This is in contrast to
the standard image
function, which assumes that there is a
known response value z
for every combination of the elements of
x
and y
, i.e. that there is a complete rectangular grid,
or image. A ragged image plot is a variant of the regular image plot
which is not complete across the entire rectangle. The user specifies
vectors x
, y
, and z
, such that x
and
y
identify a portion of the grid. This function maps the vector
z
onto a matrix of the type needed for the image
function, but has NA entries for combinations of x
and y
that are not listed. The NA values are not plotted by
image
, so a ragged image will appear.
Value
A ragged image, i.e. a portion of an image for which we have
specified grid cell centers x
and y
.
Note
This function is slow if x
, y
, and z
are long
vectors.
Author(s)
Jenise Swall
See Also
image
, heat.colors
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  ## Build x, y, and z.
x < c(1, 2, 3, 1, 2, 3)
y < c(1, 1, 1, 2, 2, 2)
z < 1:6
z.mat < matrix(c(1:6), ncol=2)
col.rng < terrain.colors(6)
par(mfrow=c(1,2))
## Show complete matrix.
image(x=unique(x), y=unique(y), z.mat, zlim=range(z), col=col.rng,
xlab="x", ylab="y")
## Plot only part of this as a ragged image. Set z range so that this
## image will use colors consistent with the previous one.
ragged.image(x=x[1:4], y=y[1:4], z=z[1:4], zlim=range(z), col=col.rng,
xlab="x", ylab="y")
## When some z value(s) is/are much lower/higher than the others,
## the outlying value(s) may appear in color at the extent
## of the range, with the remainder of the data clustered in one (or
## just a few) color bin(s).
x < c(1, 2, 3, 1, 3, 2, 3, 1, 3)
y < c(4, 4, 4, 3, 3, 2, 2, 1, 1)
z < c(0, 47:53, 100)
dev.new()
par(mfrow=c(1,3))
col.rng < rev(rainbow(n=7, start=0, end=4/6))
ragged.image(x, y, z, col=col.rng)
text(x, y, z, cex=0.8)
## In vain, you might try to "fix" this by setting zlim so that the
## color range reflects the main portion of the z values. You may
## assume that the outlying value(s) will show up in the extreme edges
## of the color range, but what will actually happen is that the
## outlying values won't be plotted.
ragged.image(x, y, z, col=col.rng, zlim=c(47, 53))
text(x, y, z, cex=0.8)
## Instead, specify zlim to reflect the main porition of the z values,
## and set plt.beyond.zlim=TRUE. Now, z values below zlim[1] will be
## plotted in the same color as zlim[1]; those above zlim[2] will be
## plotted like z values of zlim[2]. But, remember, now there are
## outlying values whose maginitudes cannot be easily ascertained!
ragged.image(x, y, z, zlim=c(47, 53), col=col.rng, plt.beyond.zlim=TRUE)
text(x, y, z, cex=0.8)
