pimage {autoimage}

Display image for projected coordinates

Description

pimage plots an image for (potentially) projected locations. A color scale is automatically provided with the image. The function is essentially an extension of the image function and the x and y locations can be irregularly-spaced locations, sequences of increasing values for locations on a regular grid, or matrices (with dimensions matching those of z) for locations on an irregular grid. Functionality for automatic projection is provided.

Usage

pimage(
  x,
  y,
  z,
  legend = "horizontal",
  proj = "none",
  parameters,
  orientation,
  lratio = 0.2,
  map = "none",
  ...
)

Arguments

x, y

Locations of grid points at which the values in z are measured. The values must be finite and non-missing. These arguments can be either vectors or matrices depending on the type of data to be displayed. See Details.

z

A numeric or logical vector or matrix containing the values to be plotted (NAs are allowed).

legend

A character string indicating where the color scale should be placed. The default is "horizontal". The other valid options are "none" and "vertical".

proj

A character string indicating what projection should be used for the included x and y coordinates. The default is "none". The other valid choices correspond to the "projection" argument in the mapproject function, which is used for the projection.

parameters

A numeric vector specifying the values of the parameters argument in the mapproject. This may be necessary when proj != "none".

orientation

A vector c(latitude,longitude,rotation) which describes where the "North Pole" should be when computing the projection. See mapproject for more details.

lratio

A numeric value indicating the ratio of the smaller dimension of the legend scale to the width of the image. Default is lratio = 0.2.

map

The name of the map to draw on the image. Default is "none". Other options include "world", "usa", "state", "county", "france", "nz" (New Zealand), "italy", "lakes", and "world2", all from the maps package.

...

Additional arguments passed to the image or poly.image functions. e.g., xlab, ylab, xlim, ylim, zlim, etc. Additionally, arguments that can be used to further customize the plot (like adding lines or points), as described in Details and Examples.

Details

If x, y, and z are numeric vectors of the same length, then the mba.surf function is used to predict the response on a regular grid using multilevel B-splines before constructing the image. This interpolation can be customized by passing interp.args through .... interp.args should be a named list with component matching the non xyz arguments of the mba.surf function.

If x are y are vectors of increasing values and nrow(z) == length(x) and ncol(z) == length(y), then an image on a regular grid is constructed.

If x, y and z are matrices with the same dimensions, then an image for irregularly gridded data is constructed.

When proj != "none", the mapproject function is used to project the x and y coordinates. In that case, proj must correspond to one of the choices for the projection argument in the mapproject function. Necessary arguments for mapproject should be provided via the parameters and orientation arguments. See Examples and the mapproject function.

Valid options for legend are "none", "horizontal", and "vertical". If legend = "none", then no color scale is provided. If legend = "horizontal", then a color scale is included under the image. If legend = "vertical", then a color scale is added to the right of the image.

Lines can be added to each image by passing the lines argument through .... In that case, lines should be a list with components x and y specifying the locations to draw the lines. The appearance of the plotted lines can be customized by passing a named list called lines.args through .... The components of lines.args should match the arguments of lines. See Examples.

Points can be added to each image by passing the points argument through .... In that case, points should be a list with components x and y specifying the locations to draw the points. The appearance of the plotted points can be customized by passing a named list called points.args through .... The components of points.args should match the components of points. See Examples.

Text can be added to each image by passing the text argument through .... In that case, text should be a list with components x and y specifying the locations to draw the text, and labels, a component specifying the actual text to write. The appearance of the plotted text can be customized by passing a named list called text.args through .... The components of text.args should match the components of text. See Examples.

The legend scale can be modified by passing legend.axis.args through .... The argument should be a named list corresponding to the arguments of the axis function. See Examples.

The image axes can be modified by passing axis.args through .... The argument should be a named list corresponding to the arguments of the axis function. The exception to this is that arguments xat and yat can be specified (instead of at) to specify the location of the x and y ticks. If xat or yat are specified, then this overrides the xaxt and yaxt arguments, respectively. See the paxes function to see how axis.args can be used.

The legend margin can be customized by passing legend.mar to pimage through .... This should be a numeric vector indicating the margins of the legend, identical to how par("mar") is specified.

The various options of the labeling, axes, and legend are largely independent. e.g., passing col.axis through ... will not affect the axis unless it is passed as part of the named list axis.args. However, one can set the various par options prior to plotting to simultaneously affect the appearance of multiple aspects of the plot. See Examples. After plotting, reset.par() can be used to reset the graphics device options to their default values.

See Also

image, image.plot, axis

Examples

# image plot for data on an irregular grid
pimage(lon, lat, tasmax[,,1], legend = "h", map = "world")
# same plot but with projection and vertical legend
pimage(lon, lat, tasmax[,,1], legend = "v", map = "world", 
       proj = "bonne", parameters = 45)
# different projection
pimage(lon, lat, tasmax[,,1], proj = "albers",
       parameters = c(33, 45), map = "world")

reset.par() # reset graphics device
# image plot for non-gridded data
data(co, package = "gear")
pimage(co$longitude, co$latitude, co$Al)

# show observed locations on image,
# along with Colorado border, locations of Denver and Colorado 
# Springs
data(copoly)
copoints <- list(x = co$lon, y = co$lat)
pimage(co$longitude, co$latitude, co$Al, 
       lines = copoly, 
       lines.args = list(lwd = 2, col = "grey"),
       points = copoints, 
       points.args = list(pch = 21, bg = "white"),
       text = list(x = c(-104.98, -104.80), y = c(39.74, 38.85), 
                   labels = c("Denver", "Colorado Springs")), 
       text.args = list(col = "purple"),
       xlim = c(-109.1, -102),
       ylim = c(36.8, 41.1))

# image plot for data on irregular grid
# notice the poor axis labeling
data(narccap)
pimage(lon, lat, tasmax[,,1], proj = "bonne",
       parameters = 45, map = "world")
# same plot but customize axis labeling 
# need to extend horizontally-running axis lines
# farther to the west and east
# also need the vertically-running lines
# to run further north/sount
# will need manual adjusting depending on size
# of current device 
pimage(lon, lat, tasmax[,,1], proj = "bonne",
       parameters = 45, map = "world", 
       xaxp = c(-200, 0, 10), yaxp = c(-10, 80, 9))

# the same effect can be acheived by specifying axis.args
# we also modify the color and size of the axis labels
pimage(lon, lat, tasmax[,,1], proj = "bonne",
       parameters = 45, map = "world", 
       axis.args = list(xat = seq(-200, 0, by = 20),
                        yat = seq(0, 70, by = 10),
                        col.axis = "blue", 
                        cex.axis = 0.5))

# modify colors of legend, map, line type for grid lines
# and customize axis
pimage(lon, lat, tasmax[,,1], 
       legend = "v", proj = "bonne", parameters = 45,
       map = "state",
       paxes.args = list(lty = 3),
       legend.axis.args = list(col = "blue", col.axis = "blue"),
       col = fields::tim.colors(64),
       xlab = "longitude",
       ylab = "latitude",
       main = "temperature (K)")
reset.par() # reset graphics device

# change many aspects of plot appearance using par
par(cex.axis = 0.5, cex.lab = 0.5, mgp = c(1.5, 0.5, 0),
    mar = c(2.1, 2.1, 4.1, 0.2), col.axis = "orange",
    col.main = "blue", family = "mono")
pimage(lon, lat, tasmax[,,1])
title("very customized plot")
reset.par()