Bivariate Binning into Hexagonal Cells

DESCRIPTION:

Creates an object of class hexbin. Its basic components are a cell identifier and a count of the points falling into each occupied cell.

USAGE:

hexbin(x, y, xbins=30, shape=1, xlim=range(x), ylim=range(y))

REQUIRED ARGUMENTS:

x
numeric vector. Usually the first (horizontal) coordinate of bivariate data to be binned.
y
numeric vector. Usually the second (vertical) coordinate of bivariate data to be binned.

OPTIONAL ARGUMENTS:

xbins
number of bins partitioning the range of x values.
shape
height to width ratio for the resulting plotting region. This parameter is used in determining the number of bins in the y-direction given xbins, the number of bins in the x-direction. The default value shape=1 makes the hexagons appear equal-sided when plotted.
xlim
the horizontal limits of the binning region in units of x. By default these are the minimum and maximum values of x.
ylim
the vertical limits of the binning region in y units. This defaults to the minimum and maximum values of y.

VALUE:

an object of class "hexbin". This is a data frame with the following columns:
cell
vector of cell identifiers that can be mapped into the bin centers in data units
count
a vector with the points count for each corresponding cell.
xcenter
the x center of mass (average of x values) for the cell.
ycenter
the y center of mass (average of y values) for the cell.

The returned data frame has attributes:
class
the class of the returned object, "hexbin".
call
the original call to hexbin which generated the object.
xbins
number of hexagons along the x axis. Same as the input value for xbins. Hexagons inner diameter equals diff(xlim)/xbins in x units
dims
the i-th and j-th limits of count if treated as a matrix ( count[i,j]).
xlim
same as the input value for xlim.
ylim
same as the input value for ylim.
shape
same as the input value for shape.

DETAILS:

Returns counts for non-empty cells. The plot shape must be maintained for hexagons to appear with equal sides. Calculations are in single precision.

REFERENCES:

Carr, D. B., Littlefield, R. J., Nicholson, W. L. and Littlefield, J. S. (1987). Scatterplot matrix techniques for large N. Journal American Statistical Association 83, 424-436.

SEE ALSO:

, , , , , , .

EXAMPLES:

x <- rnorm(10000)
y <- rnorm(10000)
bin1 <- hexbin(x, y)
trellis.device()
plot(bin1,style="nested.centroids")
# Lower resolution binning and overplotting with counts
bin2 <- hexbin(x, y, xbins=25)
plot.output <- plot(bin2, style="latt", minarea=1, maxarea=1, density=0,
        border=T)
xy <- cell2xy(bin2)
add.to.hexbin(plot.output,
   text(xy$x, xy$y, as.character(bin2$count), adj=.5, cex=.3))