Plot a Histogram

DESCRIPTION:

Creates a histogram on the current graphics device. Several options are available.

USAGE:

hist(x, nclass=<<see below>>, breaks=<<see below>>, plot=T,
     probability=F, include.lowest=T, eraseoutline=T, ...,
     xlab=deparse(substitute(x)))
hist.factor(x, plot=T,
     probability=F, include.lowest=T, ...,
     xlab=deparse(substitute(x)))

REQUIRED ARGUMENTS:

x
numeric or factor vector of data for histogram. If x is a factor (or category) hist will call hist.factor with all but the nclass and breaks arguments. If x is integer-valued hist.factor(x) may give you better results than hist(x). Missing values (NA) are allowed.

OPTIONAL ARGUMENTS:

nclass
recommendation for the number of classes (i.e., bars) the histogram should have. This may be an integer, a function to apply to x which returns an integer, or a character string specifying which built-in method to use. Available methods for calculating the number of classes are Sturges ( sturges), Freedman-Diaconis ( fd), and Scott ( scott).

For factor data nclass is length(levels(x)) and cannot be overridden.

The breaks argument will be used as the nclass argument if the nclass argument is missing, or if the breaks argument is length one or a function.

breaks
vector of the break points for the bars of the histogram. The count in the i-th bar is sum(breaks[i] < x & x <= breaks[i+1]) except that if include.lowest is TRUE (the default), the first bar also includes points equal to breaks[1]. If omitted, evenly-spaced break points are determined from nclass and the extremes of the data. For factor data breakpoints are at half integers and cannot be overridden.
plot
logical flag: if TRUE, the histogram will be plotted; if FALSE, a list giving breakpoints and counts will be returned.
probability
logical flag: if TRUE, the histogram will be scaled as a probability density; the sum of the bar heights times bar widths will equal 1. If FALSE, the heights of the bars will be counts.
include.lowest
logical flag: if TRUE (the default), the lowest bar will include data points equal to the lowest break, otherwise it will act like the other bars (see the description of the breaks argument).
eraseoutline
If TRUE draw a line around each color-filled bar using the background color to ensure that the bars are visually separated from one another. If there are lots of bars this may erase the entire bar. Use eraseoutline=FALSE to avoid this. This erasing is never done for hist.factor or for styles without color-filled bars.
...
additional arguments to barplot. The hist function uses the function barplot to do the actual plotting; consequently, arguments to the barplot function that control shading, etc., can also be given to hist. See the barplot documentation for arguments angle, density, col, and inside. Do not use the space or histo arguments.
xlab
label for the plot x-axis. By default, this will be x.

Graphical parameters may also be supplied as arguments to this function (see ). In addition, the high-level graphics arguments described under and the arguments to may be supplied to this function.

VALUE:

if plot is TRUE, a vector containing the coordinate of the center of each box is returned.

if plot is FALSE, hist returns a list with components:

counts
count or density in each bar of the histogram.
breaks
break points between histogram classes.

SIDE EFFECTS:

if plot is TRUE, a plot is created on the current graphics device.

DETAILS:

If include.lowest is FALSE the bottom breakpoint must be strictly less than the minimum of the data, otherwise (the default) it must be less than or equal to the minimum of the data. The top breakpoint must be greater than or equal to the maximum of the data.

hist.factor will label the x axis with the levels of x. If you will be adding to the plot consider the bars to be at 1:length(levels(x)).

If plot is TRUE, then hist calls barplot.

REFERENCES:

"Histograms". In Encyclopedia of Statistical Sciences. S. Kotz and N. L. Johnson, eds.

Venables, W. N. and Ripley, B. D. (1999). Modern Applied Statistics with S-PLUS, Third Edition. Springer-Verlag.

SEE ALSO:

, , , , , , , .

EXAMPLES:

my.sample <- rt(50, 5)
lab <- "50 samples from a t distribution with 5 d.f."
hist(my.sample, main=lab)

hist(state.region)  # calls hist.factor