.-
help for ^bys^                                    (Jeroen Weesie  March 21, 1995)
.-

Automatically sorting `by'
---------------------------

        ^bys^ varlist [^(^varlist2^)^] ^:^ command


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

By ^bys^ command is very similar to ^by varlist: command^ but automatically sorts
on the variables in varlist. 

If a second varlist, varlist2, is specified between parentheses, ^bys^ will
sort the data on varlist2 within varlist. This may be required for some more 
complicated commands, in particular to generate variables within subgroups 
(see example 2 below). 

If the data are already sorted on varlist and further variables, 
the sort order is not changed. The command may not contain quotes (").


Example
--------

Ex 1.   . ^bys age: summ inc^

is equivalent to

        . ^sort age^
        . ^by age: summ inc^
  
Ex 2. We want to assign to people their rank-number with respect to age
in their own sex group.

        . ^bys sex (age): gen rank = _n^

would be equivalent to

        . ^sort sex age^
        . ^by sex: gen rank = _n^

In this last 2-line solution it may not be directly apparent that the 
by: construct only works correctly if the data were sorted appropriately 
within the by-groups. Using ^bys^ makes this more transparent.

Note that the equivalence in both examples is not perfect: ^bys^ will not
sort the data if they have already been sorted on the required variables. 
Thus, if the data were sorted on more variables, the original sorting order
and Stata's information about ordering will be left unchanged.


Author
-------

        Jeroen Weesie
        Dept of Sociology/ICS
        Utrecht University
        J.Weesie @@ fss.uu.nl


Also see
---------

Manual:  [2] by
On-line: ^help^ for @by@