\Header{histogram}{Histograms and Kernel Density Plots}
\alias{densityplot}{histogram}
\keyword{hplot}{histogram}
\begin{Description}\relax
Draw Histograms and Kernel Density Plots
\end{Description}
\begin{Usage}
\begin{verbatim}
histogram(formula,
          data, 
          type = c("percent", "count", "density"),
          nint = if(is.factor(x)) length(levels(x))
                 else round(log2(length(x))+1),
          endpoints = range(x[!na.x]),
          breaks = if(is.factor(x)) seq(0.5, length = length(levels(x))
          + 1) else do.breaks(endpoints, nint),
          equal.widths = FALSE, 
          ...)

densityplot(formula, data, n = 50, plot.points = TRUE, ref = FALSE,
            ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{formula}] A formula of the form \code{\textasciitilde{} x | g1 * g2 * ...}
indicates that histograms or Kernel Density estimates of \code{x}
should be produced conditioned on the levels of the (optional)
variables \code{g1,g2,...}. When the conditioning variables
\code{g1,g2,...} are missing, the leading \code{\textasciitilde{}} can be dropped.

\code{x} can be numeric (or factor for \code{histogram}), and each
of \code{g1,g2,...} must be either factors or shingles.

As a special case, the right hand side of the formula (\code{x}) can
actually contain more than one variable separated by a '+'
sign. What happens in this case is described in details in the
documentation for \code{\Link{xyplot}}.

\item[\code{data}] optional data frame in which variables are to be evaluated

\item[\code{type}] Character string indicating type of histogram to be
drawn. ``percent'' and ``count'' give relative frequency and
frequency histograms, and can be misleading when breakpoints are not
equally spaced. ``density'' produces a density scale histogram.

\code{type} defaults to ``percent'', except when the breakpoints
are unequally spaced or \code{breaks = NULL}, when it defaults to
``density''.

\item[\code{nint}] Number of bins. Applies only when \code{breaks} is
unspecified in the call.

\item[\code{endpoints}] vector of length 2 indicating the range of x-values
that is to be covered by the  histogram. Again, applies only when
\code{breaks} is unspecified.

\item[\code{breaks}] numeric vector of length = (number of bins + 1)
defining the breakpoints of the bins. Note that when breakpoints are
not equally spaced, the only value of \code{type} that makes sense
is density.

Usually all panels use the same breakpoints. This can be changed by
specifying \code{breaks = NULL}. This has the effect of letting each
panel choose its own breakpoints. The choice of these breakpoints
are made as follows: The number of bins is calculated by the formula
for \code{nint} above, and then breakpoints are chosen according to
the value of \code{equal.widths}.

\item[\code{equal.widths}] logical, relevant only when \code{breaks=NULL}.
If \code{TRUE}, equally spaced bins will be selected, otherwise, 
approximately equal area bins will be selected (this would mean that
the breakpoints will \bold{not} be equally spaced).

\item[\code{n}] number of points at which density is to be evaluated
\item[\code{plot.points}] logical specifying whether the \code{x} values
should be plotted.

\item[\code{ref}] logical specifying whether a reference x-axis should be
drawn.

\item[\code{...}] other arguments, passed along to the panel function. In
the case of \code{densityplot}, if the default panel function is
used, then arguments appropriate to \code{density} can be
included. This can control the details of how the Kernel Density
Estimates are calculated. See documentation for
\code{\Link{density}} for details.

\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\code{histogram} draws Conditional Histograms, while
\code{densityplot} draws Conditional Kernel Density Plots.  The
density estimate in \code{densityplot} is actually calculated using
the function \code{density}, and all arguments accepted by it can be
passed (as \code{...}) in the call to \code{densityplot} to control
the output. See documentation of \code{density} for details. (Note: The
default value of the argument \code{n} of \code{density} is changed to
50.)

These and all other high level Trellis functions have several
arguments in common. These are extensively documented only in the
help page for \code{xyplot}, which should be consulted to learn more
detailed usage.
\end{Details}
\begin{Value}
An object of class ``trellis''. The `update' method can be used to
update components of the object and the `print' method (usually called
by default) will plot it on an appropriate plotting device.
\end{Value}
\begin{Note}\relax
The form of the arguments accepted by the default
panel function \code{panel.histogram} is different from that in
S-PLUS. Whereas S-PLUS calculates the heights inside \code{histogram}
and passes only the breakpoints and the heights to the panel function,
here the original variable \code{x} is passed along with the
breakpoints. This allows plots as in the second example below.
\end{Note}
\begin{Author}\relax
Deepayan Sarkar \email{deepayan@stat.wisc.edu}
\end{Author}
\begin{SeeAlso}\relax
\code{\Link{xyplot}},
\code{\Link{panel.histogram}},
\code{\Link{density}},
\code{\Link{panel.densityplot}},
\code{\Link{panel.mathdensity}},
\code{\Link{Lattice}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
require(stats)
data(singer)

histogram( ~ height | voice.part, data = singer, nint = 17,
          endpoints = c(59.5, 76.5), layout = c(2,4), aspect = 1,
          xlab = "Height (inches)")

histogram( ~ height | voice.part, data = singer,
          xlab = "Height (inches)", type = "density",
          panel = function(x, ...) {
              panel.histogram(x, ...)
              panel.mathdensity(dmath = dnorm, col = "black",
                                args = list(mean=mean(x),sd=sd(x)))
          } )

densityplot( ~ height | voice.part, data = singer, layout = c(2, 4),  
            xlab = "Height (inches)", bw = 5)
\end{ExampleCode}
\end{Examples}

