{p 4 6 2}
See {help estcom} for additional capabilities of estimation commands.  To
redisplay results, type {cmd:ml display}.{p_end}


{title:Description}

{pstd}
{opt ml model} defines the current problem.

{pstd}
{opt ml clear} clears the current problem definition.  This command is
rarely, if ever, used because, when you type {opt ml model}, any previous
problem is automatically cleared.

{pstd}
{opt ml query} displays a description of the current problem.

{pstd}
{opt ml check} verifies that the log-likelihood evaluator you have written
seems to work.  We strongly recommend the using this command.

{pstd}
{opt ml search} searches for (better) initial values.  We recommend using
this command.

{pstd}
{opt ml plot} provides a graphical way of searching for (better) initial
values.

{pstd}
{opt ml init} provides a way to specify initial values.

{pstd}
{opt ml report} reports the values of ln L, its gradient, and its
negative Hessian at the initial values or current parameter estimates.

{pstd}
{opt ml trace} traces the execution of the user-defined log-likelihood
evaluation program.

{pstd}
{opt ml count} counts the number of times the user-defined log-likelihood
evaluation program is called;  this command is seldom used.
{opt ml count clear} clears the counter.  {opt ml count on} turns on the
counter.  {opt ml count} without arguments reports the current values of the
counters.  {opt ml count off} stops counting calls.

{pstd}
{opt ml maximize} maximizes the likelihood function and reports final
results.  Once {opt ml maximize} has successfully completed, the previously
mentioned {opt ml} commands may no longer be used unless {opt noclear} is
specified. {opt ml graph} and {opt ml display} may be used whether or not
{opt noclear} is specified.

{pstd}
{opt ml graph} graphs the log-likelihood values against the iteration number.

{pstd}
{opt ml display} redisplays final results.

{pstd}
{it:progname} is the name of a program you write to evaluate the
log-likelihood function.  In this documentation, it is referred to as the
user-written evaluator or sometimes simply as the evaluator.  The program you
write is written in the style required by the method you choose.  The methods
are lf, d0, d1, and d2.  Outlines of evaluator programs for each of these
methods are shown in {help mlmethod}.

{pstd}
Several commands are helpful in writing a user-written evaluator for use
with {opt ml}.  See {helpb mleval} for details of the {opt mleval},
{opt mlsum}, {opt mlvecsum}, {opt mlmatsum}, and {opt mlmatbysum} commands.

{marker mlmode}{...}
{title:Options for use with ml model in interactive or noninteractive mode}

{phang}
{opt robust} and {opth cluster(varname)} specify
the robust variance estimator, as does specifying {opt pweight}s or the 
{opt svy} option.

{pmore}
These options will work with a method lf evaluator; all you need to do
is specify them.

{pmore}
These options will not work with a method d0 evaluator,
and specifying these options will result in an error message.

{pmore}
With method d1 or d2 evaluators in which the likelihood function
satisfies the linear-form restrictions, these options will work only if you
fill in the equation scores; otherwise, specifying these options  will result
in an error message.

{phang}
{cmd:constraints(}{it:{help numlist}} | {it:matname}{cmd:)} specifies the linear constraints to be
applied during estimation.  {opt constraints(numlist)} specifies the
constraints by number. Constraints are defined using the {helpb constraint}
command.  {opt constraint(matname)} specifies a matrix that contains the
constraints.

{phang}
{opt nocnsnotes} prevents notes from being displayed when constraints are
dropped.  A constraint will be dropped if it is inconsistent, contradicts
other constraints, or causes some other error when the constraint matrix is
being built.  Constraints are checked in the order they are specified.

{phang}
{opth "title(data types:string)"} specifies the title to be placed on the
estimation output when results are complete.

{phang}
{opt nopreserve} specifies that it is not necessary for {cmd:ml} to
ensure that only the estimation subsample is in memory when the user-written
likelihood evaluator is called.  {opt nopreserve} is irrelevant when you use
method lf.  See {bf:[R] ml} for additional details.

{phang}
{opt collinear} specifies that {opt ml} not remove the collinear variables
within equations.  There is no reason you would want to leave collinear
variables in place, but this option is of interest to programmers who, in
their code, have already removed collinear variables and do not want {cmd:ml}
to waste computer time checking again.

{phang}
{opt missing} specifies that observations containing variables with
missing values not be eliminated from the estimation sample; see
{bf:[R] ml}.

{phang}
{opt lf0(#k #ll)} is typically used by programmers.  It
specifies the number of parameters and log-likelihood value of the
"constant-only" model so that {cmd:ml} can report a likelihood-ratio test
rather than a Wald test.  See {bf:[R] ml} for additional details.

{phang}
{opt continue} is typically specified by programmers.  It does two things:

{pmore}
First, it specifies a model has just been fitted by either {opt ml} or some
other estimation command, such as {helpb logit}, and that the likelihood value
stored in {cmd:e(ll)} and the number of parameters stored in {cmd:e(b)} as of
this instant are the relevant values of the constant-only model.  The current
value of the log likelihood is used to present a likelihood-ratio test unless
{opt robust}, {opt cluster()}, {opt pweight}s, {opt svy}, or
{opt constraints()} is specified.
A likelihood-ratio test is inappropriate when {opt robust},
{opt cluster()}, {opt pweight}s, or {opt svy} is specified.
We suggest using {helpb lrtest} when {opt constraints()} is specified.

{pmore}
Second, {opt continue} sets the initial values for the model about to
be fitted according to the {cmd:e(b)} currently stored.

{pmore}
The comments made about specifying {cmd:missing} with {cmd:lf0()} apply
equally well in this case.

{phang}
{opt waldtest(#)} is typically specified by programmers.  By
default, {opt ml} presents a Wald test, but that is overridden if options
{opt lf0()} or {opt continue} are specified.
A Wald test is performed if {opt robust}, {opt cluster()}, or {opt pweight}s
are specified.

{pmore}
{cmd:waldtest(0)} prevents even the Wald test from being reported.

{pmore}
{cmd:waldtest(-1)} is the default.  It specifies that a Wald test be performed
by constraining all coefficients except for the intercept to 0 in the first
equation.  Remaining equations are to be unconstrained. 
A Wald test is performed if neither {cmd:lf0()} nor {opt continue} was
specified, and a Wald test is forced if {opt robust}, {opt cluster()}, or
{opt pweight}s were specified.

{pmore}
{opt waldtest(k)} for {it:k} {ul:<} -1 specifies that a Wald test be 
performed by constraining all coefficients except for intercepts to 0 in the
first |{it:k}| equations; remaining equations are to be unconstrained.  A Wald test
is performed if neither {cmd:lf0()} nor {opt continue} was specified, and
a Wald test is forced if {opt robust}, {opt cluster()}, or {opt pweight}s were
specified.

{pmore}
{opt waldtest(k)} for {it:k} {ul:>} 1 works like the options above, except
that it forces a Wald test to be reported even if the information to perform
the likelihood-ratio test is available and even if none of {opt robust},
{opt cluster()}, or {opt pweight}s were specified.  {opt waldtest(k)}, {it:k}
{ul:>} 1, may not be specified with {opt lf0()}.

{phang}
{opt obs(#)} is used mostly by programmers.  It specifies that the number of
observations reported and ultimately stored in {cmd:e(N)} be {it:#}.
Ordinarily, {opt ml} works that out for itself.  Programmers may want to specify
this option when, in order for the likelihood-evaluator to work for N
observations, they first had to modify the dataset so that it contained a
different number of observations.

{phang}
{opt noscvars} is used mostly by programmers.  It specifies that method
d0, d1, or d2 is being used but that the
likelihood-evaluation program does not calculate or use arguments {cmd:`g1'},
{cmd:`g2'}, etc., which are the score vectors.  Thus {cmd:ml} can save a
little time by not generating and passing those arguments.

{phang}
{opth "crittype(data types:string)"} is used mostly by programmers.  It allows
programmers to supply a string (up to 32 characters long) that describes the
criterion that is being optimized by {cmd:ml}.  The default is
{cmd:"log likelihood"} for nonrobust and {cmd:"log pseudolikelihood"} for
robust estimation.

{phang}
{opt svy} indicates that {cmd:ml} is to pick up the {opt svy} settings set
by {cmd:svyset} and use the robust variance estimator.  This option
requires the data to be {helpb svyset}.  {opt svy} may
not be supplied with {help weight}s or the {opt cluster()} options.

{phang2}
{opth subpop(varname)} specifies that estimates be computed
for the single subpopulation 
defined by the observations for which {it:varname} != 0.  Typically,
{it:varname} = 1 defines the subpopulation and {it:varname} = 0 indicates
observations not belonging to the subpopulation.  For observations whose
subpopulation status is uncertain, {it:varname} should be set to missing
('.').  This option requires the {opt svy} option.

{phang2}
{opt srssubpop} can be specified only if {opt subpop()} is specified.
{opt srssubpop} requests that deff and deft be computed using an estimate of
simple-random-sampling variance for sampling within a subpopulation.  If
{opt srssubpop} is not specified, deff and deft are computed using an estimate
of simple-random-sampling variance for sampling from the entire population.
Typically, {opt srssubpop} would be given when computing subpopulation
estimates by strata or by groups of strata.

{phang2}
{opt nosvyadjust} specifies that the model Wald test be carried out as W/k
distributed F(k,d), where W is the Wald test statistic, k is the number of
terms in the model excluding the constant term, d = total number of sampled PSUs
minus the total number of strata, and F(k,d) is an F distribution with k
numerator degrees of freedom and d denominator degrees of freedom.  By default, an
adjusted Wald test is conducted:  (d-k+1)W/(kd) distributed F(k,d-k+1).
This option requires the {opt svy} option.

{phang}
{opt technique(algorithm_spec)} specifies how the likelihood function is to be maximized.
The following algorithms are currently implemented in {cmd:ml}.  For details,
see the book 
{it:{browse "http://www.stata.com/bookstore/mle.html":Maximum Likelihood Estimation with Stata, 2nd Edition}}
(Gould, Pitblado, and Sribney 2003).

{pmore}
{cmd:technique(nr)} specifies Stata's modified Newton-Raphson (NR) algorithm.

{pmore}
{cmd:technique(bhhh)} specifies the Berndt-Hall-Hall-Hausman (BHHH) algorithm.

{pmore}
{cmd:technique(dfp)} specifies Davidon-Fletcher-Powell (DFP) algorithm.

{pmore}
{cmd:technique(bfgs)} specifies the Broyden-Fletcher-Goldfarb-Shanno (BFGS)
algorithm.

{pmore}
The default is {cmd:technique(nr)}.

{pmore}
You can switch between algorithms by specifying more than one in the
{opt technique()} option.  By default, {cmd:ml} will use an algorithm for five
iterations before switching to the next algorithm.  To specify a different
number of iterations include the number after the technique in the option.
For example, specifying {cmd:technique(bhhh 10 nr 1000)} requests that
{cmd:ml} perform 10 iterations using the BHHH algorithm followed by 1000
iterations using the NR algorithm, and then switch back to BHHH for 10
iterations, and so on.  The process continues until convergence or until the
maximum number of iterations is reached.

{phang}
{cmd:vce(oim}|{opt opg}|{opt native)} specifies the type of
variance-covariance matrix.  This option may not be combined with the
{opt robust} or {opt svy} options.

{pmore}
{cmd:vce(oim)} specifies that the standard errors and coefficient covariance
matrix be estimated using the observed information matrix (that is, the inverse of
the negative Hessian matrix).  This is the default for all optimization
algorithms except {cmd:technique(bhhh)}.

{pmore}
{cmd:vce(opg)} specifies that the standard errors and coefficient covariance
matrix be estimated using the outer product of the coefficient gradients with
respect to the observation likelihoods.  This is the default for
{cmd:technique(bhhh)}, except when the {opt robust} option is supplied.

{pmore}
{cmd:vce(native)} specifies that the standard errors and coefficient
covariance matrix be estimated using the information matrix defined by the