image                package:graphics                R Documentation

_D_i_s_p_l_a_y _a _C_o_l_o_r _I_m_a_g_e

_D_e_s_c_r_i_p_t_i_o_n:

     Creates a grid of colored or gray-scale rectangles with colors
     corresponding to the values in 'z'.  This can be used to display
     three-dimensional or spatial data aka _images_. This is a generic
     function.

     The functions 'heat.colors', 'terrain.colors' and 'topo.colors'
     create heat-spectrum (red to white) and topographical color
     schemes suitable for displaying ordered data, with 'n' giving the
     number of colors desired.

_U_s_a_g_e:

     image(x, ...)

     ## Default S3 method:
     image(x, y, z, zlim, xlim, ylim, col = heat.colors(12),
           add = FALSE, xaxs = "i", yaxs = "i", xlab, ylab,
           breaks, oldstyle = FALSE, ...)

_A_r_g_u_m_e_n_t_s:

     x,y: locations of grid lines at which the values in 'z' are
          measured.  These must be finite, non-missing and in
          (strictly) ascending order.  By default, equally spaced
          values from 0 to 1 are used.  If 'x' is a 'list', its
          components 'x$x' and 'x$y' are used for 'x' and 'y',
          respectively. If the list has component 'z' this is used for
          'z'.

       z: a matrix containing the values to be plotted ('NA's are
          allowed).  Note that 'x' can be used instead of 'z' for
          convenience.

    zlim: the minimum and maximum 'z' values for which colors should be
          plotted, defaulting to the range of the finite values of 'z'.
          Each of the given colors will be used to color an equispaced
          interval of this range. The _midpoints_ of the intervals
          cover the range, so that values just outside the range will
          be plotted.

xlim, ylim: ranges for the plotted 'x' and 'y' values, defaulting to
          the ranges of 'x' and 'y'.

     col: a list of colors such as that generated by 'rainbow',
          'heat.colors', 'topo.colors', 'terrain.colors' or similar
          functions.

     add: logical; if 'TRUE', add to current plot (and disregard the
          following arguments).  This is rarely useful because 'image'
          'paints' over existing graphics.

xaxs, yaxs: style of x and y axis.  The default '"i"' is appropriate
          for images.  See 'par'.

xlab, ylab: each a character string giving the labels for the x and y
          axis.  Default to the 'call names' of 'x' or 'y', or to '""'
          if these were unspecified.

  breaks: a set of breakpoints for the colours: must give one more
          breakpoint than colour.

oldstyle: logical. If true the midpoints of the colour intervals are
          equally spaced, and 'zlim[1]' and 'zlim[2]' were taken to be
          midpoints.  The default is to have colour intervals of equal
          lengths between the limits.

     ...: graphical parameters for 'plot' may also be passed as
          arguments to this function, as can the plot aspect ratio
          'asp' and 'axes' (see 'plot.window').

_D_e_t_a_i_l_s:

     The length of 'x' should be equal to the 'nrow(z)+1' or 'nrow(z)'.
      In the first case 'x' specifies the boundaries between the cells:
     in the second case 'x' specifies the midpoints of the cells. 
     Similar reasoning applies to 'y'.  It probably only makes sense to
     specify the midpoints of an equally-spaced grid.  If you specify
     just one row or column and a length-one 'x' or 'y', the whole user
     area in the corresponding direction is filled.

     Rectangles corresponding to missing values are not plotted (and so
     are transparent and (unless 'add=TRUE') the default background
     painted in 'par("bg")' will show though and if that is
     transparent, the canvas colour will be seen).

     If 'breaks' is specified then 'zlim' is unused and the algorithm
     used follows 'cut', so intervals are closed on the right and open
     on the left except for the lowest interval.

     Notice that 'image' interprets the 'z' matrix as a table of
     'f(x[i], y[j])' values, so that the x axis corresponds to row
     number and the y axis to column number, with column 1 at the
     bottom, i.e. a 90 degree counter-clockwise rotation of the
     conventional printed layout of a matrix.

_N_o_t_e:

     Based on a function by Thomas Lumley tlumley@u.washington.edu.

_S_e_e _A_l_s_o:

     'filled.contour' or 'heatmap' which can look nicer (but are less
     modular), 'contour'; The 'lattice' equivalent of 'image' is
     'levelplot'.

     'heat.colors', 'topo.colors', 'terrain.colors', 'rainbow', 'hsv',
     'par'.

_E_x_a_m_p_l_e_s:

     require(grDevices) # for colours
     x <- y <- seq(-4*pi, 4*pi, len=27)
     r <- sqrt(outer(x^2, y^2, "+"))
     image(z = z <- cos(r^2)*exp(-r/6), col=gray((0:32)/32))
     image(z, axes = FALSE, main = "Math can be beautiful ...",
           xlab = expression(cos(r^2) * e^{-r/6}))
     contour(z, add = TRUE, drawlabels = FALSE)

     # Volcano data visualized as matrix. Need to transpose and flip
     # matrix horizontally.
     image(t(volcano)[ncol(volcano):1,])

     # A prettier display of the volcano
     x <- 10*(1:nrow(volcano))
     y <- 10*(1:ncol(volcano))
     image(x, y, volcano, col = terrain.colors(100), axes = FALSE)
     contour(x, y, volcano, levels = seq(90, 200, by = 5),
             add = TRUE, col = "peru")
     axis(1, at = seq(100, 800, by = 100))
     axis(2, at = seq(100, 600, by = 100))
     box()
     title(main = "Maunga Whau Volcano", font.main = 4)