R: Histograms

hist {base}

R Documentation

Histograms

Description

The generic function hist computes a histogram of the given data values. If plot=TRUE, the resulting object of class "histogram" is plotted by plot.histogram, before it is returned.

Usage

hist(x, ...)
hist.default(x, breaks, freq = NULL, probability = !freq,
     include.lowest = TRUE,
     right = TRUE, col = NULL, border = par("fg"),
     main = paste("Histogram of" , xname),
     xlim = range(breaks), ylim = NULL,
     xlab = xname, ylab,
     axes = TRUE, plot = TRUE, labels = FALSE,
     nclass = NULL, ...)

Arguments

x

a vector of values for which the histogram is desired.

breaks

either a single number giving the approximate number of cells for the histogram or a vector giving the breakpoints between histogram cells.

freq

logical; if TRUE, the histogram graphic is to present a representation of frequencies, i.e, the counts component of the result; if FALSE, relative frequencies (“probabilities”), the rel.freqs, are plotted. Defaults to TRUE iff breaks are equidistant (and probability is not specified).

probability

an alias for !freq, for S compatibility.

include.lowest

logical; if TRUE, an ‘x[i]’ equal to the ‘breaks’ value will be included in the first (or last, for right = FALSE) bar.

right

logical; if TRUE, the histograms cells are right-closed (left open) intervals.

col

a colour to be used to fill the bars. The default of NULL yields unfilled bars.

border

the color of the border around the bars.

main, xlab, ylab

these arguments to title have useful defaults here.

xlim, ylim

the range of x and y values with sensible defaults.

plot

logical. If TRUE (default), a histogram is plotted, otherwise a list of breaks and counts is returned.

labels

logical or character. Additionally draw labels on top of bars, if not FALSE; see plot.histogram.

nclass

numeric (integer). For S compatibility only, nclass=n is equivalent to breaks=n (n scalar).

...

further graphical parameters to title and axis.

Details

If right = TRUE (default), the histogram cells are intervals of the form (a,b], i.e. they include their right-hand endpoint, but not their left one, with the exception of the first cell when include.lowest is TRUE.

For right = FALSE, the intervals are of the form [a,b), and include.lowest really has the meaning of “include highest”.

Value

an object of class "histogram" which is a list with components:

breaks

the n+1 cell boundaries (= breaks if that was a vector).

counts

n integers; for each cell, the number of x[] inside.

density

values \hat f(x_i), as estimated density values. If all(diff(breaks) == 1), they are the relative frequencies counts/n and in general satisfy \sum_i \hat f(x_i) (b_{i+1}-b_i) = 1, where b_i = breaks[i].

intensities

same as density. Deprecated, but retained for compatibility.

mids

the n cell midpoints.

xname

a character string with the actual x argument name.

equidist

logical, indicating if the distances between breaks are all the same.

Note

The resulting value does not depend on the values of the arguments freq (or probability) or plot. This is intentionally different from S.

Examples

data(islands)
op <- par(mfrow=c(2,2))
hist(islands)
str(hist(islands, col="gray", labels = TRUE))

hist(sqrt(islands), br = 12, col="lightblue", border="pink")
##-- For non-equidistant breaks, counts should NOT be graphed unscaled:
r <- hist(sqrt(islands), br = c(4* 0:5,10* 3:5,70,100,140), col='blue1')
text(r$mids, r$density, r$counts, adj=c(.5,-.5), col='blue3')
sapply(r[2:3],sum)
sum(r$density * diff(r$breaks)) # == 1
lines(r, lty = 3, border = "purple") # -> lines.histogram(*)
par(op)

str(hist(islands, plot= FALSE))        #-> 5  breaks
str(hist(islands, br=12, plot= FALSE)) #-> 10 (~= 12) breaks
str(hist(islands, br=c(12,20,36,80,200,1000,17000), plot = FALSE))
    hist(islands, br=c(12,20,36,80,200,1000,17000), freq = TRUE,
         main = "WRONG histogram") # and warning

[Package base version 1.3 ]