Plot a Histogram

DESCRIPTION:

USAGE:

hist(x, nclass = <<see below>>, breaks = <<see below>>, plot = T,  
     probability = F, include.lowest  =  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. Missing values (NA) are allowed.

OPTIONAL ARGUMENTS:

nclass

recommendation for the number of classes (i.e., bars) the histogram should have. The default is a number proportional to the logarithm of the length of x. For factor data nclass is length(levels(x)) and cannot be overridden.

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).

...

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 par ). In addition, the high-level graphics arguments described under plot.default and the arguments to title 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:

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.

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