\HeaderA{sunflowerplot}{Produce a Sunflower Scatter Plot}{sunflowerplot}
\keyword{hplot}{sunflowerplot}
\keyword{smooth}{sunflowerplot}
\keyword{nonparametric}{sunflowerplot}
\begin{Description}\relax
Multiple points are plotted as \sQuote{sunflowers} with multiple leaves
(\sQuote{petals}) such that overplotting is visualized instead of accidental and
invisible.
\end{Description}
\begin{Usage}
\begin{verbatim}
sunflowerplot(x, y = NULL, number, log = "", digits = 6,
              xlab = NULL, ylab = NULL, xlim = NULL, ylim = NULL,
              add = FALSE, rotate = FALSE,
              pch = 16, cex = 0.8, cex.fact = 1.5,
              col = par("col"), bg = NA, size = 1/8, seg.col = 2,
              seg.lwd = 1.5, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] numeric vector of \code{x}-coordinates of length \code{n},
say, or another valid plotting structure, as for
\code{\LinkA{plot.default}{plot.default}}, see also \code{\LinkA{xy.coords}{xy.coords}}.
\item[\code{y}] numeric vector of \code{y}-coordinates of length \code{n}.
\item[\code{number}] integer vector of length \code{n}. \code{number[i]} = number
of replicates for \code{(x[i],y[i])}, may be 0.\\
Default (\code{missing(number)}): compute the exact multiplicity of
the points \code{x[],y[]}, via
\code{\LinkA{xyTable}{xyTable}()}.
\item[\code{log}] character indicating log coordinate scale, see
\code{\LinkA{plot.default}{plot.default}}.
\item[\code{digits}] when \code{number} is computed (i.e., not specified),
\code{x} and \code{y} are rounded to \code{digits} significant
digits before multiplicities are computed.
\item[\code{xlab,ylab}] character label for x-, or y-axis, respectively.
\item[\code{xlim,ylim}] \code{numeric(2)} limiting the extents of the x-,
or y-axis.
\item[\code{add}] logical; should the plot be added on a previous one ?
Default is \code{FALSE}.
\item[\code{rotate}] logical; if \code{TRUE}, randomly rotate the
sunflowers (preventing artefacts).
\item[\code{pch}] plotting character to be used for points
(\code{number[i]==1}) and center of sunflowers.
\item[\code{cex}] numeric; character size expansion of center points
(s. \code{pch}).
\item[\code{cex.fact}] numeric \emph{shrinking} factor to be used for the
center points \emph{when there are flower leaves},
i.e., \code{cex / cex.fact} is used for these.
\item[\code{col, bg}] colors for the plot symbols, passed to
\code{\LinkA{plot.default}{plot.default}}.
\item[\code{size}] of sunflower leaves in inches, 1[in] := 2.54[cm].
Default: 1/8\", approximately 3.2mm.
\item[\code{seg.col}] color to be used for the \bold{seg}ments which make the
sunflowers leaves, see \code{\LinkA{par}{par}(col=)};
\code{col = "gold"} reminds of real sunflowers.
\item[\code{seg.lwd}] numeric; the line width for the leaves' segments.
\item[\code{...}] further arguments to \code{\LinkA{plot}{plot}} [if
\code{add=FALSE}].
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
For \code{number[i]==1}, a (slightly enlarged) usual plotting symbol
(\code{pch}) is drawn.
For \code{number[i] > 1}, a small plotting symbol is drawn and
\code{number[i]} equi-angular \sQuote{rays} emanate from it.

If \code{rotate=TRUE} and \code{number[i] >= 2}, a random direction
is chosen (instead of the y-axis) for the first ray.  The goal is to
\code{\LinkA{jitter}{jitter}} the orientations of the sunflowers in order to prevent
artefactual visual impressions.
\end{Details}
\begin{Value}
A list with three components of same length,
\begin{ldescription}
\item[\code{x}] x coordinates
\item[\code{y}] y coordinates
\item[\code{number}] number
\end{ldescription}


Use \code{\LinkA{xyTable}{xyTable}()} (from package
\pkg{grDevices}) if you are only interested in this return value.
\end{Value}
\begin{Section}{Side Effects}
A scatter plot is drawn with \sQuote{sunflowers} as symbols.
\end{Section}
\begin{Author}\relax
Andreas Ruckstuhl, Werner Stahel, Martin Maechler, Tim Hesterberg,
1989--1993.  Port to \R{} by Martin Maechler
\email{maechler@stat.math.ethz.ch}.
\end{Author}
\begin{References}\relax
Chambers, J. M., Cleveland, W. S., Kleiner, B. and Tukey, P. A. (1983)
\emph{Graphical Methods for Data Analysis.}  Wadsworth.

Schilling, M. F. and Watkins, A. E. (1994)
A suggestion for sunflower plots.
\emph{The American Statistician}, \bold{48}, 303--305.

Murrell, P. (2005) \emph{R Graphics}. Chapman \& Hall/CRC Press.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{density}{density}}, \code{\LinkA{xyTable}{xyTable}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
require(stats)
require(grDevices)

## 'number' is computed automatically:
sunflowerplot(iris[, 3:4])
## Imitating  Chambers et al., p.109, closely:
sunflowerplot(iris[, 3:4], cex=.2, cex.fact=1, size=.035, seg.lwd=.8)

sunflowerplot(x=sort(2*round(rnorm(100))), y= round(rnorm(100),0),
              main = "Sunflower Plot of Rounded N(0,1)")
## Similarly using a "xyTable" argument:
xyT <- xyTable(x=sort(2*round(rnorm(100))), y= round(rnorm(100),0),
               digits=3)
utils::str(xyT, vec.len=20)
sunflowerplot(xyT, main = "2nd Sunflower Plot of Rounded N(0,1)")

## A 'marked point process' {explicit 'number' argument}:
sunflowerplot(rnorm(100), rnorm(100), number = rpois(n=100,lambda=2),
              main="Sunflower plot (marked point process)",
              rotate=TRUE, col = "blue4")
\end{ExampleCode}
\end{Examples}

