R: Bivariate Binning into Hexagon Cells

hexbin {hexbin} | R Documentation

## Bivariate Binning into Hexagon Cells

### Description

Creates a `"hexbin"` object. Basic components are a cell id and a count of points falling in each occupied cell.

Basic methods are `show()`, `plot()` and `summary()`, but also `erode`.

### Usage

    hexbin(x, y, xbins = 30, shape = 1,
           xbnds = range(x), ybnds = range(y),
           xlab = NULL, ylab = NULL, IDs = FALSE)

### Arguments

`x, y` | vectors giving the coordinates of the bivariate data points to be binned. Alternatively a single plotting structure can be specified: see `xy.coords`. `NA`'s are allowed and silently omitted.
`xbins` | the number of bins partitioning the range of xbnds.
`shape` | the shape = yheight/xwidth of the plotting regions.
`xbnds, ybnds` | horizontal and vertical limits of the binning region in x or y units respectively; must be numeric vector of length 2.
`xlab, ylab` | optional character strings used as labels for `x` and `y`. If `NULL`, sensible defaults are used.
`IDs` | logical indicating if the individual cell “IDs” should be returned, see also below.

### Details

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

Note that when plotting a `hexbin` object, the grid package is used. You must use its graphics (or those from package lattice if you know how) to add to such plots.

### Value

an S4 object of class `"hexbin"`. It has the following slots:

`cell` | vector of cell ids that can be mapped into the (x,y) bin centers in data units.
`count` | vector of counts in the cells.
`xcm` | The x center of mass (average of x values) for the cell.
`ycm` | The y center of mass (average of y values) for the cell.
`xbins` | number of hexagons across the x axis. hexagon inner diameter =diff(xbnds)/xbins in x units
`shape` | plot shape which is yheight(inches) / xwidth(inches)
`xbnds` | x coordinate bounds for binning and plotting
`ybnds` | y coordinate bounds for binning and plotting
`dimen` | The i and j limits of cnt treated as a matrix cnt[i,j]
`n` | number of (non NA) (x,y) points, i.e., `sum(* @count)`.
`ncells` | number of cells, i.e., `length(* @count)`, etc
`call` | the function call.
`xlab, ylab` | character strings to be used as axis labels.
`cID` | of class, `"integer or NULL"`, only if `IDs` was true, an integer vector of length `n` where `cID[i]` is the cell number of the i-th original point `(x[i], y[i])`. Consequently, the `cell` and `count` slots are the same as the `names` and entries of `table(cID)`, see the example.

### References

Carr, D. B. et al. (1987) Scatterplot Matrix Techniques for Large N. JASA 83, 398, 424–436.

### See Also

`hcell2xy` `gplot.hexbin`, `grid.hexagons`, `grid.hexlegend`.

### Examples

    set.seed(101)
    x <- rnorm(10000)
    y <- rnorm(10000)
    (bin <- hexbin(x, y))
    ## or
    plot(hexbin(x, y + x*(x+1)/4),
         main = "(X, X(X+1)/4 + Y)  where X,Y ~ rnorm(10000)")

    ## Using plot method for hexbin objects:
    plot(bin, style = "nested.lattice")

    hbi <- hexbin(y ~ x, xbins = 80, IDs= TRUE)
    str(hbi)
    tI <- table(hbi@cID)
    stopifnot(names(tI) == hbi@cell,
                    tI  == hbi@count)

    ## NA's now work too:
    x[runif(6, 0, length(x))] <- NA
    y[runif(7, 0, length(y))] <- NA
    hbN <- hexbin(x,y)
    summary(hbN)

[Package hexbin version 1.28.1 Index]