autopoints {autoimage}

Automatic facetting of multiple projected scatterplots

Description

autopoints plots a sequence of scatterplots (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 customization. See the Examples below or execute vignette("autopoints") to better understand the possibilities.

Usage

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

Arguments

x

Numeric vectors of coordinates at which the values in z are measured.

y

Numeric vectors of coordinates at which the values in z are measured.

z

A numeric vector containing the values to be plotted.

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 lratio = 0.2.

outer.title

A title related to all of the images that is plotted in the outer margin of the figure.

n

integer giving the desired number of intervals. Non-integer values are rounded down.

...

Additional arguments passed to the plot. e.g., xlab, ylab, xlim, ylim, zlim, etc.

Details

The n argument specifies the desired number of color partitions, but may not be exact. This is used to create "pretty" color scale tick labels using the pretty function. If zlim or breaks are provided, then the pretty function is not used to determine the color scale tick lables, and the user may need to manually specify breaks to get the color scale to have "pretty" tick labels. If col is specified, then n is set to length(col), but the functions otherwise works the same (i.e., pretty tick labels are not automatic if zlim or breaks are specified.

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

If multiple scatterplots are to be plotted (i.e., if z is a matrix with more than 1 column), then the main argument can be a vector with length matching ncol(z), and each successive element of the vector will be used to add a title to each successive scatterplot. See the Examples.

Additionally, if common.legend = FALSE, then separate z limits and breaks for the z-axis of each image can be provided as a list. Specifically, if ncol(z) == 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. Similarly, the breaks argument should be a list of length k, and each element of the list should be a vector specifying the breaks for the color scale for each plot. Note that the length of each element of breaks should be 1 greater then the number of colors in the color scale.

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 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 autpoints 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.

See Also

autoimage, heat_ppoints

Examples

data(co, package = "gear")
easting = co$easting
northing = co$northing
# heated scatterplot for Aluminum and Cadmium
autopoints(easting, northing, co[,c("Al", "Ca")],
           common.legend = FALSE, map = "state",
           main = c("Al", "Ca"), lratio = 0.2,
           legend.mar = c(0.3, 0.1, 0.1, 0.1))

# more complicated heat scatterplot for Aluminum and
# Cadmium used more advanced options
autopoints(co$lon, co$lat, co[,c("Al", "Ca")],
          common.legend = FALSE, 
          map = "county", main = c("Aluminum", "Cadmium"),
          proj = "bonne", parameters = 40,
          text = list(x = c(-104.98, -104.80), y = c(39.74, 38.85), 
                      labels = c("Denver", "Colorado Springs")),
          text.args = list(col = "blue"))