\Header{sunflowerplot}{Produce a Sunflower Scatter Plot}
\keyword{hplot}{sunflowerplot}
\keyword{density}{sunflowerplot}
\keyword{nonparametric}{sunflowerplot}
\begin{Description}\relax
Multiple points are plotted as ``sunflowers'' with multiple leaves
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,
             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{\Link{plot.default}}, see also \code{\Link{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: compute the exact multiplicity of the points \code{x[],y[]}.
\item[\code{log}] character indicating log coordinate scale, see
\code{\Link{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 computes.
\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{size}] of sunflower leaves in inches, 1[in] := 2.54[cm].
Default: 1/8\" ~= 3.2mm.
\item[\code{seg.col}] color to be used for the \bold{seg}ments which make the
sunflowers leaves, see \code{\Link{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{\Link{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 ``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{\Link{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}
\end{Value}
\begin{Section}{Side Effects}
A scatter plot is drawn with ``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.\end{References}
\begin{SeeAlso}\relax
\code{\Link{density}}\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
data(iris)
## `number' is computed automatically:
sunflowerplot(iris[, 3:4])
## Imitating  Chambers et al., p.109, closely:
sunflowerplot(iris[, 3:4],cex=.2, cex.f=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)")

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

