image.plot: Draws image plot with a legend strip for the color scale.

Description

This function combines the SPLUS image function with some automatic placement of a legend. This is done by splitting the plotting region into two parts. Putting the image in one and the legend in the other.

Usage

image.plot(..., add=TRUE, nlevel=32, legend.shrink=0.9, legend.width=0.02,  
graphics.reset=TRUE, horizontal=FALSE, offset=0.04,  
bigplot=NULL, smallplot=NULL, legend.only=FALSE, col=topo.colors(64))

Arguments

Side Effects

After exiting, the plotting region may be changed to make it possible to add more features to the plot. To be explicit, par()$plt may be changed to reflect a smaller plotting region that includes a legend subplot.

Details

It is surprising how hard it is just to automatically add the legend! All "plotting coordinates" mentioned here are in device coordinates. The plot region is assumed to be [0,1]X[0,1] and plotting regions are defined as rectangles within this square. We found these easier to work with than user coordinates. There are always problems with default solutions to placing information on graphs but the choices made here may be useful for most cases. The most annoying thing is that after using plot.image and adding information the next plot that is made may have the slightly smaller plotting region set by the image plotting.

The strategy is simple, divide the plotting region into two smaller regions. The image goes in one and the legend in the other. This way there is always room for the legend. Some adjustments are made to this rule by not shrinking the image plot if there is already room for the legend strip and also sticking the legend strip close to the image plot. Also, one can specify the plot regions explicitly by bigplot and small plot if the default choices do not work. There may be problems with small plotting regions in fitting both of these plot and one may have to change the default character sizes or margins to make things fit.

By keeping the zlim argument the same across images one can generate the same color scale. (See image help file) One useful technique for a panel of images is to just draw the first with image.plot to get a legend and just use image for subsequent plots. Also keep in mind one can just add a legend to an existing plot without changing plotting parameters. Usually a square plot (pty="s") done in a rectangular plot region will have room for the legend with any adjustments stuck to the right side.

Examples

Run this code

x<- 1:10 
 y<- 1:15 
z<- outer( x,y,"+") 
image.plot(x,y,z) 
# now add some points on diagonal  
points( 5:10, 5:10)
#
#fat (5\% of figure) and short (50\% of figure)  legend strip on the bottom 
image.plot( x,y,z,legend.width=.05, legend.shrink=.5, horizontal=TRUE) 

# add a legend on the bottom but first change margin for some room 
par( mar=c(10,5,5,5))

image( x,y,z)
image.plot( zlim=c(0,25), legend.only=TRUE, horizontal=TRUE)
#