-------------------------------------------------------------------------------
help for levels
-------------------------------------------------------------------------------

Levels of integer or string variable

        levels varname [if exp] [in range] [ , clean local(macname) missing
                 separate(separator) ]


Description

    levels displays a sorted list of the distinct values of varname, which
    should be a variable taking on integer or string values, or in other
    words, a categorical variable, very broadly so defined.


Remarks

    levels serves two different functions.  Occasionally, it serves to give a
    compact display of the distinct values of varname.  More commonly, it may
    be useful when it is desired to cycle through the distinct values of
    varname with (say) foreach.  levels leaves behind a list in r(levels)
    which may be used in a subsequent command.

    levels may not be used if varname contains non-integer numeric values.

    levels may hit the limits imposed by your Stata. However, it is likely to
    be most useful when the number of distinct values of varname is modest.

    The terminology of levels of a factor has long been standard in
    experimental design. See, for example, Cochran and Cox (1957, p.148) or
    Yates (1937, p.5).


Options

    clean displays string values without compound double quotes.  By default,
        each distinct string value is displayed within compound double
        quotes, as these are the most general delimiters. If you know that
        the string values in varname do not include embedded spaces or
        embedded quotes, then this is an appropriate option. clean has no
        effect on the display of integer values.

    local(macname) inserts the list of values in local macro macname within
        the calling program's space. Hence that macro will be accessible
        after levels has finished.  This is helpful for subsequent use,
        especially with foreach.

    missing specifies that missing values of varname should be included in
        the calculation.  The default is to exclude them.

    separate(separator) specifies a separator to serve as punctuation for the
        values of the returned list.  The default is a space. The most
        obviously useful alternative is a comma.


Examples

    . levels rep78

    . levels rep78, sep(,)

    . levels rep78, miss

    . levels make if foreign

    . levels factor, local(levels)
    . foreach l of local levels {
    .        di "-> factor = `l'"
    .        whatever if factor == `l'
    . }

   
Saved results 

    r(levels)        list of distinct values


Author 

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


Acknowledgements 

        
    Nicholas Winter identified a bug in a previous version.  Kit Baum made a
    suggestion which led to the clean option.


References      

    Cochran, W.G. and G.M. Cox. 1957. Experimental design.  New York: John
        Wiley.

    Yates, F. 1937. The design and analysis of factorial experiments.
        Harpenden: Imperial Bureau of Soil Science Technical Communication
        35.

Also see

    On-line:  help for foreach; limits