.-
help for ^treatreg^                                        
.-

treatment effects model
-----------------------

    Basic syntax:

	^treatreg^ depvar [varlist]^,^ ^tr^eat^(^depvar_s ^=^ varlist_s^)^ [^two^step]

    Full syntax for maximum-likelihood estimates only:

	^treatreg^ depvar [varlist] [weight] [^if^ exp] [^in^ range]^,^
		^tr^eat^(^depvar_s ^=^ varlist_s [^,^ ^noc^onstant]^)^
		[ ^r^obust ^cl^uster^(^varname^)^ ^ha^sard^(^varname^)^ ^noc^onstant 
		^fir^st ^noskip^ ^l^evel^(^#^)^ ^iter^ate^(0)^ maximize_options ]


    Full syntax for the two-step consistent estimates only:

	^treatreg^ depvar [varlist] [^if^ exp] [^in^ range]^,^ ^two^step
		^tr^eat^(^depvar_s ^=^ varlist_s [^,^ ^noc^onstant]^)^
		[ ^ha^zard^(^varname^)^ ^noc^onstant ^fir^st ^l^evel^(^#^)^ ]


^pweight^s, ^aweight^s, ^fweight^s and ^iweight^s are allowed with full ML estimates;
    see help @weights@.  No weights are allowed with the ^twostep^ estimates.

^treatreg^ shares the features of all estimation commands; see help @est@.


The syntax of @predict@ following ^treatreg^ is

	^predict^ [type] newvarname [^if^ exp] [^in^ range] [^,^ statistic ^nooff^set]

where statistic is

	^xb^                 fitted values for regression equation; the default
	^stdf^               standard error of the forecast
	^stdp^               standard error of the prediction
	^yct^rt              E(y | treatment = 1)
	^ycn^trt             E(y | treatment = 0)
	^pt^rt               P(treatment = 1)
	^xbt^rt              linear prediction for treatment equation
	^stdpt^rt            standard error of treatment linear pred.

These statistics are available both in and out of sample; type "^predict^ ...
^if esample(),^ ..." if wanted only for the estimation sample.


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

^treatreg^ estimates treatment effects models using either Heckman's two-
step consistent estimator or full maximum-likelihood.

treatreg estimates all of the parameters in the model

	y = xb + dz + e				(regression equation:
						 y is depvar, x is varlist
						 z is treatment dummy var) 

	z = 1 if  Wg + u > 0			(treatment equation:
						 W is varlist_s)

	where:
		e ~ N(0, sigma)
		u ~ N(0, 1)
		corr(e, u) = rho

In the syntax for ^treatreg^, depvar and varlist are the dependent variable
and regressors for the underlying regression model to be estimated and
depvar_s is the treatment dummy variable (z), varlist_s are the variables (W)
thought to determine whether assigned treatment or not. 


Options
-------

^treat(...)^ specifies the variables and options for the treatment equation.  It
    is an integral part of specifying a treatment effects model and is not 
    optional.

^twostep^ specifies that Heckman's (1979) two-step efficient estimates of the
    parameters and covariance matrix (standard errors) of the model are to be
    produced.

^robust^ specifies that the Huber/White/sandwich estimator of variance is to be
    used in place of the traditional calculation.  ^robust^ combined with
    ^cluster()^ further allows observations which are not independent within
    cluster (although they must be independent between clusters).
    See ^[U] 23.11 Obtaining robust variance estimates^.

^cluster(^varname^)^ specifies that the observations are independent across groups
    (clusters) but not necessarily independent within groups.  varname
    specifies to which group each observation belongs; e.g., ^cluster(personid)^
    in data with repeated observations on individuals.  ^cluster()^ can be used
    with @pweight@s to produce estimates for unstratified cluster-sampled data.
    Specifying ^cluster()^ implies ^robust^.

^hazard(^varname^)^ creates a new variable containing the hazard from the treatment
    equation.  With the options ^twostep^ or ^iterate(0)^, the hazard is derived
    from a @probit@ regression of whether the treatment is assigned.  Under full
    maximum- likelihood, the hazard is derived from the parameter estimates of
    the treatment equation.

^noconstant^ omits the constant term from the equations.  This option may be
    specified on either the regression equation or the treatment equation.


^first^ specifies that the first-step probit estimates of the treatment equation
    be displayed prior to estimation.

^noskip^ specifies that a full maximum-likelihood model with only a constant for
    the regression equation be estimated.  This model is not displayed but is
    used as the base model to compute a likelihood-ratio test for the model
    test statistic displayed in the estimation header.  By default, the over-
    all model test statistic is an asymptotically equivalent Wald test of all
    the parameters in the regression equation being zero (except the constant).
    For many models, this option can significantly increase estimation time.

^level(^#^)^ specifies the confidence level in percent for confidence intervals
    of the coefficients; see help @level@.

^iterate(0)^ produces Heckman's (1979) two-step parameter estimates with standard
    errors computed from the inverse Hessian of the full information matrix at
    the two-step solution for the parameters.  As an alternative, the ^twostep^
    option computes Heckman's two-step consistent estimates of the standard
    errors.  ^iterate(^#^)^ can also be used to restrict the maximum number of
    iterations during optimization; see help @maximize@.

maximize_options control the maximization process; see help @maximize@.  You will
    likely never need to specify any of the maximize options except for
    ^iterate(0)^ and possibly ^difficult^.  If the iteration log shows many "not
    concave" messages and it is taking many iterations to converge, you may
    want to try using the ^difficult^ option and see if that helps it to converge
    in fewer steps.


Options for @predict@
-------------------

^xb^, the default, calculates the linear predictions from the underlying regres-
    sion equation.

^stdp^ calculates the standard error of the prediction from the underlying
    regression equation.

^stdf^ calculates the standard error of the forecast of the underlying regression
    equation.  This is often informally referred to as the standard error of
    the prediction.  By construction, the standard errors produced by ^stdf^ are
    always larger than those by ^stdp^; see ^[R] regress^.

^yctrt^ calculates the expected value of the dependent variable conditional on
    the treatment being assigned; E(y | z=1).

^ycntrt^ calculates the expected value of the dependent variable conditional on
    the treatment being unassigned; E(y | z=0).

^ptrt^ calculates the probability of being assigned the treatment:
    P(z=1) = Pr(w_j*g + u_j > 0).

^xbtrt^ calculates the linear prediction for the treatment equation.

^stdptrt^ calculates the standard error of the linear prediction for the
    treatment equation.


Example
-------

    To obtain full ML estimates:

	. ^treatreg ww wa cit, treat(wc=wmed wfed)^ 

    To obtain Heckman's two-step consistent estimates:

	. ^treatreg ww wa cit, treat(wc=wmed wfed) twostep^

    To define and use each equation separately:

	. ^global wage_eqn ww wa cit^
	. ^global trteqn wc=wmed wfed^
	. ^treatreg $wage_eqn, treat($trteqn)^


    Prediction:

	. ^treateg ww wa cit, treat(wc=wmed wfed)^ 
	. ^predict yhat^
	. ^predict yhat, xb^

	. ^predict mystdp, stdp^
	. ^predict mystdf, stdf^

	. ^predict yctrt, yctrt^
	. ^predict ycntrt, ycntrt^
	. ^predict probtrt, ptrt^
	. ^predict trtindex, xbtrt^


Also see
--------

 Manual:  ^[U] 23 Estimation and post-estimation commands^,
	  ^[U] 29 Overview of model estimation in Stata^,
	  ^[R] heckman^
On-line:  help for @est@, @postest@; @heckman@, @heckprob@, @tobit@
