.-
help for ^flower^
.-

Sunflower plots
---------------

  ^flower^ yvar xvar [weight] [^if^ exp] [^in^ range]
     [^,^ {^yr^ound^(^#^)^|^yb^ins^(^#^)^} {^xr^ound^(^#^)^|^xb^ins^(^#^)^}
         ^ps^ize^(^size^) pe^tals^(^maxnum^)^ graph_options]


Description
-----------

^flower^ draws sunflower plots, plots that display a bivariate dataset
using "sunflower" symbols to show the number of observations at or near
each x-y point. Each sunflower is composed of a central dot and a number
of "petals" (straight line segments) emanating from the central dot.


Remarks
-------

By default, the sunflower plot shows the number of points with exactly
identical x and y values. Even in a relatively small data set there may be
several ties, especially if values are integers or on some other coarse
scale.

Otherwise, binning on either the y axis or the x axis or both may define
intervals. Points within the interval are counted and plotted at the
center of the interval.

It is possible to combine binning on one axis and the use of exact values
on the other axis, and this may be best for a combination of a measured
variable and a categorical variable.

A dot represents a count of 1, two petals a count of 2, three petals a
count of 3, and so forth.

Frequency weights may be specified.

The user may modify the width or number of bins, the size of a sunflower,
and the maximum number of petals to be drawn.


Options
-------

^yround(^#^)^ or ^ybins(^#^)^ specifies binning on the y axis, by either
an argument for ^round(^yvar^,^yround^)^ or a number of bins, which is
converted into an argument for ^round( )^ by dividing the observed range
on yvar (maximum - minimum) by that number. Only one may be chosen.

^xround(^#^)^ or ^xbins(^#^)^ specifies binning on the x axis, by either
an argument for ^round(^xvar^,^xround^)^ or a number of bins, which is
converted into an argument for ^round( )^ by dividing the observed range
on xvar (maximum - minimum) by that number. Only one may be chosen.

The arguments for ^yround( )^ and ^xround( )^ should be expressed in the
units of the respective variables.

Example: the observed range of ^mpg^ in the auto data set is 29, from 12
to 41, miles per gallon. If ^mpg^ is to be shown on the y axis, specifying
^yround(5)^ puts values in bins with centers 10 (5) 40, multiples of 5,
while specifying ^ybins(10)^ puts values in bins of width 29 / 10 = 2.9,
with centers 11.6 (= 4 * 2.9) to 40.6 (= 14 * 2.9). Note that in this and
in other cases the bin centers may lie outside the observed range.

^psize(^size^)^ specifies the size of the sunflower symbols relative to
the default size (100). For example, ^psize(50)^ will draw half-size
symbols and ^psize(200)^ will draw double-size symbols. Sunflowers are not
drawn for non-positive values of size.

^petals(^maxnum^)^ specifies the maximum number of petals that will
display. Points with maxnum or more points in the neighborhood all display
with the same symbol. Petals do not display for values of maxnum < 2. The
default value of maxnum is 10.

graph_options are those allowed with ^graph, twoway^. The default
graph_options are ^connect(.)^ and ^pen(2)^, along with default titles and
labels. ^symbol()^ is preset and cannot be changed.


Examples
--------

 . ^flower mpg displ^

 . ^flower mpg weight, yb(20) xb(20)^


Authors
-------

  Thomas J. Steichen, RJRT, steicht@@rjrt.com

  Nicholas J. Cox, University of Durham, UK, n.j.cox@@durham.ac.uk


References
----------

  Cleveland, W.S. and McGill, R. 1984. The many faces of a scatterplot.
  Journal of the American Statistical Association 79(388): 807-822.


Also see
--------

  Manual:  ^[G] graphics^
 On-line:  help for @graph@, @functions@ (for ^round( )^)


