**[R] ml** -- Maximum likelihood estimation

__Syntax__

ml model in interactive mode

**ml** __mod__**el** *method* *progname* *eq* [*eq* ...] [*if*] [*in*] [*weight*] [**,**
*model_options* **svy** *diparm_options*]

**ml** __mod__**el** *method* *funcname***()** *eq* [*eq* ...] [*if*] [*in*] [*weight*] [**,**
*model_options* **svy** *diparm_options*]

ml model in noninteractive mode

**ml** __mod__**el** *method* *progname* *eq* [*eq* ...] [*if*] [*in*] [*weight*]**,** __max__**imize**
[*model_options* **svy** *diparm_options* *noninteractive_options*]

**ml** __mod__**el** *method* *funcname***()** *eq* [*eq* ...] [*if*] [*in*] [*weight*]**,**
__max__**imize** [*model_options* **svy** *diparm_options*
*noninteractive_options*]

Noninteractive mode is invoked by specifying the **maximize** option. Use
**maximize** when **ml** will be used as a subroutine of another ado-file or
program and you want to carry forth the problem, from definition to
posting of results, in one command.

**ml clear**

**ml** __q__**uery**

**ml check**

**ml** __sea__**rch** [[**/**]*eqname*[**:**] *#lb* *#ub* ] [*...*] [**,** *search_options*]

**ml** __pl__**ot** [*eqname***:**]*name* [*#* [*#* [*#*]]] [**,** __sav__**ing(***filename*[**,** **replace**]**)**]

**ml init** { [*eqname***:**]*name***=***#* | **/***eqname***=***#* } [*...*]

**ml init** *#* [*#* *...*]**,** **copy**

**ml init** *matname* [**,** **copy** **skip** ]

**ml** __rep__**ort**

**ml trace** { **on** | **off** }

**ml count** [ **clear** | **on** | **off** ]

**ml** __max__**imize** [**,** *ml_maximize_options* *display_options* *eform_option*]

**ml** __gr__**aph** [*#*] [**,** __sav__**ing(***filename*[**,** **replace**]**)** ]

**ml** __di__**splay** [**,** *display_options* *eform_option*]

**ml** __foot__**note**

**ml** **score** *newvar* [*if*] [*in*] [**,** *ml_score_options*]

**ml** **score** *newvarlist* [*if*] [*in*] [**,** __miss__**ing**]

**ml** **score** [*type*] *stub** [*if*] [*in*] [**,** __miss__**ing**]

where *method* is one of

**lf** **d0** **lf0** **gf0**
**d1** **lf1**
**d1debug** **lf1debug**
**d2** **lf2**
**d2debug** **lf2debug**

or *method* can be specified using one of the longer, more descriptive
names

*method* Longer name
-----------------------------------------------------------------
**lf** **linearform**
**d0** **derivative0**
**d1** **derivative1**
**d1debug** **derivative1debug**
**d2** **derivative2**
**d2debug** **derivative2debug**
**lf0** **linearform0**
**lf1** **linearform1**
**lf1debug** **linearform1debug**
**lf2** **linearform2**
**lf2debug** **linearform2debug**
**gf0** **generalform0**
-----------------------------------------------------------------

*eq* is the equation to be estimated, enclosed in parentheses, and
optionally with a name to be given to the equation, preceded by a
colon,

**(** [*eqname***:**] [*varlist_y* **=**] [*varlist_x*] [**,** *eq_options*] **)**

or *eq* is the name of a parameter, such as sigma, with a slash in
front

**/***eqname* which is equivalent to **(***eqname***:, freeparm)**

and *diparm_options* is one or more **diparm(***diparm_args***)** options where
*diparm_args* is either **__sep__** or anything accepted by the
"undocumented" **_diparm** command; see **[P] _diparm**.

*eq_options** * Description
-------------------------------------------------------------------------
__nocons__**tant** do not include an intercept in the equation
__off__**set(***varname_o***)** include *varname_o* in model with coefficient
constrained to 1
__exp__**osure(***varname_e***)** include ln(*varname_e*) in model with
coefficient constrained to 1
**freeparm** *eqname* is a free parameter
-------------------------------------------------------------------------

*model_options** * Description
-------------------------------------------------------------------------
**group(***varname***)** use *varname* to identify groups
**vce(***vcetype***)** *vcetype* may be __r__**obust**, __cl__**uster** *clustvar*,
**oim**, or **opg**
__const__**raints(***numlist***)** constraints by number to be applied
__const__**raints(***matname***)** matrix that contains the constraints to be
applied
__nocnsnote__**s** do not display notes when constraints are
dropped
__ti__**tle(***string***)** place a title on the estimation output
__nopre__**serve** do not preserve the estimation subsample in
memory
__col__**linear** keep collinear variables within equations
__miss__**ing** keep observations containing variables with
missing values
**lf0(***#k #ll***)** number of parameters and log-likelihood
value of the constant-only model
__cont__**inue** specifies that a model has been fit and
sets the initial values b_0 for the model
to be fit based on those results
__wald__**test(***#***)** perform a Wald test; see *Options for use*
*with ml model in interactive or*
*noninteractive mode* below
**obs(***#***)** number of observations
**crittype(***string***)** describe the criterion optimized by **ml**
__sub__**pop(***varname***)** compute estimates for the single
subpopulation
__nosvy__**adjust** carry out Wald test as W/k distributed
F(k,d)
__tech__**nique(nr)** Stata's modified Newton-Raphson (NR)
algorithm
__tech__**nique(bhhh)** Berndt-Hall-Hall-Hausman (BHHH) algorithm
__tech__**nique(dfp)** Davidon-Fletcher-Powell (DFP) algorithm
__tech__**nique(bfgs)** Broyden-Fletcher-Goldfarb-Shanno (BFGS)
algorithm
-------------------------------------------------------------------------

*noninteractive_options** * Description
-------------------------------------------------------------------------
__ini__**t(***ml_init_args***)** set the initial values b_0
__sea__**rch(on)** equivalent to **ml search, repeat(0)**; the
default
__sea__**rch(norescale)** equivalent to **ml search, repeat(0)**
**norescale**
__sea__**rch(quietly)** same as **search(on)**, except that output is
suppressed
__sea__**rch(off)** prevents calling **ml search**
__r__**epeat(***#***)** **ml search**'s **repeat()** option; see below
__b__**ounds(***ml_search_bounds***)** specify bounds for **ml search**
__nowarn__**ing** suppress "convergence not achieved" message
of **iterate(0)**
**novce** substitute the zero matrix for the variance
matrix
**negh** indicates that the evaluator returns the
negative Hessian matrix
__sc__**ore(***newvars***)** new variables containing the contribution
to the score
*maximize_options* control the maximization process; seldom
used
-------------------------------------------------------------------------

*search_options** * Description
-------------------------------------------------------------------------
__r__**epeat(***#***)** number of random attempts to find better
initial-value vector; default is
**repeat(10)** in interactive mode and
**repeat(0)** in noninteractive mode
__rest__**art** use random actions to find starting values;
not recommended
__noresc__**ale** do not rescale to improve parameter vector;
not recommended
*maximize_options* control the maximization process; seldom
used
-------------------------------------------------------------------------

*ml_maximize_options** * Description
-------------------------------------------------------------------------
__nowarn__**ing** suppress "convergence not achieved" message
of **iterate(0)**
**novce** substitute the zero matrix for the variance
matrix
**negh** indicates that the evaluator returns the
negative Hessian matrix
__sc__**ore(***newvars* | *stub****)** new variables containing the contribution
to the score
__noout__**put** suppress display of final results
**noclear** do not clear ml problem definition after
model has converged
*maximize_options* control the maximization process; seldom
used
-------------------------------------------------------------------------

*display_options** * Description
-------------------------------------------------------------------------
__noh__**eader** suppress header display above the
coefficient table
__nofoot__**note** suppress footnote display below the
coefficient table
__l__**evel(***#***)** set confidence level; default is **level(95)**
__f__**irst** display coefficient table reporting results
for first equation only
**neq(***#***)** display coefficient table reporting first *#*
equations
__showeq__**ns** display equation names in the coefficient
table
__pl__**us** display coefficient table ending in
dashes-plus-sign-dashes
__nocnsr__**eport** suppress constraints display above the
coefficient table
__noomit__**ted** suppress display of omitted variables
**vsquish** suppress blank space separating
factor-variable terms or
time-series-operated variables from other
variables
__noempty__**cells** suppress empty cells for interactions of
factor variables
__base__**levels** report base levels of factor variables and
interactions
__allbase__**levels** display all base levels of factor variables
and interactions
**cformat(***%fmt***)** format the coefficients, standard errors,
and confidence limits in the coefficient
table
**pformat(***%fmt***)** format the p-values in the coefficient
table
**sformat(***%fmt***)** format the test statistics in the
coefficient table
**nolstretch** do not automatically widen the coefficient
table to accommodate longer variable
names
__coefl__**egend** display legend instead of statistics
-------------------------------------------------------------------------

*eform_option* Description
-------------------------------------------------------------------------
__ef__**orm(***string***)** display exponentiated coefficients; column
title is "string"
__ef__**orm** display exponentiated coefficients; column
title is "**exp(b)**"
**hr** report hazard ratios
**shr** report subhazard ratios
__ir__**r** report incidence-rate ratios
**or** report odds ratios
__rr__**r** report relative-risk ratios
-------------------------------------------------------------------------
**fweight**s, **aweight**s, **iweight**s, and **pweight**s are allowed; see weight. With
all but methods lf, you must write your likelihood-evaluation program
carefully if **pweight**s are to be specified, and **pweight**s may not be
specified with method d0, d1, d1debug, d2, or d2debug. See Gould,
Pitblado, and Poi (2010, chap. 6) for details.
See estcom for more capabilities of estimation commands. To redisplay
results, type **ml display**.

__Description__

**ml model** defines the current problem.

**ml clear** clears the current problem definition. This command is rarely
used because when you type **ml model**, any previous problem is
automatically cleared.

**ml query** displays a description of the current problem.

**ml check** verifies that the log-likelihood evaluator you have written
works. We strongly recommend using this command.

**ml search** searches for (better) initial values. We recommend using this
command.

**ml plot** provides a graphical way of searching for (better) initial
values.

**ml init** provides a way to specify initial values.

**ml report** reports ln L's values, gradient, and Hessian at the initial
values or current parameter estimates, b_0.

**ml trace** traces the execution of the user-defined log-likelihood
evaluation program.

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

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

**ml graph** graphs the log-likelihood values against the iteration number.

**ml display** redisplays results.

**ml footnote** displays a warning message when the model did not converge
within the specified number of iterations.

**ml score** creates new variables containing the equation-level scores. The
variables generated by **ml score** are equivalent to those generated by
specifying the **score()** option of **ml maximize** (and **ml model** ...**,** ...
**maximize**).

*progname* is the name of a Stata program you write to evaluate the
log-likelihood function.

*funcname***()** is the name of a Mata function you write to evaluate the
log-likelihood function.

In this documentation, *progname* and *funcname***()** are referred to as the
user-written evaluator, the likelihood 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, d2, lf0, lf1, lf2,
and, gf0. Thus, if you choose to use method lf, your program is called a
method-lf evaluator. mlmethod shows outlines of evaluator programs for
each of these methods.

Several commands are helpful in writing a user-written evaluator for use
with **ml**. See **mleval** for details of the **mleval**, **mlsum**, **mlvecsum**,
**mlmatsum**, and **mlmatbysum** commands if your evaluator is a Stata program.
See **moptimize()** for details on **moptimize_util_sum()**,
**moptimize_util_vecsum()**, **moptimize_util_matsum()**, and
**moptimize_util_matbysum()** functions if your evaluator is a Mata function.

__Options for use with ml model in interactive or noninteractive mode__

**group(***varname***)** specifies the numeric variable that identifies groups.
This option is typically used to identify panels for panel-data
models.

**vce(***vcetype***)** specifies the type of standard error reported, which
includes types that are robust to some kinds of misspecification
(**robust**), that allow for intragroup correlation (**cluster** *clustvar*),
and that are derived from asymptotic theory (**oim**, **opg**); see **[R]**
*vce_option*.

**vce(robust)**, **vce(cluster** *clustvar***)**, **pweight**, and **svy** will work with
evaluators of methods lf, lf0, lf1, lf2, and gf0 evaluators; all you
need to do is specify them.

These options will not work with evaluators of methods d0, d1, or d2,
and specifying these options will produce an error message.

**constraints(***numlist* | *matname***)** specifies the linear constraints to be
applied during estimation. **constraints(***numlist***)** specifies the
constraints by number. Constraints are defined by using the
**constraint** command; see **[R] constraint**. **constraint(***matname***)**
specifies a matrix that contains the constraints.

**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 in which they are specified.

**title(***string***)** specifies the title for the estimation output when results
are complete.

**nopreserve** specifies that **ml** need not ensure that only the estimation
subsample is in memory when the user-written likelihood evaluator is
called. **nopreserve** is irrelevant when you use method lf. See the
**nopreserve** option in **[R] ml** for more details.

**collinear** specifies that **ml** not remove the collinear variables within
equations. There is no reason 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 **ml** to waste
computer time checking again.

**missing** specifies that observations containing variables with missing
values not be eliminated from the estimation sample. There are two
reasons you might want to specify **missing**:

Programmers may wish to specify **missing** because, in other parts of
their code, they have already eliminated observations with missing
values and do not want **ml** to waste computer time looking again.

You may wish to specify **missing** if your model explicitly deals with
missing values. Stata's **heckman** command is a good example of this.
In such cases, there will be observations where missing values are
allowed and other observations where they are not -- where their
presence should cause the observation to be eliminated. If you
specify **missing**, it is your responsibility to specify an **if** *exp* that
eliminates the irrelevant observations.

**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 **ml** can report a likelihood-ratio test rather than a Wald test.
These values may have been analytically determined, or they may have
been determined by a previous fitting of the constant-only model on
the estimation sample.

Also see the **continue** option directly below.

If you specify **lf0()**, it must be safe for you to specify the **missing**
option, too, else how did you calculate the log likelihood for the
constant-only model on the same sample? You must have identified the
estimation sample, and done so correctly, so there is no reason for
**ml** to waste time rechecking your results. All of which is to say, do
not specify **lf0()** unless you are certain your code identifies the
estimation sample correctly.

**lf0()**, even if specified, is ignored if **vce(robust)**, **vce(cluster**
*clustvar***)**, **pweight**, or **svy** is specified because, in that case, a
likelihood-ratio test would be inappropriate.

**continue** is typically specified by programmers and does two things:

First, it specifies that a model has just been fit by either **ml** or
some other estimation command, such as **logit**, and that the likelihood
value stored in **e(ll)** and the number of parameters stored in **e(b)** as
of that 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 **vce(robust)**, **vce(cluster** *clustvar***)**,
**pweight**, **svy**, or **constraints()** is specified. A likelihood-ratio test
is inappropriate when **vce(robust)**, **vce(cluster** *clustvar***)**, **pweight**, or
**svy** is specified. We suggest using **lrtest** when **constraints()** is
specified; see **[R] lrtest**.

Second, **continue** sets the initial values, b_0, for the model about to
be fit according to the **e(b)** currently stored.

The comments made about specifying **missing** with **lf0()** apply equally
well here.

**waldtest(***#***)** is typically specified by programmers. By default, **ml**
presents a Wald test, but that is overridden if the **lf0()** or **continue**
option is specified. A Wald test is performed if **vce(robust)**,
**vce(cluster** *clustvar***)**, or **pweight** is specified.

**waldtest(0)** prevents even the Wald test from being reported.

**waldtest(-1)** is the default. It specifies that a Wald test be
performed by constraining all coefficients except the intercept to 0
in the first equation. Remaining equations are to be unconstrained.
A Wald test is performed if neither **lf0()** nor **continue** was specified,
and a Wald test is forced if **vce(robust)**, **vce(cluster** *clustvar***)**, or
**pweight** was specified.

**waldtest(***k***)** for *k* __<__ -1 specifies that a Wald test be performed by
constraining all coefficients except intercepts to 0 in the first |*k*|
equations; remaining equations are to be unconstrained. A Wald test
is performed if neither **lf0()** nor **continue** was specified, and a Wald
test is forced if **vce(robust)**, **vce(cluster** *clustvar***)**, or **pweight** was
specified.

**waldtest(***k***)** for *k* __>__ 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
**vce(robust)**, **vce(cluster** *clustvar***)**, or **pweight** was specified.
**waldtest(***k***)**, *k* __>__ 1, may not be specified with **lf0()**.

**obs(***#***)** is used mostly by programmers. It specifies that the number of
observations reported and ultimately stored in **e(N)** be *#*.
Ordinarily, **ml** works that out for itself. Programmers may want to
specify this option when, 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.

**crittype(***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 **ml**. The default is **"log**
**likelihood"** for nonrobust and **"log pseudolikelihood"** for robust
estimation.

**svy** indicates that **ml** is to pick up the **svy** settings set by **svyset** and
use the robust variance estimator. This option requires the data to
be **svyset**. **svy** may not be specified with **vce()** or weights.

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

**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 is the
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). See Korn and
Graubard (1990) for a discussion of the Wald test and the adjustments
thereof. This option requires the **svy** option.

**technique(***algorithm_spec***)** specifies how the likelihood function is to be
maximized. The following algorithms are currently implemented in **ml**.
For details, see Gould, Pitblado, and Poi (2010).

**technique(nr)** specifies Stata's modified Newton-Raphson (NR)
algorithm.

**technique(bhhh)** specifies the Berndt-Hall-Hall-Hausman (BHHH)
algorithm.

**technique(dfp)** specifies Davidon-Fletcher-Powell (DFP) algorithm.

**technique(bfgs)** specifies the Broyden-Fletcher-Goldfarb-Shanno (BFGS)
algorithm.

The default is **technique(nr)**.

You can switch between algorithms by specifying more than one in the
**technique()** option. By default, **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 **technique(bhhh 10**
**nr 1000)** requests that **ml** perform 10 iterations using the BHHH
algorithm, followed by 1,000 iterations using the NR algorithm, and
then switch back to BHHH for 10 iterations, and so on. The process
continues until convergence or until reaching the maximum number of
iterations.

__Options for use with ml model in noninteractive mode__

The following extra options are for use with **ml model** in noninteractive
mode. Noninteractive mode is for programmers who use **ml** as a subroutine
and want to issue one command that will carry forth the estimation from
start to finish.

**maximize** is required. It specifies noninteractive mode.

**init(***ml_init_args***)** sets the initial values, b_0. *ml_init_args* are
whatever you would type after the **ml init** command.

**search(on**|**norescale**|**quietly**|**off)** specifies whether **ml search** is to be
used to improve the initial values. **search(on)** is the default and is
equivalent to separately running **ml search, repeat(0)**.
**search(norescale)** is equivalent to separately running **ml search,**
**repeat(0) norescale**. **search(quietly)** is equivalent to **search(on)**,
except that it suppresses **ml search**'s output. **search(off)** prevents
calling **ml search**.

**repeat(***#***)** is **ml search**'s **repeat()** option. **repeat(0)** is the default.

**bounds(***ml_search_bounds***)** specifies the search bounds. *ml_search_bounds*
is specified as

[*eqn_name*] *lower_bound* *upper_bound* ... [*eqn_name*] *lower_bound*
*upper_bound*

for instance, **bounds(100 100 lnsigma 0 10)**. The **ml model** command
issues **ml search** *ml_search_bounds***, repeat(***#***)**. Specifying search
bounds is optional.

**nowarning**, **novce**, **negh**, and **score()** are **ml maximize**'s equivalent options.

*maximize_options*: __dif__**ficult**, __tech__**nique(***algorithm_spec***)**, __iter__**ate(***#***)**,
[__no__]__lo__**g**, __tr__**ace**, __grad__**ient**, **showstep**, __hess__**ian**, __showtol__**erance**,
__tol__**erance(***#***)**, __ltol__**erance(***#***)**, __nrtol__**erance(***#***)**, __nonrtol__**erance**, and
**from(***init_specs***)**; see **[R] maximize**. These options are seldom used.

__Options for use when specifying equations__

**noconstant** specifies that the equation not include an intercept.

**offset(***varname_o***)** specifies that the equation be xb + *varname_o* -- that
it include *varname_o* with coefficient constrained to be 1.

**exposure(***varname_e***)** is an alternative to **offset(***varname_o***)**; it specifies
that the equation be xb + ln(*varname_e*). The equation is to include
ln(*varname_e*) with coefficient constrained to be 1.

**freeparm** specifies that the associated *eqname* is a free parameter. The
corresponding full column name on **e(b)** will be **/***eqname* instead of
*eqname***:_cons**. This option is not allowed with *varlist_x*.

__Options for use with ml search__

**repeat(***#***)** specifies the number of random attempts that are to be made to
find a better initial-value vector. The default is **repeat(10)**.

**repeat(0)** specifies that no random attempts be made. More precisely,
**repeat(0)** specifies that no random attempts be made if the first
initial-value vector is a feasible starting point. If it is not, **ml**
**search** will make random attempts, even if you specify **repeat(0)**,
because it has no alternative. The **repeat()** option refers to the
number of random attempts to be made to improve the initial values.
When the initial starting value vector is not feasible, **ml search**
will make up to 1,000 random attempts to find starting values. It
stops when it finds one set of values that works and then moves into
its improve-initial-values logic.

**repeat(***k***)**, *k* > 0, specifies the number of random attempts to be made
to improve the initial values.

**restart** specifies that random actions be taken to obtain starting values
and that the resulting starting values not be a deterministic
function of the current values. Generally, you should not specify
this option because, with **restart**, **ml search** intentionally does not
produce as good a set of starting values as it could. **restart** is
included for use by the optimizer when it gets into serious trouble.
The random actions ensure that the optimizer and **ml search**, working
together, do not cause an endless loop.

**restart** implies **norescale**, which is why we recommend that you do not
specify **restart**. In testing, sometimes **rescale** worked so well that,
even after randomization, the rescaler would bring the starting
values right back to where they had been the first time and thus
defeat the intended randomization.

**norescale** specifies that **ml search** not engage in its rescaling actions to
improve the parameter vector. We do not recommend specifying this
option because rescaling tends to work so well.

*maximize_options*: [__no__]__lo__**g** and __tr__**ace**; see **[R] maximize**. These options
are seldom used.

__Option for use with ml plot__

**saving(***filename***[, replace])** specifies that the graph be saved in
*filename***.gph**.

__Options for use with ml init__

**copy** specifies that the list of numbers or the initialization vector be
copied into the initial-value vector by position rather than by name.

**skip** specifies that any parameters found in the specified initialization
vector that are not also found in the model be ignored. The default
action is to issue an error message.

__Options for use with ml maximize__

**nowarning** is allowed only with **iterate(0)**. **nowarning** suppresses the
"convergence not achieved" message. Programmers might specify
**iterate(0) nowarning** when they have a vector b already containing the
final estimates and want **ml** to calculate the variance matrix and
postestimation results. Then specify
**init(b) search(off) iterate(0) nowarning nolog**.

**novce** is allowed only with **iterate(0)**. **novce** substitutes the zero matrix
for the variance matrix, which in effect posts estimation results as
fixed constants.

**negh** indicates that the evaluator returns the negative Hessian matrix.
By default, **ml** assumes d2 and lf2 evaluators return the Hessian
matrix.

**score(***newvars* | *stub****)** creates new variables containing the contributions
to the score for each equation and ancillary parameter in the model;
see **[U] 20.23 Obtaining scores**.

If **score(***newvars***)** is specified, the *newvars* must contain k new
variables. For evaluators of methods lf, lf0, lf1, and lf2, k is the
number of equations. For evaluators of method gf0, k is the number
of parameters. If **score(***stub****)** is specified, variables named *stub***1**,
*stub***2**, *...*, *stub***k** are created.

For evaluators of methods lf, lf0, lf1, and lf2, the first variable
contains d(ln l_j)/d(x_1j b_1), the second variable contains
d(ln l_j)/d(x_2j b_2), and so on.

For evaluators of method gf0, the first variable contains
d(ln l_j)/d(b_1), the second variable contains d(ln l_j)/d(b_2), and
so on.

**nooutput** suppresses display of results. This option is different from
prefixing **ml maximize** with **quietly** in that the iteration log is still
displayed (assuming that **nolog** is not specified).

**noclear** specifies that the ml problem definition not be cleared after the
model has converged. Perhaps you are having convergence problems and
intend to run the model to convergence. If so, use **ml search** to see
if those values can be improved, and then restart the estimation.

*maximize_options*: __dif__**ficult**, __iter__**ate(***#***)**, [__no__]__lo__**g**, __tr__**ace**, __grad__**ient**,
**showstep**, __hess__**ian**, __showtol__**erance**, __tol__**erance(***#***)**, __ltol__**erance(***#***)**,
__nrtol__**erance(***#***)**, and __nonrtol__**erance**; see **[R] maximize**. These options
are seldom used.

*display_options*; see *Options for use with ml display*.

*eform_option*; see *Options for use with ml display*.

__Option for use with ml graph__

**saving(***filename***[, replace])** specifies that the graph be saved in
*filename***.gph**.

__Options for use with ml display__

**noheader** suppresses the header display above the coefficient table that
displays the final log-likelihood value, the number of observations,
and the model significance test.

**nofootnote** suppresses the footnote display below the coefficient table,
which displays a warning if the model fit did not converge within the
specified number of iterations. Use **ml** **footnote** to display the
warning if 1) you add to the coefficient table using the **plus** option
or 2) you have your own footnotes and want the warning to be last.

**level(***#***)** is the standard confidence-level option. It specifies the
confidence level, as a percentage, for confidence intervals of the
coefficients. The default is **level(95)** or as set by **set level**; see
**[R] level**.

**first** displays a coefficient table reporting results for the first
equation only, and the report makes it appear that the first equation
is the only equation. This option is used by programmers who
estimate ancillary parameters in the second and subsequent equations
and who wish to report the values of such parameters themselves.

**neq(***#***)** is an alternative to **first**. **neq(***#***)** displays a coefficient table
reporting results for the first *#* equations. This option is used by
programmers who estimate ancillary parameters in the *#*+1 and
subsequent equations and who wish to report the values of such
parameters themselves.

**showeqns** is a seldom-used option that displays the equation names in the
coefficient table. **ml** **display** uses the numbers stored in **e(k_eq)** and
**e(k_aux)** to determine how to display the coefficient table. **e(k_eq)**
identifies the number of equations, and **e(k_aux)** identifies how many
of these are for ancillary parameters. The **first** option is implied
when **showeqns** is not specified and all but the first equation are for
ancillary parameters.

**plus** displays the coefficient table, but rather than ending the table in
a line of dashes, ends it in dashes-plus-sign-dashes. This is so
that programmers can write additional display code to add more
results to the table and make it appear as if the combined result is
one table. Programmers typically specify **plus** with the **first** or
**neq()** options. This option implies **nofootnote**.

**nocnsreport** suppresses the display of constraints above the coefficient
table. This option is ignored if constraints were not used to fit
the model.

**noomitted** specifies that variables that were omitted because of
collinearity not be displayed. The default is to include in the
table any variables omitted because of collinearity and to label them
as "(omitted)".

**vsquish** specifies that the blank space separating factor-variable terms
or time-series-operated variables from other variables in the model
be suppressed.

**noemptycells** specifies that empty cells for interactions of factor
variables not be displayed. The default is to include in the table
interaction cells that do not occur in the estimation sample and to
label them as "(empty)".

**baselevels** and **allbaselevels** control whether the base levels of factor
variables and interactions are displayed. The default is to exclude
from the table all base categories.

**baselevels** specifies that base levels be reported for factor
variables and for interactions whose bases cannot be inferred
from their component factor variables.

**allbaselevels** specifies that all base levels of factor variables and
interactions be reported.

**cformat(***%fmt***)** specifies how to format coefficients, standard errors, and
confidence limits in the coefficient table.

**pformat(***%fmt***)** specifies how to format p-values in the coefficient table.

**sformat(***%fmt***)** specifies how to format test statistics in the coefficient
table.

**nolstretch** specifies that the width of the coefficient table not be
automatically widened to accommodate longer variable names. The
default, **lstretch**, is to automatically widen the coefficient table up
to the width of the Results window. To change the default, use **set**
**lstretch** **off**. **nolstretch** is not shown in the dialog box.

**coeflegend** specifies that the legend of the coefficients and how to
specify them in an expression be displayed rather than displaying the
statistics for the coefficients.

*eform_option*: **eform(***string***)**, **eform**, **hr**, **shr**, **irr**, **or**, and **rrr** display the
coefficient table in exponentiated form: for each coefficient,
exp(*b*) rather than *b* is displayed, and standard errors and confidence
intervals are transformed. *string* is the table header that will be
displayed above the transformed coefficients and must be 11
characters or shorter in length -- for example, **eform("Odds ratio")**.
The options **eform**, **hr**, **shr**, **irr**, **or**, and **rrr** provide a default *string*
equivalent to **"exp(b)"**, **"Haz. Ratio"**, **"SHR"**, **"IRR"**, **"Odds Ratio"**,
and **"RRR"**, respectively. These options may not be combined.

**ml** **display** looks at **e(k_eform)** to determine how many equations are
affected by an *eform_option*; by default, only the first equation is
affected. Type **ereturn list, all** to view **e(k_eform)**; see **[P]**
**ereturn**.

__Examples__

See **[R] ml** for examples. More examples are available in Gould, Pitblado,
and Poi (2010) -- available from StataCorp.

__Stored results__

For results stored by **ml** without the **svy** option, see **[R] maximize**.

For results stored by **ml** with the **svy** option, see **[SVY] svy**.

__References__

Gould, W. W., J. Pitblado, and B. P. Poi. 2010. *Maximum Likelihood*
*Estimation with Stata*. 4th ed. College Station, TX: Stata Press.

Korn, E. L., and B. I. Graubard. 1990. Simultaneous testing of
regression coefficients with complex survey data: Use of Bonferroni t
statistics. *American Statistician* 44: 270-276.