{smcl}
{* 03mar2005}{...}
{cmd:help by}, {cmd:help bysort}
{hline}

{title:Title}

{p2colset 5 15 17 2}{...}
{p2col :{hi:[D] by} {hline 2}}Repeat Stata command on subsets of the data{p_end}
{p2col :{hi:[U] 11 Language syntax}}{p_end}
{p2colreset}{...}


{title:Syntax}

{p 8 12 2}
{cmd:by} {varlist}{cmd::} {it:stata_cmd}

{p 8 16 2}
{opt bys:ort} {varlist}{cmd::} {it:stata_cmd}

{pstd}
The above diagrams show {cmd:by} and {cmd:bysort} as they are typically
used.  The full syntax of the commands is

{p 8 12 2}
{cmd:by} {it:varlist1} [{cmd:(}{it:varlist2}{cmd:)}]
[{cmd:,} {opt s:ort} {cmd:rc0}]{cmd::}  {it:stata_cmd}

{p 8 16 2}
{opt bys:ort} {it:varlist1} [{cmd:(}{it:varlist2}{cmd:)}]
[{cmd:,} {cmd:rc0}]{cmd::}  {it:stata_cmd}


{title:Description}

{pstd}
Most Stata commands allow the {cmd:by} prefix, which repeats the command for
each group of observations for which the values of the variables in
{varlist} are the same.  {cmd:by} without the {cmd:sort} option requires
that the data must be sorted by {it:varlist}; see {helpb sort}.

{pstd}
Stata commands that work with the {cmd:by} prefix indicate this immediately
following their syntax diagram by reporting, for example,
"{cmd:by} may be used with {cmd:alpha}; see {helpb by}" or "{cmd:bootstrap}, 
{cmd:by}, etc. are allowed; see {help prefix}".

{pstd}
{cmd:by} and {cmd:bysort} are really the same command; {cmd:bysort} is just
{cmd:by} with the {cmd:sort} option.

{pstd}
The {it:varlist1} {cmd:(}{it:varlist2}{cmd:)} syntax is of special use to
programmers.  It verifies that the data are sorted by 
{bind:{it:varlist1 varlist2}} and then performs a {cmd:by} as if only
{it:varlist1} were specified.  For instance,

{phang2}
{cmd:by pid (time): gen growth = (bp - bp[_n-1])/bp}

{pstd}
performs the {cmd:generate} by values of {hi:pid} but first verifies that
the data are sorted by {hi:pid} and {hi:time} within {hi:pid}.


{title:Options}

{phang}
{opt sort} specifies that if the data are not already sorted by {varlist},
{cmd:by} sort them.

{phang}
{opt rc0} specifies that even if the {it:stata_cmd} produces an error in one
of the by-groups, then {cmd:by} is still to run the {it:stata_cmd} on the
remaining by-groups.  The default action is to stop when an error occurs.
{opt rc0} is especially useful when {it:stata_cmd} is an estimation command,
and some by-groups have insufficient observations.


{title:Examples}

{phang}{cmd:. sort marstat}{p_end}
{phang}{cmd:. by marstat:  summarize age}

{phang}{cmd:. by marstat, sort:  summarize age}

{phang}{cmd:. bysort marstat:  summarize age}

{phang}{cmd:. sort sex marstat}{p_end}
{phang}{cmd:. by sex marstat:  regress y x1 x2 x3}

{phang}{cmd:. by sex marstat, sort:  regress y x1 x2 x3}

{phang}{cmd:. bysort sex marstat:  regress y x1 x2 x3}

{phang}{cmd:. sort pid time}{p_end}
{phang}{cmd:. by pid (time): gen growth = (bp - bp[_n-1])/bp}

{phang}{cmd:. by pid (time), sort: gen growth = (bp - bp[_n-1])/bp}

{phang}{cmd:. bysort pid (time): gen growth = (bp - bp[_n-1])/bp}


{title:Also see}

{psee}
Manual:  {bf:[D] by}

{psee}
Online:  
{help byprog},
{helpb foreach},
{helpb forvalues},
{helpb sort},
{helpb statsby},
{helpb while}
{p_end}