

   HHiissttooggrraammss

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

   AArrgguummeennttss::

          x: a vector of values for which the histogram is
             desired.

     breaks: either a single number giving the approximate num-
             ber 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', rel-
             ative 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.  Additionally draw labels on top of bars,
             if `TRUE'.

        ...: further graphical parameters to `title' and
             `axis'.

   DDeessccrriippttiioonn::

        The generic function `hist' computes and plots (if
        `plot=T') a histogram of the given data values.

   DDeettaaiillss::

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

   VVaalluuee::

        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.

   intensities: 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]'.

       mids: the n cell midpoints; useful for plotting.

   NNoottee::

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

   SSeeee AAllssoo::

        `stem', `density'.

   EExxaammpplleess::

        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$intensities, r$counts, adj=c(.5,-.5), col='blue3')
        sapply(r[2:3],sum)
        sum(r$intensities * diff(r$breaks)) # == 1
        par(op)

        str(hist(islands, plot= F))
        str(hist(islands, br=12, plot= F))
        str(hist(islands, br=c(12,20,36,80,200,1000,17000), plot = F))
        str(hist(islands, br=c(12,20,36,80,200,1000,17000), freq = TRUE))#warning

