.-
help for ^byvar^                                                   [STB-27: ip9]
.-

Repeat command by variable(s)
-----------------------------

	^byvar^ varlist [^,^ options ] ^:^ stata_cmd

where options are

	^m^acro^(^mlist^)^ ^r^esult^(^rlist^)^ ^c^oef^(^coeflist^)^ ^s^e^(^selist^)^
	^gen^erate ^st^ore ^ta^bulate ^mi^ssing ^p^ause


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

^byvar^ repeats stata_cmd for each distinct combination of values in varlist.
For details of storage of results, see the ^generate^ and ^store^ options.


Options
-------

^macro(^mlist^)^ stores the values of global macros which are named in mlist.
    The macros must evaluate to numbers (strings are not allowed). The macro
    names must be separated by space(s). You may append a label, preceded by
    an ^=^ sign, to each macro name; this will be used to label the correspond-
    ing column of output (if the ^tabulate^ option is used) or variable (if the
    ^generate^ option is used).  The label may be no longer than 13 characters
    and must not contain spaces, commas, colons or equals signs. Example:
    ^macro(S_1=number_of_obs S_2=Shapiro-Wilk)^.

^result(^rlist^)^ stores the values of ^_result()^ whose arguments are given in
    rlist.  Individual items may be labelled as with the ^macro()^ option.

^coef(^clist^)^ stores the regression coefficients for variables named in clist.
    Individual items may be labelled as with the ^macro()^ option.

^se(^slist^)^ stores the standard errors of regression coefficients for variables
    named in slist.  Individual items may be labelled as with the ^macro()^
    option.

^generate^ creates new variable(s) corresponding to the quantities named in the
    ^macro()^, ^result()^, ^coef()^ and ^se()^ options.  The names of the new variables
    begin with ^_M_^#, ^_R_^#, ^_C_^# and ^_S_^#, respectively.  Sequence numbers (#)
    correspond to the items stored.  For example, ^macro(S_1 S_3) generate^ would
    create variables called ^_M_1^ and ^_M_2^, containing the values of macros
    ^$S_1^ and ^$S_3^, respectively, which are "left behind" by each execution of
    stata_cmd.  Results are stored according to the combinations of values of
    the variables in varlist.

^store^ stores results corresponding to the quantities named in the ^macro()^,
    ^result()^, ^coef()^ and ^se()^ options in global macros whose names begin with
    ^M^#^_^, ^R^#^_^, ^C^#^_^ and ^S^#^_^ respectively.  The #'s are sequence numbers which
    correspond to the numbers of items stored.  These suffices are followed by
    integer codes which index the combinations of values of the variables in
    varlist.  For example, ^macro(S_1 S_3)^ would create macros called ^$M1_1^,
    ^$M1_2^, ... containing successive values of macro ^$S_1^.  Similarly, ^$M2_1^,
    ^$M2_2^, ... would contain successive values of macro ^$S_3^.

^tabulate^ displays the results in tabular form, suppressing the output (if any)
    from stata_cmd.

^missing^ causes stata_cmd to be executed even when a combination of values of
    any of the variables in varlist involves a missing value.  The idea is the
    same as for the ^missing^ option in Stata's @tabulate@ command.

^pause^ pauses output after each execution of stata_cmd.


Remarks
-------

In programming ^byvar^, I have attempted to solve an awkward problem: how to
incorporate an ^if^ phrase, if one is specified in stata_cmd, when filtering
stata_cmd according to values in varlist.  I have done so by searching for
"^if^" in the part of stata_cmd which precedes the first comma if one is
present, or in the whole of stata_cmd if not.  There may be types of stata_cmd
for which this will not work correctly, but so far none have been encountered.


Examples
--------

 . ^use auto^

To produce a Normal Q-Q plot of ^weight^ for each non-missing value of ^rep78^:

 . ^byvar rep78 : qnorm weight^

To carry out Shapiro-Wilk tests on ^mpg^ for each of the 6 values of ^rep78^
including missing, store the W-statistics (^$S_2^) in macros ^$M1_1^,..., ^$M1_6^
and their P-values (^$S_5^) in macros ^$M2_1^, ..., ^$M2_6^, and display the results
in tabular form, with columns headed W and P-value:

 . ^byvar rep78, macro(S_2=W S_5=P-value) store tabulate missing : swilk mpg^

To create two new variables: ^_R_1^ containing ^_result(9)^, i.e. the regression
mean square error, for each of the two values of ^foreign^, and ^_C_1^ containing
the estimated regression coefficients for ^mpg^ on ^weight^:

 . ^byvar foreign, result(9) coef(weight) generate : regress mpg weight^


Author
------

        Patrick Royston
        Royal Postgraduate Medical School, London
        FAX:  (011)-44-181-740-3119


Also see
--------

    STB:  STB-27 ip9
 Manual:  [2] by
On-line:  help for @by@