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.
`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 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; 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.

### See Also

`stem`, `density`.

### 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