.-
help for ^bcoeff^                          
.-

Saving regression coefficients to new variable
----------------------------------------------

	^bcoeff^ yvar x1var [ otherxvars ] [^if^ exp] [^in^ range]
	^, by(^byvarlist^) g^enerate^(^newvar^)^ [ ^m^odel^(^model^) dxmin(^#^)^
	^n^min^(^#^) s^e^(^newvar^) c^ons^(^newvar^) d^ouble ^miss^ing ]

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

^bcoeff^ saves in a new variable regression coefficients (more generally, 
the b coefficient from a regression-like model) for each of several groups 
of observations. 

Remarks
------- 

Consider a regression ^regress y x1 x2 x3^. The regression produces, 
among other results, the b coefficient of ^y^ on ^x1^ given ^x2^ and ^x3^. 
This is left behind in ^_b[x1]^. 

Now consider a group variable ^g^. 

	. ^sort g^ 
	. ^by g: regress y x1 x2 x3^ 

produces a set of regressions, one for each group defined by ^g^. The 
b coefficient of ^y^ on ^x1^ given ^x2^ and ^x3^ for each group is left 
behind in ^_b[x1]^, but overwritten by each successive regression. ^bcoeff^ 
picks up each b coefficient for each group and puts them in a new variable.
Optionally, it also picks up the standard error of that coefficient, from
^_se[x1]^, and/or the constant (intercept) of the model, from ^_b[_cons]^. 

Note that in some cases, for example in the output of ^regress^ given a 
constant ^y^ and a variable ^x1^, the standard error is reported as ^.^ when 
strictly it is ^0^. This is a misfeature of Stata. ^bcoeff^ uses the vector 
^_se^, which in such cases correctly reports ^0^.

Note also that covariates may be dropped from a model, for example if the 
number of data points is fewer than the number of parameters to be estimated. 
In such cases, the b coefficient is reported as ^0^. Users may wish to use 
the ^nmin( )^ option to guard against this problem. 

With ^bcoeff^ which variables are named first and second is crucial. The 
first-named variable is the response variable. The second-named variable is 
the covariate for which the regression coefficient is saved. 
 

Options
-------

^by(^byvarlist^)^ specifies one or more variables that define distinct groups 
of observations. This is a required option. 

^generate(^newvar^)^ specifies a new variable to hold the regression 
coefficients. This is a required option. 

^model(^model^)^ indicates the model command used. It defaults to ^regress^. 
Any model may be used that leaves behind a vector in ^_b^.

^dxmin(^#^)^ specifies a minimum required range of x1var for each group. 
Regressions will not be performed if the actual range is less than or equal 
to this. Default is 0. 

^nmin(^#^)^ specifies a minimum required number of observations for each group. 
Regressions will not be performed if the actual number is less than this. 
Default is 2. 

^se(^newvar^)^ specifies a new variable to hold the standard error of each 
b coefficient.

^cons(^newvar^)^ specifies a new variable to hold the constant (intercept) 
from each model. 

^double^ specifies that each variable generated is to be of type double. 

^missing^ indicates that observations with missing values for byvarlist 
(either ^.^ or ^""^) are to be included in calculations. The default is 
to exclude such observations. 


Examples
--------

	. ^bcoeff weight age, by(id) g(b)^
	. ^bcoeff weight age, by(id) g(b) se(se)^


Authors
-------

	Zhiqiang Wang 
	Menzies School of Health Research
	Darwin Australia
	email: wang@@menzies.edu.au
	
	Nicholas J. Cox
        University of Durham, U.K.
        email: n.j.cox@@durham.ac.uk