Dotplot                                                         [STB19: gr14]
-------

   ^dotplot^ var [^if^ exp] [^in^ range] ^, by(^groupvar^)^ [^ nx(^#^) ny(^#^) ce^ntre
	^av^erage^(^string^) b^ar ^ex^act_y graph_options ]

                               -- or --

   ^dotplot^ varlist [^if^ exp] [^in^ range] [^, nx(^#^) ny(^#^) ce^ntre
	^av^erage^(^string^) b^ar ^ex^act_y graph_options ]


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

A dotplot is a scatterplot with grouping of values in the vertical direction
('binning', as in a histogram), and with separation between plotted points in
the horizontal direction.  The aim is to show all the data for several
variables or groups in a single, compact graphic.

In the first form, ^dotplot^ produces a columnar dotplot of var, with one column
per value of groupvar.



Description, continued
----------------------

In the second form, ^dotplot^ produces a columnar dotplot for each variable in
varlist, with one column per variable.  ^by(^groupvar^)^ is not allowed.

In each case, the 'dots' are plotted as small circles to increase readability.

If the original data was sorted, ^dotplot^ will ask the user to press the F4 key 
to restore the original order.













Options
-------

^nx(^#^)^ sets the horizontal dot density.  A larger value of # will increase the
    density and hence will reduce the horizontal separation between the dots.
    This will help to avoid overlap between columns if many groups or variables
    are to be displayed.  A smaller value of # will increase the separation.
    Stored in $S_1.

^ny(^#^)^ sets the vertical dot density (number of 'bins' on the Y-axis).  A
    larger value of # will result in more bins and a plot which is less
    spread-out in the horizontal direction.  # should be determined in
    conjunction with ^nx()^ to give the most pleasing appearance.
    Stored in $S_2.

^centre^ centres the dots for each column around a vertical line.

^average(^string^)^ produces a horizontal line of pluses at the average of  
	each group. The string specifies whether the average should be the 
	^mean^ or the ^median^.




Options, continued
------------------

^bar^ plots horizontal dashed lines at the "shoulders" of each group.  The
	"shoulders" are taken to be the upper and lower quartiles unless
	^ave(mean)^ has been specified in which case they will be the
	mean plus or minus the standard deviation.

^exact_y^ uses the actual values of yvar rather than group them.  This may
	be useful if yvar only takes on a few values, i.e., if yvar is a
	discrete variable.

graph_options are any of the standard Stata ^twoway^ graph options except 
	^xscale()^.


Examples
--------

 . ^dotplot mpg^
 . ^dotplot mpg, by(foreign) nx(20) ny(10) centre ylabel^
 . ^dotplot gratio, by(foreign) exact centre ylabel xline(0,1)^
 . ^dotplot g1r1-g1r10, ylabel l1title("Tumour volume, cu mm")^
 . ^dotplot g1r1-g1r10, ave(median) bar^



Authors
-------
          Peter Sasieni, Imperial Cancer Research Fund, London
	  Patrick Royston, Royal Postgraduate Medical School, London


Also see
--------

    STB:  gr14 (STB19)
On-line:  ^help^ for ^graph^, ^hist^, ^egen^