-
Notifications
You must be signed in to change notification settings - Fork 8
/
image.plot.html
548 lines (479 loc) · 23.5 KB
/
image.plot.html
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
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Draws an image plot with a legend strip for the color scale...</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<link rel="stylesheet" type="text/css" href="R.css" />
</head><body>
<table width="100%" summary="page for image.plot {fields}"><tr><td>image.plot {fields}</td><td style="text-align: right;">R Documentation</td></tr></table>
<h2>
Draws an image plot with a legend strip for the color scale based on either
a regular grid or a grid of quadrilaterals.
</h2>
<h3>Description</h3>
<p>This function combines the R 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. After the
legend is added the plot region is reset to the image plot.
This function also allows for plotting quadrilateral cells in the image format that
often arise from regular grids transformed with a map projection or a scaling and rotation of coordinates.
</p>
<h3>Usage</h3>
<pre>
## S3 method for class 'plot'
image(...,
add = FALSE,
breaks= NULL, nlevel = 64, col = NULL,
horizontal = FALSE, legend.shrink = 0.9, legend.width = 1.2,
legend.mar = ifelse(horizontal, 3.1, 5.1), legend.lab = NULL,
legend.line= 2,
graphics.reset = FALSE, bigplot = NULL, smallplot = NULL,
legend.only = FALSE, lab.breaks = NULL,
axis.args = NULL, legend.args = NULL, legend.cex=1.0, midpoint = FALSE, border = NA,
lwd = 1,verbose = FALSE )
</pre>
<h3>Arguments</h3>
<table summary="R argblock">
<tr valign="top"><td><code>...</code></td>
<td>
<p>The usual arguments to the <code>image</code> function as x,y,or z or as a
list with x,y,z as components. One can also include a <code>breaks</code>
argument for an unequal spaced color scale with color scale boundaries
at the breaks (see example below). If a "quadrilateral grid",
arguments must be explicitly x,y and z with x, and y being matrices of
dimensions equal to, or one more than, z giving the grid
locations. The basic concept is that the coordinates of x and y still
define a grid but the image cells are quadrilaterals rather than being
restricted to rectangles. NOTE: graphical argruments passed here will only have impact
on the image plot. To change the graphical defaults for the legend use
the individual legend arguments and <code>legend.arg</code> listed below.
</p>
</td></tr>
<tr valign="top"><td><code>add</code></td>
<td>
<p>If true add image and a legend strip to the existing plot.
</p>
</td></tr>
<tr valign="top"><td><code>bigplot</code></td>
<td>
<p>Plot coordinates for image plot. If not passed
these will
be determined within the function.
</p>
</td></tr>
<tr valign="top"><td><code>border</code></td>
<td>
<p>This only works if x and y are matrices – if NA the quadralaterals will
have a border color that is
the same as the interior color. Otherwise this specifies the color to use.</p>
</td></tr>
<tr valign="top"><td><code>breaks</code></td>
<td>
<p>Break points in sorted order to indicate the intervals for assigning
the colors. Note that if there are nlevel colors there should be (nlevel+1)
breakpoints. If <code>breaks</code> is not specified (nlevel+1) equally spaced breaks are created where the first and last bin have their midpoints at the minimum and maximum values in <code>z</code> or at <code>zlim</code>. </p>
</td></tr>
<tr valign="top"><td><code>col</code></td>
<td>
<p>Color table to use for image (See help file on image for details.).
Default is a pleasing range of 64 divisions suggested by Tim Hoar and is similar to
the MATLAB (TM) jet color scheme. Note that if <code>breaks</code> is specified there must be one less color specified than the number of breaks.
</p>
</td></tr>
<tr valign="top"><td><code>graphics.reset</code></td>
<td>
<p>If FALSE (default) the plotting region ( plt in par) will not be reset
and one can add more information onto the image plot. (e.g. using functions
such as points or lines.) If TRUE will reset plot parameters to the
values before entering the function.
</p>
</td></tr>
<tr valign="top"><td><code>horizontal</code></td>
<td>
<p>If false (default) legend will be a vertical strip on the right side. If
true the legend strip will be along the bottom.
</p>
</td></tr>
<tr valign="top"><td><code>lab.breaks</code></td>
<td>
<p> If breaks are supplied these are text string labels
to put at each break value. This is intended to label axis on a
transformed scale such as logs.</p>
</td></tr>
<tr valign="top"><td><code>axis.args</code></td>
<td>
<p>Additional arguments for the axis function used to
create the legend axis. (See example below adding a log scaling.)</p>
</td></tr>
<tr valign="top"><td><code>legend.only</code></td>
<td>
<p>If TRUE just add the
legend to a the plot in the plot region defined by the coordinates in
smallplot. In the absence of other information the range for the legend
is determined from the <code>zlim</code> argument.
</p>
</td></tr>
<tr valign="top"><td><code>legend.args</code></td>
<td>
<p>Arguments for a complete specification of the
legend label, e.g. if you need to the rotate text or other details. This is in the form of list and is just passed to the
mtext function and you will need to give both the side and line arguments for positioning. This usually will not be needed.
(See example below.)</p>
</td></tr>
<tr valign="top"><td><code>legend.cex</code></td>
<td>
<p>Character expansion to change size of the legend label.</p>
</td></tr>
<tr valign="top"><td><code>legend.line</code></td>
<td>
<p>Distance in units of character height (as in <code>mtext</code>)
of the legend label from the
color bar. Make this larger if the label collides with the color axis labels.</p>
</td></tr>
<tr valign="top"><td><code>legend.mar</code></td>
<td>
<p>Width in characters of legend margin that has the axis. Default is 5.1
for a vertical legend and 3.1 for a horizontal legend.</p>
</td></tr>
<tr valign="top"><td><code>legend.lab</code></td>
<td>
<p> Label for the axis of the color legend. Default is no
label as this is usual evident from the plot title.</p>
</td></tr>
<tr valign="top"><td><code>legend.shrink</code></td>
<td>
<p>Amount to shrink the size of legend relative to the full height or width
of the plot.
</p>
</td></tr>
<tr valign="top"><td><code>legend.width</code></td>
<td>
<p>Width in characters of the legend strip. Default is 1.2, a little bigger
that the width of a character. </p>
</td></tr>
<tr valign="top"><td><code>lwd</code></td>
<td>
<p>Line width of bordering lines around pixels.
This might need to be set less than 1.0
to avoid visible rounding of the pixel corners.</p>
</td></tr>
<tr valign="top"><td><code>midpoint</code></td>
<td>
<p>This option for the case of unequally spaced grids with x and y being
matrices of grid point locations.
If FALSE (default) the quadralaterals will be extended
to surround the z locations as midpoints. If TRUE z values will be averaged
to yield a midpoint value and the original grid points be used to define the
quadralaterals. (See help on poly.image for details). In most cases
midpoint should be FALSE to preserve exact values for z and
let the grid polygons be modified.</p>
</td></tr>
<tr valign="top"><td><code>nlevel</code></td>
<td>
<p>Number of color levels used in legend strip
</p>
</td></tr>
<tr valign="top"><td><code>smallplot</code></td>
<td>
<p>Plot coordinates for legend strip. If not passed these will be determined within
the function. Be sure to leave room for the axis labels. For example, if the legend is on the
right side <code>smallplot= c(.85,.9,0,1) </code> will leave (.1 in plot coordinates) for the
axis labels to the right of the color strip. This argument is useful for drawing a
plot with the legend that is the same size as the plots without legends.
</p>
</td></tr>
<tr valign="top"><td><code>verbose</code></td>
<td>
<p>If TRUE prints intermediate information about setting up plots (for debugging). </p>
</td></tr>
</table>
<h3>Details</h3>
<p>This is a function using the basic R graphics. The coding was done to make it easier for users to see how this function works and to modify.
</p>
<p><strong>How this function works:</strong>
The strategy for <code>image.plot</code> is simple, divide the plotting region
into two smaller regions <code>bigplot</code> and <code>smallplot</code>. 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
<code>bigplot</code> if there is already room for the legend strip and also
sticking the legend strip close to the image plot. One can specify the
plot regions explicitly by <code>bigplot</code> and <code>smallplot</code> if the
default choices do not work.(Note that these in figure coordinates.
) There may be problems with small plotting
regions in fitting both of these elements into the plot region and one may
have to change the default character sizes or margins to make things fit.
Sometimes this function will not reset the type of margins correctly and the
"null" call <code>par(mar = par("mar"))</code> may help to fix this issue.
</p>
<p><strong>The text is too small!</strong>
This always seems to happen as one is rushing to finish a talk and the figures have tiny default axis labels. Try just calling the function <code>fields.style</code> before plotting. List out this function to see what is changed, however, all text is increased by 20% in size.
</p>
<p><strong>Why “image.plot" and not “image"?</strong> The R Base function <code>image</code> is very
useful but it is awkward to place a legend quickly. However, that said if you are
drawing several image plots and want a common legend use the <code>image</code> function
and just just use <code>image.plot</code> to add the legend. See the example in the
help file. Note that you can use <code>image</code> to draw a bunch of images and then follow with <code>image.plot</code> and <code>legend.only=TRUE</code> to add a common legend. (See examples below.)
</p>
<p><strong>Almost cloropleths too:</strong> It should be noted that this image function is slightly
different than a cloropleth map because
the legend is assuming that a continous scale has been discretized into a series of colors.
To make the image.plot function as a cloropleth graphic one would of course use the
<code>breaks</code> option
and for clarity perhaps code the different regions as different integer values.
In addition, for publication quality one would want to use the <code>legend.args</code> to
add more descriptive labels at the midpoints in the color strip.
</p>
<p><strong>Relationship of x, y and z:</strong>
If the z component is a matrix then the user should be aware that
this function locates the matrix element z[i,j] at the grid locations
(x[i], y[j]) this is very different than simply listing out the
matrix in the usual row column tabular form. See the example below
for details on the difference in formatting. What does one do
if you do not really have the "z" values on a regular grid? See the
functions <code>quilt.plot.Rd</code> and <code>as.image</code> to discretise
irregular observations to a grid. If the values makes sense as points on
a smooth surface see <code>Tps</code> and <code>fastTps</code> for surface interpolation.
</p>
<p><strong>Adding separate color to indicate the grid box boundaries.</strong> Sometimes you want to show to the grid box borders to emphasize this is not a smooth surface. To our knowledge there is no easy way to do this as an option in <code>image</code>. But if your image is formatted in the "poly image" style where x and y are also matrices you can use the polyimage (see the <code>border</code> argument above) option to draw in boundaries.
</p>
<p><strong>Grids with unequally spacing – quadrialteral pixels:</strong>
If x and y are matrices that are a smooth transformation of a regular grid then
z[i,j] can be interperted as representing the average value in a quadrilateral that is centered at x[i,j] and
y[i,j] (<code>midpoint</code> TRUE). The details of how this cell is found
are buried in <code>poly.image</code> but it it essentially found using midpoints between the centers. If <code>midpoint</code> is FALSE then x
and y are interpreted as the corners of the quadrilateral cells. But
what about z? The four values of z are now averaged to represent a
value at the midpoint of the cell and this is what is used for
plotting. Quadrilateral grids were added to help with plotting
the gridded output of geophysical models where the regular grid is
defined according to one map projection but the image plotting is required
in another projection. Typically the regular grid becomes distorted in
a smooth way when this happens. See the regional climate example for
a illustration of this application. One can add border colors in this case
easily because these choices are just passed onto the polygon function.
</p>
<p><strong>Adding the pixel grid for rectangular images:</strong>
For adding the grid of pixel borders to a rectangular image try this example
after calling <code>image.plot</code>.
</p>
<pre>
dx <- x[2] - x[1]
dy <- y[2] - y[1]
xtemp<- seq( min( x)- dx/2, max(x)+ dx/2,
length.out = length(x) +1)
ytemp<- seq( min( y)- dy/2, max(y)+ dy/2,
length.out = length(y) +1)
xline( xtemp, col="grey", lwd=2)
yline( ytemp, col="grey", lwd=2)
</pre>
<p>Here <code>x</code> and <code>y</code> here are the x and y grid values from the image list.
</p>
<p><strong>Fine tuning color scales:</strong> This function gives some flexibility in
tuning the color scale to fit the rendering of z values. This can
either be specially designed color scale with specific colors ( see
help on <code>designer.colors</code>), positioning the colors at specific
points on the [0,1] scale, or mapping distinct colors to intervals of
z. The examples below show how to do each of these. In addition, by
supplying <code>lab.break</code> strings or axis parameters one can
annotate the legend axis in an informative matter.
</p>
<p><strong>Adding just the legend strip:</strong>
Note that to add just the legend strip all the numerical information one
needs is the <code>zlim</code> argument and the color table! See examples for tricks in positioning.
</p>
<p><strong>About color tables:</strong>
We like <code>tim.colors</code>
as a default color scale and so if this what you use this can be omitted. Unfortunately this is not the default for the <code>image</code> function. The
topographic color scale (<code>topo.colors</code>) is
also a close second showing our geophysical bias.
Users may find <code>larry.colors</code> useful for coding distinct regions
in the style of a cloropleith map. See also
<code>terrain.colors</code> for a subset of the topo ones and <code>designer.colors</code> to "roll
your own" color table. One nice option in this last function is to fix color transitions at
particular quantiles of the data rather than at equally spaced
intervals. For color choices see how the <code>nlevels</code> argument figures
into the legend and main plot number of colors. Also see the <code>colors</code> function
for a listing of all the colors that come with the R base environment.
</p>
<p><strong>The details of placing the legend and
dividing up the plotting real estate:</strong>
It is surprising how hard it is 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.
</p>
<p><code>legend.width</code> and <code>legend.mar</code> are in units of character
spaces. These units are helpful in thinking about axis labels that
will be put into these areas. To add more or less space between the
legend and the image plot alter the mar parameters. The default mar
settings (5.1,5.1,5.1,2.1) leaves 2.1 spaces for vertical legends and
5.1 spaces for horizontal legends.
</p>
<p>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 image.plot and adding information the next plot that is made may
have the slightly smaller plotting region set by the image plotting.
The user should set <code>reset.graphics=TRUE</code> to avoid the plotting size
from changing. The disadvantage, however, of resetting the graphics
is that one can no longer add additional graphics elements to the image
plot. Note that filled.contour always resets the graphics but provides
another mechanism to pass through plotting commands. Apparently
<code>filled.contour</code>, while very pretty, does not work for multiple plots.
<code>levelplot</code> that is part of the lattice package has a very
similar function to image.plot and a formula syntax in the call.
</p>
<p>By keeping the <code>zlim</code> argument the same across images one can generate the
same color scale. (See the <code>image</code> help file.) One useful technique for a
panel of images is to just draw the images with good old <code>image</code>
and then use image.plot to add a legend to the last plot. (See example
below for messing with the outer margins to make this work.)
Usually a square plot (<code>pty="s"</code>) done in a rectangular plot region will
have room for the legend stuck to the right side without any other
adjustments. See the examples below for more complicated arrangements
of multiple image plots and a summary
legends.
</p>
<h3>Side Effects</h3>
<p>After exiting, the
plotting region may be changed to make it possible to add more features to
the plot. To be explicit, <code>par()\$plt</code> may be changed to reflect a
smaller plotting region that has accommodated room for the legend subplot.
</p>
<p>If <code>xlim</code> and <code>ylim</code> are specified the pixels may overplot the axis lines.
Just use the <code>box</code> function to redraw them.
</p>
<h3>See Also</h3>
<p> image, poly.image, filled.contour, quilt.plot, plot.surface,
add.image, colorbar.plot, tim.colors, designer.colors </p>
<h3>Examples</h3>
<pre>
x<- 1:10
y<- 1:15
z<- outer( x,y,"+")
image.plot(x,y,z)
# or
obj<- list( x=x,y=y,z=z)
image.plot(obj, legend.lab="Sverdrups")
# add some points on diagonal using standard plot function
#(with some clipping beyond 10 anticipated)
points( 5:12, 5:12, pch="X", cex=3)
# adding breaks and distinct colors for intervals of z
# with and without lab.breaks
brk<- quantile( c(z))
image.plot(x,y,z, breaks=brk, col=rainbow(4))
# annotate legend strip at break values and add a label
image.plot(x,y,z, breaks=brk, col=rainbow(4),
lab.breaks=names(brk))
#
# compare to
zp <-quantile(c(z), c( .05, .1,.5, .9,.95))
image.plot(x,y,z,
axis.args=list( at=zp, labels=names(zp) ) )
# a log scaling for the colors
ticks<- c( 1, 2,4,8,16,32)
image.plot(x,y,log(z), axis.args=list( at=log(ticks), labels=ticks))
# see help file for designer.colors to generate a color scale that adapts to
# quantiles of z.
# Two add some color scales together here is an example of 5 blues to white to 5 reds
# with white being a specific size.
colorTable<- designer.colors(11, c( "blue","white", "red") )
# breaks with a gap of 10 to 17 assigned the white color
brks<- c(seq( 1, 10,,6), seq( 17, 25,,6))
image.plot( x,y,z,breaks=brks, col=colorTable)
#
#fat (5 characters wide) and short (50% of figure) color bar on the bottom
image.plot( x,y,z,legend.width=5, legend.shrink=.5, horizontal=TRUE)
# adding a label with all kinds of additional arguments.
# use side=4 for vertical legend and side= 1 for horizontal legend
# to be parallel to axes. See help(mtext).
image.plot(x,y,z,
legend.args=list( text="unknown units",
col="magenta", cex=1.5, side=4, line=2))
# and finally add some grid lines
dx <- x[2] - x[1]
dy <- y[2] - y[1]
xtemp<- seq( min( x)- dx/2, max(x)+ dx/2,
length.out = length(x) +1)
ytemp<- seq( min( y)- dy/2, max(y)+ dy/2,
length.out = length(y) +1)
xline( xtemp, col="grey", lwd=2)
yline( ytemp, col="grey", lwd=2)
#
#### example using a irregular quadrilateral grid
data( RCMexample)
image.plot( RCMexample$x, RCMexample$y, RCMexample$z[,,1])
ind<- 50:75 # make a smaller image to show bordering lines
image.plot( RCMexample$x[ind,ind], RCMexample$y[ind,ind], RCMexample$z[ind,ind,1],
border="grey50", lwd=2)
#### multiple images with a common legend
set.panel()
# Here is quick but quirky way to add a common legend to several plots.
# The idea is leave some room in the margin and then over plot in this margin
par(oma=c( 0,0,0,4)) # margin of 4 spaces width at right hand side
set.panel( 2,2) # 2X2 matrix of plots
# now draw all your plots using usual image command
for ( k in 1:4){
data<- matrix( rnorm(150), 10,15)
image( data, zlim=c(-4,4), col=tim.colors())
# and just for fun add a contour plot
contour( data, add=TRUE)
}
par(oma=c( 0,0,0,1))# reset margin to be much smaller.
image.plot( legend.only=TRUE, zlim=c(-4,4))
# image.plot tricked into plotting in margin of old setting
set.panel() # reset plotting device
#
# Here is a more learned strategy to add a common legend to a panel of
# plots consult the split.screen help file for more explanations.
# For this example we draw two
# images top and bottom and add a single legend color bar on the right side
# first divide screen into the figure region (left) and legend region (right)
split.screen( rbind(c(0, .8,0,1), c(.8,1,0,1)))
# now subdivide up the figure region into two parts
split.screen(c(2,1), screen=1)-> ind
zr<- range( 2,35)
# first image
screen( ind[1])
image( x,y,z, col=tim.colors(), zlim=zr)
# second image
screen( ind[2])
image( x,y,z+10, col=tim.colors(), zlim =zr)
# move to skinny region on right and draw the legend strip
screen( 2)
image.plot( zlim=zr,legend.only=TRUE, smallplot=c(.1,.2, .3,.7),
col=tim.colors())
close.screen( all=TRUE)
# you can always add a legend arbitrarily to any plot;
# note that here the plot is too big for the vertical strip but the
# horizontal fits nicely.
plot( 1:10, 1:10)
image.plot( zlim=c(0,25), legend.only=TRUE)
image.plot( zlim=c(0,25), legend.only=TRUE, horizontal =TRUE)
# combining the usual image function and adding a legend
# first change margin for some more room
## Not run:
par( mar=c(10,5,5,5))
image( x,y,z, col=topo.colors(64))
image.plot( zlim=c(0,25), nlevel=64,legend.only=TRUE, horizontal=TRUE,
col=topo.colors(64))
## End(Not run)
#
#
# sorting out the difference in formatting between matrix storage
# and the image plot depiction
# this really has not much to do with image.plot but I hope it is useful
A<- matrix( 1:48, ncol=6, nrow=8)
# first column of A will be 1:8
# ... second is 9:16
image.plot(1:8, 1:6, A)
# add labels to each box
text( c( row(A)), c( col(A)), A)
# and the indices ...
text( c( row(A)), c( col(A))-.25,
paste( "(", c(row(A)), ",",c(col(A)),")", sep=""), col="grey")
# "columns" of A are horizontal and rows are ordered from bottom to top!
#
# matrix in its usual tabular form where the rows are y and columns are x
image.plot( t( A[8:1,]), axes=FALSE)
</pre>
<hr /><div style="text-align: center;">[Package <em>fields</em> version 9.9 <a href="00Index.html">Index</a>]</div>
</body></html>