R: Automatic facetting of multiple projected images

autoimage {autoimage}

R Documentation

Automatic facetting of multiple projected images

Description

autoimage plots a sequence of images (with possibly projected coordinates) while also automatically plotting a color scale matching the image colors to the values of z. Many options are available for legend customization. The coordinates can be irregularly spaced, on a regular grid, or on an irregular grid. z can be a numeric vector, matrix, or array, depending on the context.

Usage

autoimage(
  x,
  y,
  z,
  legend = "horizontal",
  proj = "none",
  parameters,
  orientation,
  common.legend = TRUE,
  map = "none",
  size,
  lratio,
  outer.title,
  ...
)

Arguments

`x`	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.
`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.
`common.legend`	A logical value indicating whether a common legend scale should be used for all images provided in the `z` array. Default is `TRUE`. If `FALSE`, a separate legend is used for each image.
`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.
`size`	A vector of length two indicating the number of rows and columns that should be used for the series of image data in `z`. Note that `prod(size)` must match the length of the third dimension of `z` (if it is an array), or `c(1, 1)` if `z` is a matrix.
`lratio`	A numeric value indicating the ratio of the smaller dimension of the legend scale to the width of the image. Default is 0.1 + 0.1 `* k`, where `k` is the number of image rows if `legend == "horizontal"` or the number of image columns if `legend == "vertical"`.
`outer.title`	A title related to all of the images that is plotted in the outer margin of the figure.
`...`	Additional arguments passed to the `image` or `poly.image` functions. e.g., `xlab`, `ylab`, `xlim`, `ylim`, `zlim`, etc.

Details

The mapproject function is used to project the x and y coordinates when proj != "none".

If multiple images are to be plotted (i.e., if z is an array), then the main argument can be a vector with length matching dim(z)[3], and each successive element of the vector will be used to add a title to each successive image plotted. See the Examples.

Additionally, if common.legend = FALSE, then separate limits for the z-axis of each image can be provided as a list. Specifically, if dim(z)[3] == k, then zlim should be a list of length k, and each element of the list should be a 2-dimensional vector providing the lower and upper limit, respectively, of the legend for each image. Alternatively, if zlim is a list of length k, then common.legend is set to FALSE.

The range of zlim is cut into n partitions, where n is the length of col.

It is generally desirable to increase lratio when more images are plotted simultaneously.

The multiple plots are constructed using the autolayout function, which is incompatible with the mfrow and mfcol arguments in the par function and is also incompatible with the split.screen function.

The mtext.args argument can be passed through ... in order to customize the outer title. This should be a named list with components matching the arguments of mtext.

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 for pimage. After plotting, reset.par() can be used to reset the graphics device options to their default values.

Examples

data(narccap)
# restructure data for 2 images
tasmax2 <- tasmax[,,1:2]

# plot irregularly gridded images with separate legends
# and usa border
autoimage(lon, lat, tasmax2, common.legend = FALSE, map = "usa")

# plot irregularly gridded images with common legend and world lines
# customize world lines
# add and customize title
autoimage(lon, lat, tasmax2, map = "world", 
          lines.args = list(col = "white", lwd = 2),
          outer.title = "Maximum Daily Surface Air Temperature (K)",
          mtext.args = list(col = "blue", cex = 2))

# plot irregularly-spaced responsed as images with separate legends
# and county borders.  Add observed data locations with custom point
# options.  Add text at locations of Denver and Colorado Springs.
data(co, package = "gear")
autoimage(co$lon, co$lat, co[,c("Al", "Ca")], common.legend = FALSE, 
          map = "county", main = c("Aluminum", "Cadmium"),
          points = list(x = co$lon, y = co$lat),
          points.args = list(pch = 20, col = "white"),
          text = list(x = c(-104.98, -104.80), y = c(39.74, 38.85), 
                      labels = c("Denver", "Colorado Springs")),
          text.args = list(col = "red"))

# customize margins and lratio for large plot
# also use projection
# specify manual lines (though in this case it is the same as using 
# map = "world")
data(worldMapEnv, package = "maps")
worldpoly <- maps::map("world", plot = FALSE)
par(mar = c(1.1, 4.1, 2.1, 1.1))
autoimage(lon, lat, tasmax, lines = worldpoly, 
          proj = "bonne", parameters = 40,
          main = c("day 1", "day 2", "day 3", "day 4", "day 5"),
          ylab = "",
          axes = FALSE,
          lratio = 0.5)