1% File src/library/graphics/man/stripchart.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2014 R Core Team
4% Distributed under GPL 2 or later
5
6\name{stripchart}
7\title{1-D Scatter Plots}
8\alias{stripchart}
9\alias{stripchart.default}
10\alias{stripchart.formula}
11
12\description{
13  \code{stripchart} produces one dimensional scatter plots (or dot
14  plots) of the given data.  These plots are a good alternative to
15  \code{\link{boxplot}}s when sample sizes are small.
16}
17\usage{
18stripchart(x, \dots)
19
20\method{stripchart}{formula}(x, data = NULL, dlab = NULL, \dots,
21           subset, na.action = NULL)
22
23
24\method{stripchart}{default}(x, method = "overplot", jitter = 0.1, offset = 1/3,
25           vertical = FALSE, group.names, add = FALSE,
26           at = NULL, xlim = NULL, ylim = NULL,
27           ylab = NULL, xlab = NULL, dlab = "", glab = "",
28           log = "", pch = 0, col = par("fg"), cex = par("cex"),
29           axes = TRUE, frame.plot = axes, \dots)
30}
31\arguments{
32  \item{x}{the data from which the plots are to be produced.  In the
33    default method the data can be specified as a single numeric
34    vector, or as list of numeric vectors, each corresponding to
35    a component plot.  In the \code{formula} method, a symbolic
36    specification of the form \code{y ~ g} can be given,
37    indicating the observations in the vector \code{y} are to be
38    grouped according to the levels of the factor
39    \code{g}.  \code{NA}s are allowed in the data.}
40  \item{data}{a data.frame (or list) from which the variables in
41    \code{x} should be taken.}
42  \item{subset}{an optional vector specifying a subset of observations
43    to be used for plotting.}
44  \item{na.action}{a function which indicates what should happen
45    when the data contain \code{NA}s.  The default is to ignore missing
46    values in either the response or the group.}
47  \item{\dots}{additional parameters passed to the default method, or by
48    it to \code{\link{plot.window}}, \code{\link{points}},
49    \code{\link{axis}} and \code{\link{title}} to control the appearance
50    of the plot.}
51  \item{method}{the method to be used to separate coincident points.
52    The default method \code{"overplot"} causes such points to be
53    overplotted, but it is also possible to specify \code{"jitter"} to
54    jitter the points, or \code{"stack"} have coincident points
55    stacked.  The last method only makes sense for very granular data.}
56  \item{jitter}{when \code{method = "jitter"} is used, \code{jitter}
57    gives the amount of jittering applied.}
58  \item{offset}{when stacking is used, points are stacked this many
59    line-heights (symbol widths) apart.}
60  \item{vertical}{when vertical is \code{TRUE} the plots are drawn
61    vertically rather than the default horizontal.}
62  \item{group.names}{group labels which will be printed alongside
63    (or underneath) each plot.}
64  \item{add}{logical, if true \emph{add} the chart to the current plot.}
65  \item{at}{numeric vector giving the locations where the charts should
66    be drawn, particularly when \code{add = TRUE};
67    defaults to \code{1:n} where \code{n} is the number of boxes.}
68  \item{ylab, xlab}{labels: see \code{\link{title}}.}
69  \item{dlab, glab}{alternate way to specify axis labels: see \sQuote{Details}.}
70  \item{xlim, ylim}{plot limits: see \code{\link{plot.window}}.}
71  \item{log}{on which axes to use a log scale:  see
72    \code{\link{plot.default}}}
73  \item{pch, col, cex}{Graphical parameters: see \code{\link{par}}.}
74  \item{axes, frame.plot}{Axis control:  see \code{\link{plot.default}}.}
75}
76\details{
77  Extensive examples of the use of this kind of plot can be found in
78  Box, Hunter and Hunter or Seber and Wild.
79
80  The \code{dlab} and \code{glab} labels may be used instead of \code{xlab}
81  and \code{ylab} if those are not specified.  \code{dlab} applies to the
82  continuous data axis (the X axis unless \code{vertical} is \code{TRUE}),
83  \code{glab} to the group axis.
84}
85\examples{
86x <- stats::rnorm(50)
87xr <- round(x, 1)
88stripchart(x) ; m <- mean(par("usr")[1:2])
89text(m, 1.04, "stripchart(x, \"overplot\")")
90stripchart(xr, method = "stack", add = TRUE, at = 1.2)
91text(m, 1.35, "stripchart(round(x,1), \"stack\")")
92stripchart(xr, method = "jitter", add = TRUE, at = 0.7)
93text(m, 0.85, "stripchart(round(x,1), \"jitter\")")
94
95stripchart(decrease ~ treatment,
96    main = "stripchart(OrchardSprays)",
97    vertical = TRUE, log = "y", data = OrchardSprays)
98
99stripchart(decrease ~ treatment, at = c(1:8)^2,
100    main = "stripchart(OrchardSprays)",
101    vertical = TRUE, log = "y", data = OrchardSprays)
102}
103\keyword{hplot}
104