..-
help for ^spikeplt^                                     (STB-40: gr25.1)
..-

Spike plot, histogram or rootogram showing fine structure
---------------------------------------------------------

    ^spikeplt^ varname [weight] [^if^ exp] [^in^ range]
    [ ^, r^ound^(^#^) sh^ift ^frac root z^ero^(^#^)^ graph_options ]

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

^spikeplt^ produces a spike plot, histogram or rootogram for varname
that will show some of the fine structure of the data. varname is
plotted on the x-axis. The frequency of each value, after any rounding,
and applying any weight, is shown by a vertical spike drawn from a
reference level (by default 0).

If used to produce histograms, the default is to show raw frequencies in
each bin or interval. In contrast to ^graph, histogram^, there is no
restriction to a maximum of 50 bins, and a few hundred spikes may be
tolerable, especially if there are interesting gaps, clusters or
preferred values. Berry (1996, p.14) uses the name `spike chart' for
this kind of histogram.

If used to produce time series plots, the varname would be the time
variable, and the weight variable would be the values for those times.
Chapman and Mahon (1986, p.84) used the name `spike graph' for such a
plot.

Options
-------

^round(^#^)^ uses the round( ) function to round varname to the nearest
    multiple of #. See help on @functions@. In other words, round
    specifies the binwidth.

    With ^round(1)^ values between 0.5 and 1.5 would be rounded to 1 and
    the bin frequency shown as a spike at 1.

^shift^ shifts bins so that the bin boundaries, rather than the bin
    centres, are multiples of #.

    With ^round(1) shift^ values between 1 and 2 would be rounded to 1.5
    and the bin frequency shown as a spike at 1.5.

^frac^ specifies that the vertical scale is to show fractions.  Note
    that this convention is the opposite of that for ^graph, histogram^.

^root^ specifies that the vertical scale is to show square roots of
    frequencies (J.W. Tukey's `rootogram'). See Tukey (1972, 1977) or
    Velleman and Hoaglin (1981).

^zero(^#^)^ specifies a constant other than 0 as a level from which
    spikes are drawn vertically.

graph_options are options allowed with ^graph, twoway^. ^by^ is allowed,
    but ^total^ is trapped with a warning, as the total graph produced
    with ^by(^byvar^)^ ^total^ would superimpose spikes, not add them
    vertically.

The defaults for graph_options are

    ^l2title^ of "Frequency" (or "Fraction", if ^frac^ is
    used, or "Root of frequency", if ^root^ is used)

    ^b2title^ of the variable label of varname (or varname itself, if
    that is not defined)

    ^c(||)^, so that each bin or value is shown by a vertical spike

    ^sy(ii)^

Examples
--------

        . ^spikeplt wallasp, round(5)^
        . ^spikeplt day [w=rain] if rain, l2("Daily rainfall in mm") gap(5)^
        ^xla yla^
        . ^spikeplt age [w=pop], l2("Population in 000") gap(5) yla^
        ^xla(0,20,40,60,80) xti(10,30,50,70,90)^

References
----------

Berry, D.A. 1996. Statistics: a Bayesian perspective. Belmont, CA:
Duxbury Press.

Chapman, M. and Mahon, B. 1986. Plain figures. London: Her Majesty's
Stationery Office.

Tukey, J.W. 1972. Some graphic and semigraphic displays. In Bancroft,
T.A. and Brown, S.A. (eds) Statistical papers in honor of George W.
Snedecor. Ames, IA: Iowa State University Press, 293-316.

Tukey, J.W. 1977. Exploratory data analysis. Reading, MA:
Addison-Wesley, Ch. 17.

Velleman, P.F. and Hoaglin, D.C. 1981. Applications, basics, and
computing of exploratory data analysis. Boston, MA: Duxbury Press,
Ch. 9.

Authors
-------
         Nicholas J. Cox, University of Durham, U.K.
         n.j.cox@@durham.ac.uk

         Tony Brady, Royal Postgraduate Medical School, U.K.
         t.brady@@rpms.ac.uk

Also see
--------

    STB:  STB-40 gr25.1, STB-36 gr25
On-line: help for @graph@, @dotplot@, @kdensity@