.-
help for ^barplot^
.-

Bar plot
--------

    ^barplot^ yvarlist xvar [^if^ exp] [^in^ range]
    [ ^, w^idth^(^string^) b^ase^(^string^) m^onths ^join^
    graph_options ]

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

^barplot^ produces a plot of the variables in yvarlist against xvar.
Each variable in yvarlist is plotted as a series of unshaded bars rising
above or falling below one or more base lines. The height of each bar is
given by the y variable, the width via the width option, the base via
the base option and the horizontal centre of each bar by xvar.

^barplot^ could be used, for example, to

    plot monthly totals or other time series as a series of touching
    bars, positive and negative values shown upwards and downwards
    (rainfall/evaporation, profit/loss, income/expenditure)

    show histograms, especially those with more than 50 bins (classes)
    or unequal bin widths (class intervals), or with unshaded bars

    show the difference between two histograms as a series of bars that
    may be positive or negative

    show J.W. Tukey's rootograms, with the square root of frequencies on
    the y axis.

Note especially in the case of histograms or rootograms that the
frequencies must be calculated beforehand.

Through the ^width()^ option, ^barplot^ could be used to produce
overlapping or underlapping bars, if desired for some reason.


Options
-------

^width(^string^)^ specifies how the widths of the bars are determined.
    ^width(^widthvar^)^ specifies that they are given by widthvar.
    ^width(^#^)^ specifies that they are constant and equal to #.
    The default is ^width(1)^.

^base(^string^)^ specifies how the bases of the bars are determined.
    ^base(^basevar^)^ specifies that they are given by basevar.
    ^base(^#^)^ specifies that they are constant and equal to #.
    The default is ^base(0)^.

^months^ without ^xlabel( )^ automatically produces
    ^xla(1,2,3,4,5,6,7,8,9,10,12)^.

^join^ specifies that bars that do not touch will be joined, i.e.
    connected by fragments of a baseline. Separate bars usually look
    better on histograms containing gaps (bins with zero frequency).
    Joined bars often look better with time series plots.

graph_options are options allowed with ^graph, twoway^, other than
    ^symbol^ and ^connect^, which are set to ^i^ and ^L^ for each y
    variable, and ^xlabel^ by itself. Note that these options do not
    include ^shading^.


Examples
--------

        . ^barplot pop age^
        . ^barplot rain month, mon^
        . ^barplot males females age^

    Histogram from data:

        . ^genfreq r if r > 0, w(1) b(Br) f(Fr)^
        . ^barplot Fr Br, w(1)^

    OR  . ^histplot r if r > 0, w(1)^

    Histogram from data, discrete variables:

        . ^egen freq = count(rep78), by(rep78)^
    OR  . ^genfreq rep78, fg(freq)^

        . ^barplot freq rep78, w(0.5) yla xla(1,2,3,4,5)^

    Histogram with unequal bin widths (Snedecor and Cochran, 1989,
    p.19):

        . ^input centre width freq^
        . ^112.5 25 38^
        . ^137.5 25 27^
        . ^162.5 25 15^
        . ^187.5 25 11^
        . ^250 100 4^
        . ^350 100 4^
        . ^450 100 1.8^
        . ^550 100 2^
        . ^700 200 1.2^
        . ^900 200 0.2^
        . ^barplot freq centre, w(width) l2(Frequency per 25000)^
            ^b2(Population in 000) yla^

    Superimposed histograms for different groups:

        . ^genfreq length, w(5) bg(Blength) fg(Flength) by(foreign)^
        . ^gen Flengthf = Flength if foreign^
        . ^gen Flengthd = Flength if !foreign^
        . ^barplot Flengthf Flengthd Blength, w(5)^

    Normal and inverted histograms for different groups:
        . ^gen nFlf = -Flength if foreign^
        . ^barplot nFlf Flengthd Blength, w(5)^

    Separate histograms for different groups:

        same colour:
        . ^barplot Flength Blength, w(5) by(foreign)^

        different colours:
        . ^barplot Flengthf Flengthd Blength, w(5) by(foreign)^

    Superimposed histograms for different variables:

        . ^genfreq n, w(0.5) bg(Bn) fg(Fn)^
        . ^genfreq x, w(0.5) bg(Bx) fg(Fx)^
        . ^stack Bx Fx Bn Fn, into(B F) wide clear^
        . ^barplot Fx Fn B, w(0.5)^

    Separate histograms for different variables:
        . ^barplot Fx Fn B, w(0.5) by(_stack)^


Author
------

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


Also see
--------

On-line: help for @graph@, @spikeplt@ (if installed), @genfreq@ (if
         installed), @histplot@ (if installed)