-------------------------------------------------------------------------------
help for levels7
-------------------------------------------------------------------------------

Levels of integer or string variable

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


Description

levels7 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

levels7 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.  levels7 leaves behind a list in r(levels) which may be used in
a subsequent command.

If working with string variables, note that Stata trims leading spaces in any
operation of a form necessarily used within this program:

        local macroname = string_variable[i]

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

levels7 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

local(macname) inserts the list of values in local macro macname within the
    calling program's space. Hence that macro will be accessible after levels7
    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

    . levels7 rep78

    . levels7 rep78, sep(,)

    . levels7 rep78, miss

    . levels7 make if foreign

    . levels7 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. 


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