1\name{histBxp}
2\encoding{latin1}
3\alias{histBxp}
4\title{Plot a Histogram and a Boxplot}
5\description{
6  Creates a histogram and a horizontal boxplot on the current graphics
7  device.
8}
9\usage{
10histBxp(x, nclass, breaks, probability=FALSE, include.lowest=TRUE,
11         xlab = deparse(substitute(x)),
12         \dots,
13         width=0.2, boxcol=3, medcol=2, medlwd=5, whisklty=2, staplelty=1)
14}
15\arguments{
16  \item{x}{numeric vector of data for histogram. Missing values
17    (\code{NA}s) are allowed.}
18  \item{nclass}{
19    recommendation for the number of classes (i.e., bars) the histogram should
20    have. The default is a number proportional to the logarithm of the length
21    of \code{x}.
22  }
23  \item{breaks}{
24    vector of the break points for the bars of the histogram. The count in the
25    i-th bar is \code{sum(breaks[i] < x <= breaks[i+1])}
26    except that if \code{include.lowest} is \code{TRUE} (the default),
27    the first bar also includes points equal to \code{breaks[1]}.  If
28    omitted, evenly-spaced break points are determined from
29    \code{nclass} and the extremes of the data.
30  }
31  \item{probability}{
32    logical flag: if \code{TRUE}, the histogram will be scaled as a probability
33    density; the sum of the bar heights times bar widths will equal \code{1}. If
34    \code{FALSE}, the heights of the bars will be counts.
35  }
36  \item{include.lowest}{
37    If \code{TRUE} (the default), the lowest bar will include data
38    points equal to the lowest break, otherwise it will act like the
39    other bars (see the description of the \code{breaks} argument).
40  }
41  \item{xlab}{character or expression for x axis labeling.}
42  \item{\dots}{additional arguments to \code{\link{barplot}}.  The
43    \code{\link{hist}} function uses the function \code{barplot} to do
44    the actual plotting; consequently, arguments to the \code{barplot}
45    function that control shading, etc., can also be given to
46    \code{hist}. See the \code{barplot} documentation for arguments
47    \code{angle}, \code{density}, \code{col}, and  \code{inside}. Do not
48    use the \code{space} or \code{histo} arguments.
49  }
50  \item{width}{
51    width of the box relative to the height of the histogram. DEFAULT is
52    \code{0.2}.}
53  \item{boxcol}{color of filled box. The default is \code{3}.}
54  \item{medcol}{
55    the color of the median line. The special value, \code{NA},
56    indicates the current plotting color (\code{par("col")}). The
57    default is \code{2}. If \code{boxcol=0} and \code{medcol} is not
58    explicitly specified this is set to the current plotting color
59    (\code{par("col")}).
60  }
61  \item{medlwd}{
62    median line width.  The special value \code{NA}, is used to indicate
63    the current line width (\code{par("lwd")}).  The default is \code{5}.
64  }
65  \item{whisklty}{
66    whisker line type. The special value \code{NA} indicates the
67    current line type (\code{par("lty")}). The default is \code{2}
68    (dotted line).}
69  \item{staplelty}{
70    staple (whisker end cap) line type. The special value \code{NA}
71    indicates the current line type (\code{par("lty")}). The default is
72    \code{1} (solid line).
73
74    Graphical parameters (see \code{\link{par}}) may also
75    be supplied as arguments to this function.
76    In addition, the high-level graphics arguments described under
77    \code{par} and the arguments to \code{title} may be supplied to this
78    function.}
79}
80\details{
81  If \code{include.lowest} is \code{FALSE} the bottom breakpoint must be
82  strictly less than the minimum of the data, otherwise (the default) it
83  must be less than or equal to the minimum of the data.  The top
84  breakpoint must be greater than or equal to the maximum of the data.
85
86  This function has been called \code{hist.bxp()} for 17 years; in 2012,
87  the increasingly strong CRAN policies required a new name (which could not
88  be confused with an S3 method name).
89}
90\author{S-Plus: Markus Keller, Christian Keller; port to \R in 1990's: Martin M�chler.}
91
92\seealso{\code{\link{hist}}, \code{\link{barplot}},
93  \code{\link{boxplot}}, \code{\link{rug}} and
94  \code{\link[Hmisc]{scat1d}} in the \CRANpkg{Hmisc} package.
95}
96\examples{
97 lab <- "50 samples from a t distribution with 5 d.f."
98 mult.fig(2*3, main = "Hist() + Rug()   and    histBxp(*)")
99 for(i in 1:3) {
100   my.sample <-  rt(50, 5)
101   hist(my.sample, main=lab); rug(my.sample)# for 50 obs., this is ok, too..
102   histBxp(my.sample, main=lab)
103 }
104}
105\keyword{hplot}
106