\Header{hist}{Histograms}
\alias{hist.default}{hist}
\keyword{hplot}{hist}
\keyword{iplot}{hist}
\keyword{distribution}{hist}
\begin{Usage}
\begin{verbatim}
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, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\texttt{x}] a vector of values for which the histogram is desired.
\item[\texttt{breaks}] either a single number giving the
approximate number of cells for the histogram
or a vector giving the breakpoints between histogram cells.
\item[\texttt{freq}] logical; if \texttt{TRUE}, the
histogram graphic is to present a representation of frequencies, i.e,
the \texttt{counts} component of the result; if \texttt{FALSE},
\emph{relative} frequencies (``probabilities''), the \texttt{rel.freqs},
are plotted.   Defaults to \texttt{TRUE} \emph{iff} \texttt{breaks} are
equidistant.
\item[\texttt{probability}] an \emph{alias} for \texttt{!freq}, for S compatibility.
\item[\texttt{include.lowest}] logical; if \texttt{TRUE},
an `x[i]' equal to the `breaks' value will be included in the first
(or last, for \texttt{right = FALSE}) bar.
\item[\texttt{right}] logical; if \texttt{TRUE}, the histograms cells are
right-closed (left open) intervals.
\item[\texttt{col}] a colour to be used to fill the bars.
The default of \texttt{NULL} yields unfilled bars.
\item[\texttt{border}] the color of the border around the bars.
\item[\texttt{main,xlab,ylab}] these arguments to \texttt{title} have useful
defaults here.
\item[\texttt{xlim,ylim}] the range of x and y values with sensible defaults.
\item[\texttt{plot}] logical.  If \texttt{TRUE} (default), a histogram is
plotted, otherwise a list of breaks and counts is returned.
\item[\texttt{labels}] logical.  Additionally draw labels on top of bars, if \texttt{TRUE}.
\item[\texttt{...}] further graphical parameters to \texttt{title} and \texttt{axis}.
\end{ldescription}
\end{Arguments}
\begin{Description}
The generic function \texttt{hist} computes and plots (if \texttt{plot=T}) a
histogram of the given data values.\end{Description}
\begin{Details}
If \texttt{right = TRUE} (default), the histogram cells are intervals of the form
\texttt{(a,b]}, i.e. they include their right-hand endpoint,
but not their left one, with the exception of the first cell when
\texttt{include.lowest} is \texttt{TRUE}.

For \texttt{right = FALSE}, the intervals are of the form \texttt{[a,b)},
and \texttt{include.lowest} really has the meaning of ``\emph{include highest}''.\end{Details}
\begin{Value}
a list with components
\begin{ldescription}
\item[\texttt{breaks}] the \eqn{n+1}{} cell boundaries (= \texttt{breaks} if that
was a vector).
\item[\texttt{counts}] \eqn{n}{} integers; for each cell, the number of
\texttt{x[]} inside.
\item[\texttt{intensities}] values \eqn{\hat f(x_i)}{f^(x[i])}, as estimated
density values. If \texttt{all(diff(breaks) == 1)}, they are the
relative frequencies \texttt{counts/n} and in general satisfy
\eqn{\sum_i \hat f(x_i) (b_{i+1}-b_i) = 1}{sum[i; f^(x[i])
(b[i+1]-b[i])] = 1}, where \eqn{b_i}{b[i]}=\texttt{breaks[i]}.
\item[\texttt{mids}] the \eqn{n}{} cell midpoints; useful for plotting.
\end{ldescription}
\end{Value}
\begin{Note}
The resulting value does \emph{not}
depend on the values of the arguments \texttt{freq} (or \texttt{probability})
or \texttt{plot}.  This is intentionally different from S.\end{Note}
\begin{SeeAlso}
\texttt{\Link{stem}}, \texttt{\Link{density}}.\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
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
\end{ExampleCode}
\end{Examples}

