{smcl}
{* 03Feb2009/touched NJC 9nov2007}{...}
{cmd:help mixlogit}{right:(SJ7-4: st0133_1; 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} {weight} {cmd:,}
{cmdab:gr:oup(}{varname}{cmd:)}
{cmdab:rand:(}{varlist}{cmd:)}
[{opt id(varname)}
 {opt ln(#)}
 {opt corr}
 {opt nrep(#)}
 {opt burn(#)}
 {opt num:erical}
 {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}]


{p 8 15 2}
{cmd:mixlbeta}
{varlist} {ifin}
{cmd:,} {opt sav:ing(filename)} [{opt replace} {opt nrep(#)} {opt burn(#)}]


{phang}
{opt fweight}s, {opt iweight}s, and {opt pweight}s are allowed
(see {help weight}), but
they are interpreted to apply to decision-makers, not to individual
observations.{p_end}


{title:Description}

{pstd}
{cmd:mixlogit} fits mixed logit models by using maximum simulated likelihood
(Train 2003). See Hole (2007) for a description of the module with examples.

{pstd}
The following postestimation commands are available after {cmd:mixlogit}:

{pstd}
{cmd:mixlpred} calculates 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} calculates 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}).

{pstd}
{cmd:mixlbeta} calculates individual-level parameters corresponding to the variables in
the specified {it:varlist} using the method proposed by Revelt and Train (2000)
(see also Train, 2003, ch. 11). The individual-level parameters are stored in a data file
specified by the user. As with  {cmd:mixlpred} the predictions are available both in and
out of sample; type {cmd:mixlbeta} ... {cmd:if e(sample)} ... if predictions are wanted
for the estimation sample only.


{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 numerical} specifies that numerical gradients should be used instead of analytical gradients (the default).
This option is useful for replicating the results from earlier versions of {cmd:mixlogit} but should
otherwise not be used.

{phang}
{opt coll} overrides checks for multicollinearity. This option should be used with caution but can be useful 
when estimating error components models with the means of random coefficients constrained to zero.

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

{phang}
{opth constraints(numlist)}; see {help estimation options}.

{phang}
{opt robust}, {opth cluster(varname)}; see {help estimation options}.  The cluster variable
must be numeric.

{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 {help maximize}.
{cmd: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)}.
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.


{title:Option for mixlcov}

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


{title:Options for mixlbeta}

{phang}
{opt sav:ing(filename)} save individual-level parameters to {it:filename}.

{phang}
{opt replace} overwrite {it:filename}.

{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.


{title:Examples}

{pstd}
Consider the following example that contains the data for one individual who
makes two choices.  On the first choice occasion, the individual has three alternatives
and on the second, four.  {cmd:choice} is the dependent variable, and
{cmd:speed} and {cmd:cost} are the independent variables or 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 {cmd:speed} has a normally distributed coefficient and
{cmd: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 {cmd:speed} has a normally distributed coefficient and {cmd:cost} has a
lognormally distributed coefficient can be specified as follows (given that
the coefficient for {cmd:cost} is expected to be negative we generate a variable
{cmd:mcost = -cost} since the lognormal distribution implies that the
coefficient is positive):

{phang2}{cmd:. gen mcost = -cost}{p_end}
{phang2}{cmd:. mixlogit choice, group(group) id(id) 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:References}

{phang}Hole AR. 2007. Fitting mixed logit models by using maximum simulated likelihood.
{it:The Stata Journal} 7: 388-401.

{phang}Revelt D, Train K. 2000. Customer-specific taste parameters and mixed logit:
Households' choice of electricity supplier. Working Paper, Department of Economics,
University of California, Berkeley.

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


{title:Author}

{phang}This command was written by Arne Risa Hole (a.r.hole@sheffield.ac.uk),
Department of Economics, University of Sheffield. Comments and suggestions are welcome. {p_end}


{title:Also see}

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

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