.-
help for ^switchr^             				[Beta version]
       
.-

switchr
-------

     ^switchr^ eq1 eq2 [weight] [^if^ exp] [^, cl^uster^(^string^)
strata(^string^)^
	^sige^qual ^tol(^real^)^ ^itout(^integer^)^ ^noisyn(^integer^)^ ]


The user must define eq1, which will be the two component regressions.  eq2 is
	the classification regression.  It must be defined by the user so that
	its dependent variable is a variable containing an initial guess of the
	partition of the observations into the two components.  This initial
	guess variable will be overwritten by ^switchr^ to contain the 
	probabilities that a given observation adheres to the first component 
	regression.


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

^Switchr^ calculates switching regression estimates for a two-component model
in which observations are drawn from two different regression regimes (or
components), but separation into the separate regimes is unobserved.  Such
a situation is also called a mixture model.


Options
-------

^cluster^ and ^strata^ invoke the _robust variance calculations, by using
	@svyreg@.

^sige^qual forces the variance of the two component regressions to be the 
	same.

^tol^ specifies a threshold such that, when the largest relative change among
	the coefficients from one iteration to the next is less than ^tol^(), 
	estimates are declared to have converged.  The default is ^tol(^1e-4^)^.

^itout()^ and ^noisyn()^ control reporting of progress on the iterations and of
	intermediate output.  ^itout(^#^)^ specifies that every # iterations,
	the convergence criterion, the mean and mean change of the 
	classification vector, and the time taken for that iteration be 
	reported.  The default is ^itout(^20^)^.  ^noisyn(^#^)^ specifies that
	every # iterations, the	regression results on the two component 
	regressions be reported.  In addition, results for a modified version
	of the classification vector are reported.  These classifications 
	results are accurate up to a constant (across coefficients) scaling 
	parameter.  The default is ^noisyn(^16000^)^.


Remarks
-------

Consider the following system, in which observed values of the dependent 
variable come from one of two regression regimes, but where it is unknown
a priori which regime produced any given observation:
y(1) = x b(1) + u(1)	u(1) ~ N(0,sigma(1)-squared)
y(2) = x b(2) + u(2)	u(2) ~ N(0,sigma(2)-squared)
y(3) = x b(3) + u(3)	u(3) ~ N(0,sigma(3)-squared)
and y = y(1) if y(3) < 0
and y = y(2) if y(3) >= 0
The outcome y is observed; y(1), y(2), and y(3) are latent.

^Switchr^ produces estimates of b(1), b(2) and b(3), and of sigma(1) and 
sigma(2), which may be equal or different.  Sigma(3) is unidentified, and
assumed to be 1.

Exact standard errors in a switching regression are not available.  This 
addition provides good approximate standard errors.  The program can be used 
iteratively to obtain bootstrapped standard errors.

To obtain these estimates, ^switchr^ maximizes the likelihood function through
the EM algorithm of Dempster, Laird and Rubin (1977), as further 
articulated by Hartley (1978).  This iterative method first estimates the 
classification vector, i.e., the probability that a given observation is in 
the first component regression.  This estimate is obtained by (in part) 
reweighting the probabilities based on the errors of the observations in the 
two component regressions.  The updated probabilities are then used to weight 
observations in each of the two separate component regressions.  This 
iterative procedure eventually converges to the maximum likelihood estimates 
of the above three-equation regression model.

Because the likelihood surface is not globally concave, several local maxima 
are possible.  ^Switchr^ can be used iteratively to find the local maximum 
with the highest likelihood value, by searching from different starting 
values of the classification vector.  If sigma(1) and sigma(2) are allowed to 
differ (the default), problems can arise in which one variance is driven to 
zero, with a very small number of observations sorted into the corresponding 
component regime.  One solution to this problem is to use the ^sige^qual 
option to force the two variances to be the same.

The program uses a linear version of the probability regression of the 
classification regression.  Therefore, intermediate results are valid only up 
to a scale parameter.  In a final step, once the regression results have 
converged, the classification regression is re-run using a (slower) maximum 
likelihood modified logit regression.

Users should be aware of several caveats in using this method.  First, 
switching regressions of this sort are valid only when errors are 
independent, and identically distributed.  The independence of errors
across equations can be a strong assumption.  Second, standard errors 
are not exact, and will in general be biased downward.  Finally, 
convergence is not monotonic in the convergence criterion 
measure (relative change in the coefficient estimates).  Therefore, it is 
prudent to be conservative in the convergence criterion. 

This program uses @elapse@ to help with the timing of the iterations.

The full complement of programs needed for ^switchr^ is: switchr.ado, 
switchr.hlp, elapse.ado, elapse.hlp, and classif.ado.



Examples
--------
	
  ^use c:/statadata/sadata^
  ^gen double Guesprob = 0^
  ^quietly summarize lnpce^
  ^replace Guesprob = 1 if lnpce > _result(10)^
  ^delimit ;^
  ^eq main : hazscore docdist nursdist phardist father mother gender ^
	^lnpce crop_siz urban rural ;^
  ^eq regime : Guesprob lnpce members maxfe1 maxfe2 highfe^
        ^urban rural KZN Ecape NorP reticul elect ; ^

  ^switchr main regime [pweight=rsweight] , cl(clustnum) noisyn(200) sige ;^



References
----------

	Dempster, Laird and Rubin (1977) "Maximum likelihood from incomplete
data via the EM algorithm, Jornal of the Royal Statistical Society, 
Ser. B. 39 1-38.

	Michael J. Hartley (1978) "Comment" Journal of the American
Statistical Association, v. 73 (December): 738-741.



Saved Results
-------------

S_E_ll is the log-likelihood of the full problem.


Author
------

     Frederic Zimmerman
     Food Research Institute
     Stanford University
     zimmer@@leland.stanford.edu
     
