heat_ppoints {autoimage}

Display colored scatterplot for projected coordinates

Description

heat_ppoints plots a "heated" scatterplot for (potentially) projected locations. A color scale is automatically provided with the scatterplot. The function is similar in purpose to pimage, but the z-values are not interpolated. The color scale can be changed by passing a vector of colors to the col argument.

Usage

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

Arguments

x, 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.

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.

n

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

...

Additional arguments passed to the plot function. 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

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 plot. If legend = "vertical", then a color scale is added to the right of the plot.

Lines can be added to each plot 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 plot 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 heat_ppoints 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

plot, axis, pimage

Examples

data(co, package = "gear")
# heated scatterplot for data on an irregular grid
heat_ppoints(co$lon, co$lat, co$Al, legend = "v", map = "state")
reset.par()

# change color scale
heat_ppoints(co$lon, co$lat, co$Al, col = cm.colors(5))
reset.par()

# Use custom border, x and y limits, breaks for legend axis
data(copoly)
heat_ppoints(co$lon, co$lat, co$Al, legend = "h",
       xlab = "longitude", ylab = "latitude",
       proj = "bonne", parameters = 40,
       lines = copoly,
       lines.args = list(lwd = 2, col = "grey"),
       xlim = c(-109.1, -102),
       ylim = c(36.8, 41.1),
       breaks = seq(0, 10, len = 6))
reset.par()