ML estimation for Box-Cox power transformation
----------------------------------------------
by Patrick Royston, Royal Postgraduate Medical School, FAX:(011)-44-81-740 3119

^boxcoxr^ yvar [xvar(s)] [^in^ range] [^if^ exp] [^,^ [^delta(^#^) zero(^#^) ci(^#^) iter(^#^)
^lstart(^#^) ropt(^regression_options^) gen(^newvar^) anova symm quiet detail ^ ]

creates newvar = (yvar^^lambda-1)/lambda), where lambda is the maximum log like-
lihood (MLL) estimate. ^delta(^#^)^ specifies a small increment for calculating
derivatives of the log likelihood (LL) function and is by default 0.01.
^zero(^#^)^ specifies a value for the derivative of the LL which is regarded as
small enough to be considered zero to determine convergence and is by default
0.001. ^ci(^#^)^ is the confidence interval required for lambda; the default value
is no interval. Confidence intervals are calculated from the LL function and
should strictly be called "support intervals." ^iter(^#^)^ is the maximum number of
iterations permitted, the default number is 10. ^lstart(^#^)^ forces a starting 
value for lambda, default is chosen by the program. Specifying ^zero^ = 0 forces
the program to use the value of lambda in ^lstart^; no confidence interval is
then available.



If xvar(s) are specified, yvar is regressed on xvar(s) with regression options
defined in ^ropt^. If ^anova^ is specified, analysis of variance rather than
regression is done. ^quiet^ suppresses output. ^detail^ reports progress on
the convergence of the iterative process as it happens, and gives a plot
of the LL function against lambda (the 'profile likelihood').

If ^symm^ is specified, the data are transformed to zvar=1+abs(yvar-mean(yvar))
and the power, lambda, applied to zvar is found which maximizes the LL.

The program is iterative and is not guaranteed to converge to the maximum
likelihood estimate. Convergence may be achieved in difficult cases by 
varying (typically increasing) the value of ^delta^ and/or by trying different
starting values for lambda. A cruder approximate ML estimate may be obtained by
increasing the value of ^zero^. Alternatively the program may be used
'manually' by specifying single values of lambda and inspecting the LL values
which result. The plot previously obtained when ^detail^ was specified may
help here.

Stored are:
             ^%S_1^          Lambda
             ^%S_2^          Lower confidence limit for lambda
             ^%S_3^          Upper confidence limit for lambda
             ^%S_4^          Log likelihood for yvar
             ^%S_5^          Log likelihood for (yvar^^lambda-1)/lambda)

Example
-------
       ^. boxcoxr mpg^

finds the ML estimate of lambda.

       ^. boxcoxr mpg weight, gen(lmpg) ci(.95) detail^

finds the ML estimate of lambda and 95% confidence interval for regression
of (mpg^^lambda-1)/lambda on weight, giving progress reports. ^lmpg^ is created
as (mpg^^lambda-1)/lambda.