gplots (version 3.1.1)

hist2d: 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 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.

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

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.

See Also

image, persp, hist, freq2d

Examples

# NOT RUN {
   ## 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) )



# }