R: Compute and Plot a 2-Dimensional Histogram

hist2d {gplots} | R Documentation

## Compute and Plot a 2-Dimensional Histogram

### Description

Compute and plot a 2-dimensional histogram.

### Usage

    hist2d(x,y=NULL, nbins=200, same.scale=FALSE, na.rm=TRUE, show=TRUE,
           col=c("black", heat.colors(12)), FUN=base::length, xlab, ylab,
           ... )
    ## S3 method for class 'hist2d'
    print(x, ...)

### Arguments

`x` | either a vector containing the x coordinates or a matrix with 2 columns.
`y` | a vector contianing the y coordinates, not required if ‘x’ is matrix
`nbins` | number of bins in each dimension. May be a scalar or a 2 element vector. Defaults to 200.
`same.scale` | use the same range for x and y. Defaults to FALSE.
`na.rm` | Indicates whether missing values should be removed. Defaults to TRUE.
`show` | Indicates whether the histogram be displayed using `image` once it has been computed. Defaults to TRUE.
`col` | Colors for the histogram. Defaults to "black" for bins containing no elements, a set of 16 heat colors for other bins.
`FUN` | Function used to summarize bin contents. Defaults to `base::length`. Use, e.g., `mean` to calculate means for each bin instead of counts.
`xlab,ylab` | (Optional) x and y axis labels
`...` | Parameters passed to the image function.

### Details

This fucntion creates a 2-dimensional histogram by cutting the x and y dimensions into `nbins` sections. A 2-dimensional matrix is then constucted which holds the counts of the number of observed (x,y) pairs that fall into each bin. If `show=TRUE`, this matrix is then then passed to `image` for display.

### Value

A list containing 5 elements:

`counts` | Matrix containing the number of points falling into each bin
`x.breaks, y.breaks` | Lower and upper limits of each bin
`x,y` | midpoints of each bin

### Author(s)

Gregory R. Warnes greg@warnes.net

### See Also

`image`, `persp`, `hist`, `freq2d`

### Examples

       ## example data, bivariate normal, no correlation
       x <- rnorm(2000, sd=4)
       y <- rnorm(2000, sd=1)

       ## separate scales for each axis, this looks circular
       hist2d(x,y)

       ## same scale for each axis, this looks oval
       hist2d(x,y, same.scale=TRUE)

       ## use different ## bins in each dimension
       hist2d(x,y, same.scale=TRUE, nbins=c(100,200) )

       ## use the hist2d function to create an h2d object
       h2d <- hist2d(x,y,show=FALSE, same.scale=TRUE, nbins=c(20,30))

       ## show object summary
       h2d

       ## object contents
       str(h2d)

       ## perspective plot
       persp( h2d$x, h2d$y, h2d$counts,
              ticktype="detailed", theta=30, phi=30,
              expand=0.5, shade=0.5, col="cyan", ltheta=-30)

       ## for contour (line) plot ...
       contour( h2d$x, h2d$y, h2d$counts, nlevels=4 )

       ## for a filled contour plot ...
       filled.contour( h2d$x, h2d$y, h2d$counts, nlevels=4,
                       col=gray((4:0)/4) )

[Package gplots version 3.0.1 Index]