whist.Rd
\name{whist}
\alias{whist}
\title{
Weighted Histogram
}
\description{
Computes the weighted histogram of a set of observations
with a given set of weights.
}
\usage{
whist(x, breaks, weights = NULL)
}
\arguments{
\item{x}{
Numeric vector of observed values.
}
\item{breaks}{
Vector of breakpoints for the histogram.
}
\item{weights}{
Numeric vector of weights for the observed values.
}
}
\details{
This low-level function computes (but does not plot) the weighted
histogram of a vector of observations \code{x} using a given
vector of \code{weights}.
The arguments \code{x} and \code{weights} should be numeric vectors of
equal length. They may include \code{NA} or infinite values.
The argument \code{breaks} should be a numeric vector whose entries
are strictly increasing. These values define the boundaries between the
successive histogram cells.
The breaks \emph{do not} have to span the range
of the observations.
There are \code{N-1} histogram cells, where \code{N = length(breaks)}.
An observation \code{x[i]} falls in the \code{j}th cell if
\code{breaks[j] <= x[i] < breaks[j+1]} (for \code{j < N-1})
or
\code{breaks[j] <= x[i] <= breaks[j+1]} (for \code{j = N-1}).
The weighted histogram value \code{h[j]} for the \code{j}th cell is
the sum of \code{weights[i]} for all observations \code{x[i]} that
fall in the cell.
Note that, in contrast to the function \code{\link{hist}},
the function \code{whist} does not require the breakpoints to span the
range of the observations \code{x}. Values of \code{x} that fall outside the
range of \code{breaks} are handled separately; their total weight
is returned as an attribute of the histogram.
}
\value{
A numeric vector of length \code{N-1} containing the
histogram values, where \code{N = length(breaks)}.
The return value also has attributes \code{"low"} and \code{"high"}
giving the total weight of all observations that are less than
the lowest breakpoint, or greater than the highest breakpoint,
respectively.
}
\examples{
x <- rnorm(100)
b <- seq(-1,1,length=21)
w <- runif(100)
whist(x,b,w)
}
\author{Adrian Baddeley
\email{Adrian.Baddeley@csiro.au}
\url{http://www.maths.uwa.edu.au/~adrian/}
and Rolf Turner
\email{r.turner@auckland.ac.nz}
with thanks to Peter Dalgaard.
}
\keyword{arith}