-------------------------------------------------------------------------------
help for catplot
-------------------------------------------------------------------------------

Plots of frequencies, fractions or percents of categorical data 

        catplot {bar|hbar|dot} catvar1 [catvar2 [catvar3]] [weight] [if exp]
                 [in range] [ ,
                 {fraction|fraction(varlist)|percent|percent(varlist)}
                 missing sort descending graph_options ]


Description

    catplot shows frequencies (or optionally fractions or percents) of the
    categories of one, two or three categorical variables. The first named
    variable is innermost on the display; that is, its categories vary
    fastest.  The syntaxes catplot bar, catplot hbar and catplot dot are
    specified to indicate use of graph bar, graph hbar and graph dot
    respectively. The choice is a matter of personal taste, although in
    general horizontal displays make it easier to identify names or labels of
    categories.

    fweights, aweights and iweights may be specified.


Remarks 

    The default display with bar and hbar is graphically conservative,
    reflecting the view that height of bars and text indicating categories
    are the best ways of conveying information. If you wish also to have bars
    in different colours, specify the option asyvars, which differentiates
    the categories of the first named variable catvar1. If you wish also to
    stack bars of different colours, specify the further option stack.

    The default display with dot is similarly conservative.  If you wish to
    have point symbols in different colours, specify the option asyvars,
    which differentiates the categories of the first named variable catvar1.
    If you wish also to use different point symbols, use the further option
    marker().


Options 

    fraction indicates that all frequencies should be shown as fractions
        (with sum 1) of the total frequency of all values being represented
        in the graph.

    fraction(varlist) indicates that all frequencies should be shown as
        fractions (with sum 1) of the total frequency for each distinct
        category defined by the combinations of varlist. For example, given a
        variable sex with two categories male and female, the fractions shown
        for male would have sum 1 and those for female would have sum 1.

    percent indicates that all frequencies should be shown as percents (with
        sum 100) of the total frequency of all values being represented in
        the graph.

    percent(varlist) indicates that all frequencies should be shown as
        percents (with sum 100) of the total frequency for each distinct
        category defined by the combinations of varlist.  For example, given
        a variable sex with two categories male and female, the percents
        shown for male would have sum 100 and those for female would have sum
        100.

    Only one of these fraction[()] and percent[()] options may be specified.

    missing specifies that any missing values of any of the variables
        specified should also be included within their own categories.

    sort specifies that values shown should be sorted in each category
        (higher values at the bottom of each category).  Sorting is applied
        to all variables shown.

    descending specifies that sorted values should be shown in descending
        order (higher values at the top of each category).

    graph_options refers to options of graph bar, graph hbar or graph dot as
        appropriate.  by() is one useful example.

Examples

    . sysuse auto

    . catplot hbar rep78 foreign
    . catplot bar rep78, by(foreign) percent(foreign)
    . gen himpg = mpg > 25
    . catplot hbar himpg rep78 foreign

    . catplot hbar rep78 foreign, percent(foreign) bar(1, bcolor(blue))
        blabel(bar, position(outside) format(%3.1f)) ylabel(none)
        yscale(r(0,60))

    . catplot hbar rep78, sort
    . catplot hbar rep78, sort desc


Author

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

         
Acknowledgements 

    Vince Wiggins provided very helpful comments.  Fred Wolfe asked for
    sorting. David Schwappach provided feedback on limitations.


Also see

    On-line:  help for histogram