aqfig (version 0.9)

ragged.image: 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

ragged.image(x, y, z, zlim = range(z, na.rm = TRUE), add = FALSE,
   col = heat.colors(12), xlab, ylab, plt.beyond.zlim = FALSE, ...)

Value

A ragged image, i.e. a portion of an image for which we have specified grid cell centers x and y.

Arguments

x

x-coordinates of grid cell centers at which response values z are available.

y

y-coordinates of grid cell centers at which response values z are available.

z

Response values recorded at the grid cell centers whose coordinates are given by (x, y).

zlim

Vector of minimum and maximum values of z to which to assign the two most extreme colors in the 'col' argument (col[1] and col[length(col)]). Default is to use the range of z. This is very much like the 'zlim' argument to the image function.

add

If FALSE (default), the ragged image will begin a new plot. If TRUE, adds ragged image to a pre-existing 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 image.

xlab

The label for the x-axis. If not specified by the user, defaults to the expression the user named as parameter x. This behavior is similar to that for image.

ylab

The label for the y-axis. If not specified by the user, defaults to the expression the user named as parameter y. This behavior is similar to that for image.

plt.beyond.zlim

IF TRUE, and if zlim is specified by the user, z values beyond the limits given in zlim are plotted. Values less than zlim[1] are plotted in the same color as zlim[1]; values greater than zlim[2] are plotted in the same color as zlim[2]. If TRUE, and zlim is not specified by the user, zlim[1] and zlim[2] will be assigned the minimum and maximum values of z. In this case, user is warned and plt.beyond.zlim is set to FALSE. Default is plt.beyond.zlim==FALSE.

...

Any additional parameters to be passed to the image function, if add=FALSE.

Author

Jenise Swall

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.

See Also

image, heat.colors

Examples

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