{smcl}
{* 24may2007}{...}
{cmd:help mixlogit}{right:(SJ7-3: st0133)}
{hline}

{title:Title}

{p2colset 5 17 19 2}{...}
{p2col :{hi:mixlogit} {hline 2}}Mixed logit model{p_end}
{p2colreset}{...}


{title:Syntax}

{p 8 15 2}
{cmd:mixlogit}
{depvar}
[{indepvars}] {ifin}{cmd:,}
{cmdab:gr:oup(}{varname}{cmd:)}
{cmdab:rand:(}{varlist}{cmd:)}
[{opt id(varname)}
 {opt ln(#)}
 {opt corr}
 {opt nrep(#)}
 {opt burn(#)}
 {opt l:evel(#)}
 {opt const:raints(numlist)}
 {it:maximize_options}]


{p 8 15 2}
{cmd:mixlpred}
{newvar} {ifin}
[{cmd:,} {opt nrep(#)} {opt burn(#)}]


{p 8 15 2}
{cmd:mixlcov}
[{cmd:,}
{opt sd}]


{title:Description}

{pstd}
{cmd:mixlogit} fits mixed logit models by using maximum simulated likelihood
(Train 2003). The data setup is the same as for {cmd:clogit}.

{pstd}
{cmd:mixlpred} can be used following {cmd:mixlogit} to obtain
predicted probabilities. The predictions are available both in and out of
sample; type {cmd:mixlpred} ... {cmd:if e(sample)} ... if predictions are
wanted for the estimation sample only.

{pstd}
{cmd:mixlcov} can be used following {cmd:mixlogit} to obtain the elements in
the coefficient covariance matrix along with their standard errors. This
command is relevant only when the coefficients are specified to be correlated;
see the {opt corr} option below.  {cmd:mixlcov} is a wrapper for {cmd:nlcom}
(see {manhelp nlcom R}).


{title:Options for mixlogit}

{phang}
{opth group(varname)} is required and specifies a numeric identifier variable
for the choice occasions.

{phang}
{opth rand(varlist)} is required and specifies the independent variables whose
coefficients are random. The random coefficients can be specified to be
normally or lognormally distributed (see the {opt ln()} option).  The
variables immediately following the dependent variable in the syntax are
specified to have fixed coefficients (see the examples below).

{phang}
{opth id(varname)} specifies a numeric identifier variable for the decision
makers.  This option should be specified only when each individual performs
several choices; i.e., the dataset is a panel.

{phang}
{opt ln(#)} specifies that the last {it:#} variables in {opt rand()} have
lognormally rather than normally distributed coefficients.  The default is
{cmd:ln(0)}.

{phang}
{opt corr} specifies that the random coefficients are correlated.  The default
is that they are independent. When the {opt corr} option is specified, the
estimated parameters are the means of the (fixed and random) coefficients plus
the elements of the lower-triangular matrix L, where the covariance matrix for
the random coefficients is given by V = LL'.  The estimated parameters are
reported in the following order: the means of the fixed coefficients, the
means of the random coefficients, and the elements of the L matrix.  The
{cmd:mixlcov} command can be used postestimation to obtain the elements in
the V matrix along with their standard errors.

{p 8 8 2}
If the {opt corr} option is not specified, the estimated parameters are the
means of the fixed coefficients and the means and standard deviations of the
random coefficients, reported in that order. The sign of the estimated
standard deviations is irrelevant. Although in practice the estimates may be
negative, interpret them as being positive.

{p 8 8 2}
The sequence of the parameters is important to bear in mind when specifying
starting values.

{phang}
{opt nrep(#)} specifies the number of Halton draws used for the simulation.
The default is {cmd:nrep(50)}.

{phang}
{opt burn(#)} specifies the number of initial sequence elements to drop when
creating the Halton sequences. The default is {cmd:burn(15)}. Specifying
this option helps reduce the correlation between the sequences in each
dimension.  Train (2003, 230) recommends that {it:#} should be at least as
large as the prime number used to generate the sequences. If there are K
random coefficients, {cmd:mixlogit} uses the first K primes to generate
the Halton draws.

{phang}
{opt level(#)}; see {help estimation options}.

{phang}
{opth constraints(numlist)}; see {help estimation options}.
 
{phang}
{it:maximize_options}:
{opt dif:ficult}
{opt tech:nique(algorithm_spec)}, 
{opt iter:ate(#)}, {opt tr:ace}, {opt grad:ient}, 
{opt showstep}, {opt hess:ian}, {opt tol:erance(#)}, 
{opt ltol:erance(#)} {opt gtol:erance(#)}, {opt nrtol:erance(#)}, 
{opt from(init_specs)}; see {manhelp maximize R}.
{opt technique(bhhh)} is not allowed.


{title:Options for mixlpred}

{phang}
{opt nrep(#)} specifies the number of Halton draws used for the simulation.
The default is {cmd:nrep(50)}.

{phang}
{opt burn(#)} specifies the number of initial sequence elements to drop when
creating the Halton sequences. The default is {cmd:burn(15)}.


{title:Option for mixlcov}

{phang}
{opt sd} reports the standard deviations of the correlated coefficients instead
of the covariance matrix.


{title:Examples}

{pstd}
Consider the following example that contains the data for one individual who
makes two choices.  On the first choice occasion, he/she has three alternatives
and on the second, four. {cmd:choice} is the dependent variable, and
{cmd:speed} and {cmd:cost} are the independent variables/alternative attributes:

{cmd}
        choice speed cost group  id 
          0      5    3     1    1         
          1      8    4     1    1         
          0      6    3     1    1       
          0      3    2     2    1         
          0      2    2     2    1         
          1      5    4     2    1         
          0      6    4     2    1         {txt}
	  
{pstd}
A mixed logit model where speed has a normally distributed coefficient and
cost has a fixed coefficient can be specified as follows:

{phang2}{cmd:. mixlogit choice cost, group(group) id(id) rand(speed)}{p_end}

{pstd}
A model where speed has a normally distributed coefficient and cost has a
lognormally distributed coefficient can be specified as follows (given that
the coefficient for cost is expected to be negative we generate a variable
mcost = -1 x cost since the lognormal distribution implies that the
coefficient is positive):

{phang2}{cmd:. gen mcost = -1*cost}{p_end}
{phang2}{cmd:. mixlogit choice, csid(csid) pid(pid) rand(speed mcost) ln(1)}{p_end}

{pstd}
{cmd:mixlogit} automatically generates starting values unless they are
specified using the {opt from()} option. The starting values for the means are
the estimated coefficients from a model where all coefficients are fixed
(i.e., {cmd:clogit}), and the starting values for the standard
deviations/elements in the L matrix are set to 0.1. 


{title:Reference}

{phang}Train, K. E. 2003. {it:Discrete Choice Methods with Simulation}.
Cambridge: Cambridge University Press.


{title:Author}

{phang}This command was written by Arne Risa Hole (ah522@york.ac.uk),
Centre for Health Economics, University of York. Comments and suggestions are welcome. {p_end}


{title:Also see}

{psee}
Manual:  {bf:[R] clogit}

{psee}
Online:  {manhelp clogit R}{p_end}