hexbinplot {hexbin}

Trellis Hexbin Displays

Description

Display of hexagonally binned data, as implemented in the hexbin packge, under the Trellis framework, with associated utilities. hexbinplot is the high level generic function, with the "formula" method doing the actual work. prepanel.hexbinplot and panel.hexbinplot are associated prepanel and panel functions. hexlegendGrob produces a suitable legend.

Usage

hexbinplot(x, data, ...)

## S3 method for class 'formula'
hexbinplot(x, data = NULL,
           prepanel = prepanel.hexbinplot,
           panel = panel.hexbinplot,
	   groups = NULL,
           aspect = "xy",
           trans = NULL,
           inv = NULL,
           colorkey = TRUE,
           ...,
           maxcnt,
           legend = NULL,
           legend.width = TRUE,
           subset)

prepanel.hexbinplot(x, y, type = character(0), ...)

panel.hexbinplot(x, y, ..., groups = NULL)

hexlegendGrob(legend = 1.2,
              inner = legend / 5,
              cex.labels = 1,
              cex.title = 1.2,
              style = "colorscale",
              minarea = 0.05, maxarea = 0.8,
              mincnt = 1, maxcnt,
              trans = NULL, inv = NULL,
              colorcut = seq(0, 1, length = 17),
              density = NULL, border = NULL, pen = NULL,
              colramp = function(n) { LinGray(n,beg = 90,end = 15) },
              ...,
              vp = NULL,
              draw = FALSE)

Arguments

x

For hexbinplot, the object on which method dispatch is carried out.

For the "formula" methods, a formula describing the form of conditioning plot. Formulas that are valid for xyplot are acceptable.

In panel.hexbinplot, the x variable.

y

In panel.hexbinplot, the y variable.

data

For the formula method, a data frame containing values for any variables in the formula, as well as groups and subset if applicable (using groups currently causes an error with the default panel function). By default, the environment where the function was called from is used.

minarea, maxarea, mincnt, maxcnt, trans, inv, colorcut, density, border, pen, colramp, style

see gplot.hexbin

prepanel, panel, aspect

See xyplot. aspect="fill" is not allowed. The current default of "xy" may not always be the best choice, often aspect=1 will be more reasonable.

colorkey

logical, whether a legend should be drawn. Currently a legend can be drawn only on the right.

legend.width, legend

width of the legend in inches when style is "nested.lattice" or "nested.centroids". The name legend.width is used to avoid conflict with the standard trellis argument legend. It is possible to specify additional legends using the legend or key arguments as long as they do not conflict with the hexbin legend (i.e., are not on the right).

inner

Inner radius in inches of hexagons in the legend when style is "nested.lattice" or "nested.centroids".

cex.labels, cex.title

in the legend, multiplier for numeric labels and text annotation respectively

type

character vector controlling additional augmentation of the display. A "g" in type adds a reference grid, "r" adds a regression line (y on x), "smooth" adds a loess smooth

draw

logical, whether to draw the legend grob. Useful when hexlegendGrob is used separately

vp

grid viewport to draw the legend in

...

extra arguments, passed on as appropriate. Arguments to gplot.hexbin, xyplot, panel.hexbinplot and hexlegendGrob can be supplied to the high level hexbinplot call.

panel.hexbinplot calls one of two (unexported) low-level functions depending on whether groups is supplied (although specifying groups currently leads to an error). Arguments of the appropriate function can be supplied; some important ones are

xbins:

number of hexagons covering x values. The number of y-bins depends on this, the aspect ratio, and xbnds and ybnds

xbnds, ybnds:

Numeric vector specifying range of values that should be covered by the binning. In a multi-panel display, it is not necessarily a good idea to use the same bounds (which along with xbins and the aspect ratio determine the size of the hexagons) for all panels. For example, when data is concentrated in small subregions of different panels, more detail will be shown by using smaller hexagons covering those regions. To control this, xbnds and ybnds can also be character strings "panel" or "data" (which are not very good names and may be changed in future). In the first case, the bounds are taken to be the limits of the panel, in the second case, the limits of the data (packet) in that panel. Note that all panels will have the same limits (enough to cover all the data) by default if relation="free" in the standard trellis argument scales, but not otherwise.

groups

in hexbinplot, a grouping variable that is evaluated in data, and passed on to the panel function.

subset

an expression that is evaluated in evaluated in data to produce a logical vector that is used to subset the data before being used in the plot.

Details

The panel function panel.hexbinplot creates a hexbin object from data supplied to it and plots it using grid.hexagons. To make panels comparable, all panels have the same maxcnt value, by default the maximum count over all panels. This default value can be calculated only if the aspect ratio is known, and so aspect="fill" is not allowed. The default choice of aspect ratio is different from the choice in hexbin (namely, 1), which may sometimes give better results for multi-panel displays. xbnds and ybnds can be numeric range vectors as in hexbin, but they can also be character strings specifying whether all panels should have the same bins. If they are not, then bins in different panels could be of different sizes, in which case style="lattice" and style="centroids" should be interpreted carefully.

The dimensions of the legend and the size of the hexagons therein are given in absolute units (inches) by legend.width and inner only when style is "nested.lattice" or "nested.centroids". For other styles, the dimensions of the legend are determined relative to the plot. Specifically, the height of the legend is the same as the height of the plot (the panel and strip regions combined), and the width is the minimum required to fit the legend in the display. This is different in some ways from the hexbin implementation. In particular, the size of the hexagons in the legend are completely unrelated to the sizes in the panels, which is pretty much unavoidable because the sizes need not be the same across panels if xbnds or ybnds is "data". The size of the hexagons encode information when style is "lattice" or "centroids", consequently a warning is issued when a legend is drawn with wither of these styles.

Value

hexbinplot produces an object of class "trellis". The update method can be used to update components of the object and the print method (usually called by default) will plot it on an appropriate plotting device. hexlegendGrob produces a "grob" (grid object).

Author(s)

Deepayan Sarkar [e-mail]

See Also

hexbin, xyplot

Examples

mixdata <-
    data.frame(x = c(rnorm(5000),rnorm(5000,4,1.5)),
               y = c(rnorm(5000),rnorm(5000,2,3)),
               a = gl(2, 5000))
hexbinplot(y ~ x, mixdata, aspect = 1,
           trans = sqrt, inv = function(x) x^2)
hexbinplot(y ~ x | a, mixdata)
hexbinplot(y ~ x | a, mixdata, style = "lattice",
           xbnds = "data", ybnds = "data")
hexbinplot(y ~ x | a, mixdata, style = "nested.centroids")
hexbinplot(y ~ x | a, mixdata, style = "nested.centroids",
           border = FALSE, type = c("g", "smooth"))