**[ME] menl** -- Nonlinear mixed-effects regression

__Syntax__

**menl** *depvar* **=** <*menlexpr*> [*if*] [*in*] [**,** *options*]

<*menlexpr*> defines a nonlinear regression function as a substitutable
expression that contains model parameters and random effects
specified in braces **{}**, as in **exp({b}+{U[id]})**; see *Random-effects*
*substitutable expressions* in **[ME] menl** for details.

*options* Description
-------------------------------------------------------------------------
Model
__ml__**e** fit model via maximum likelihood; the
default
**reml** fit model via restricted maximum
likelihood
__def__**ine(***name***:**<*resubexpr*>**)** define a function of model parameters;
this option may be repeated
__cov__**ariance(***covspec***)** variance-covariance structure of the
random effects; this option may be
repeated
__init__**ial(***initial_values***)** initial values for parameters

Residuals
__rescov__**ariance(***rescovspec***)** covariance structure for within-group
errors
__resvar__**iance(***resvarspec***)** heteroskedastic variance structure for
within-group errors
__rescorr__**elation(***rescorrspec***)** correlation structure for within-group
errors

Reporting
__l__**evel(***#***)** set confidence level; default is
**level(95)**
__var__**iance** show random-effects and within-group
error parameter estimates as variances
and covariances; the default
__stddev__**iations** show random-effects and within-group
error parameter estimates as standard
deviations and correlations
__noret__**able** suppress random-effects table
__nofet__**able** suppress fixed-effects table
__estm__**etric** show parameter estimates as stored in
**e(b)**
__noleg__**end** suppress table expression legend
__nohead__**er** suppress output header
__nogr__**oup** suppress table summarizing groups
__nostd__**err** do not estimate standard errors of
random-effects parameters
*display_options* control columns and column formats, row
spacing, line width, display of omitted
variables and base and empty cells, and
factor-variable labeling

EM options
__emiter__**ate(***#***)** number of EM iterations; default is
**emiterate(25)**
__emtol__**erance(***#***)** EM convergence tolerance; default is
**emtolerance(1e-10)**
**emlog** show EM iteration log

Maximization
*menlmaxopts* control the maximization process

__coefl__**egend** display legend instead of statistics
-------------------------------------------------------------------------
**coeflegend** does not appear in the dialog box.
See **[ME] menl postestimation** for features available after estimation.

The syntax of *covspec* is

*rename1* *rename2* [...]**,** *vartype*

*vartype* Description
-------------------------------------------------------------------------
__ind__**ependent** one unique variance parameter per random
effect; all covariances are 0; the
default
__exc__**hangeable** equal variances for random effects and
one common pairwise covariance
__id__**entity** equal variances for random effects; all
covariances are 0
__un__**structured** all variances and covariances to be
distinctly estimated
-------------------------------------------------------------------------

The syntax of *rescovspec* is

*rescov* [**,** *rescovopts*]

*rescov* Description
-------------------------------------------------------------------------
__id__**entity** uncorrelated within-group errors with one
common variance; the default
__ind__**ependent** uncorrelated within-group errors with
distinct variances
__exc__**hangeable** within-group errors with equal variances
and one common covariance
**ar** [*#*] within-group errors with autoregressive
(AR) structure of order *#*, AR(*#*); **ar 1**
is implied by **ar**
**ma** [*#*] within-group errors with moving-average
(MA) structure of order *#*, MA(*#*); **ma 1**
is implied by **ma**
**ctar1** within-group errors with continuous-time
AR(1) structure
__un__**structured** within-group errors with distinct
variances and covariances
-------------------------------------------------------------------------

The syntax of *resvarspec* is

*resvarfunc* [**,** *resvaropts*]

*resvarfunc* Description
-------------------------------------------------------------------------
__id__**entity** equal within-group error variances; the
default
__lin__**ear** *varname* within-group error variance varies
linearly with *varname*
__pow__**er** *varname*|**_yhat** variance function is a power of *varname*
or of predicted mean
__exp__**onential** *varname*|**_yhat** variance function is exponential of
*varname* or of predicted mean
__dis__**tinct** distinct within-group error variances
-------------------------------------------------------------------------

The syntax of *rescorrspec* is

*rescorr* [**,** *rescorropts*]

*rescorr* Description
-------------------------------------------------------------------------
__id__**entity** uncorrelated within-group errors; the
default
__exc__**hangeable** within-group errors with one common
correlation
**ar** [*#*] within-group errors with AR(*#*) structure;
**ar 1** is implied by **ar**
**ma** [*#*] within-group errors with MA(*#*) structure;
**ma 1** is implied by **ma**
**ctar1** within-group errors with continuous-time
AR(1) structure
__un__**structured** within-group errors with distinct
correlations
-------------------------------------------------------------------------

__Menu__

**Statistics > Multilevel mixed-effects models > Nonlinear regression**

__Description__

**menl** fits nonlinear mixed-effects models in which some or all fixed and
random effects enter nonlinearly. These models are also known as
multilevel nonlinear models or hierarchical nonlinear models. The
overall error distribution of the nonlinear mixed-effects model is
assumed to be Gaussian. Different covariance structures are provided to
model random effects and to model heteroskedasticity and correlations
within lowest-level groups.

__Options__

+-------+
----+ Model +------------------------------------------------------------

**mle** and **reml** specify the statistical method for fitting the model.

**mle**, the default, specifies that the model be fit using maximum
likelihood (ML).

**reml** specifies that the model be fit using restricted maximum
likelihood (REML), also known as residual maximum likelihood.

**define(***name***:**<*resubexpr*>**)** defines a function of model parameters,
<*resubexpr*>, and labels it as *name*. This option can be repeated to
define multiple functions. The **define()** option is useful for
expressions that appear multiple times in the main nonlinear
specification *menlexpr*: you define the expression once and then
simply refer to it by using **{***name***:}** in the nonlinear specification.
This option can also be used for notational convenience. See
*Random-effects substitutable expressions* in **[ME] menl** for how to
specify <*resubexpr*>.

**covariance(***rename1* *rename2* [...]**,** *vartype***)** specifies the structure of the
covariance matrix for the random effects. *rename1*, *rename2*, and so
on, are the names of the random effects to be correlated (see *Random*
*effects* in **[ME] menl**), and *vartype* is one of the following:
**independent**, **exchangeable**, **identity**, or **unstructured**. Instead of
*rename*s, you can specify *restub****** to refer to random effects that
share the same *restub* in their names.

**independent** allows for a distinct variance for each random effect and
assumes that all covariances are 0; the default.

**exchangeable** specifies one common variance for all random effects and
one common pairwise covariance.

**identity** is short for "multiple of the identity"; that is, all
variances are equal, and all covariances are 0.

**unstructured** allows for all variances and covariances to be distinct.
If p random effects are specified, the unstructured covariance
matrix will have p(p+1)/2 unique parameters.

**initial(***initial_values***)** specifies the initial values for model
parameters. You can specify a 1 x k matrix, where k is the total
number of parameters in the model, or you can specify a parameter
name, its initial value, another parameter name, its initial value,
and so on. For example, to initialize **{alpha}** to 1.23 and **{delta}** to
4.57, you would type

. **menl** ...**, initial(alpha 1.23 delta 4.57)** ...

To initialize multiple parameters that have the same group name, for
example, **{y:x1}** and **{y:x2}**, with the same initial value, you can
simply type

. **menl** ...**, initial({y:} 1)** ...

For the full specification, see *Specifying initial values* in **[ME]**
**menl**.

+-----------+
----+ Residuals +--------------------------------------------------------

**menl** provides two ways to model the within-group error covariance
structure, sometimes also referred to as residual covariance structure in
the literature. You can model the covariance directly by using the
**rescovariance()** option or indirectly by using the **resvariance()** and
**rescorrelation()** options.

**rescovariance(***rescov* [**,** *rescovopts*]**)** specifies the within-group errors
covariance structure or covariance structure of the residuals within
the lowest-level group of the nonlinear mixed-effects model. For
example, if you are modeling random effects for classes nested within
schools, then **rescovariance()** refers to the residual
variance-covariance structure of the observations within classes, the
lowest-level groups.

*rescov* is one of the following: **identity**, **independent**, **exchangeable**,
**ar** [*#*], **ma** [*#*], **ctar1**, or **unstructured**. Below, we describe each
*rescov* with its specific options *rescovopts*:

**identity** [**,** **by(***byvar***)**], the default, specifies that all
within-group errors be independent and identically
distributed (i.i.d.) with one common error variance
sigma^2_epsilon. When combined with **by(***byvar***)**, independence
is still assumed, but you estimate a distinct variance for
each category of *byvar*.

**independent,** **index(***varname***)** [**group(***grpvar***)**] specifies that
within-group errors are independent with distinct variances
for each value (index) of *varname*. **index(***varname***)** is
required. **group(***grpvar***)** is required if there are no random
effects in the model.

**exchangeable** [**,** **by(***byvar***)** **group(***grpvar***)**] assumes that
within-group errors have equal variances and a common
covariance.

**ar** [*#*]**,** **t(***timevar***)** [**by(***byvar***)** **group(***grpvar***)**] assumes that
within-group errors have an AR(*#*) structure. If *#* is
omitted, **ar 1** is assumed. **t(***timevar***)** is required.

**ma** [*#*]**,** **t(***timevar***)** [**by(***byvar***)** **group(***grpvar***)**] assumes that
within-group errors have an MA(*#*) structure. If *#* is
omitted, **ma 1** is assumed. **t(***timevar***)** is required.

**ctar1,** **t(***timevar***)** [**by(***byvar***)** **group(***grpvar***)**] assumes that
within-group errors have a continuous-time AR(1) structure.
This is a generalization of the AR covariance structure that
allows for unequally spaced and noninteger time values.
**t(***timevar***)** is required.

**unstructured,** **index(***varname***)** [**group(***grpvar***)**] assumes that
within-group errors have distinct variances and covariances.
This is the most general covariance structure in that no
structure is imposed on the covariance parameters.
**group(***grpvar***)** is required if there are no random effects in
the model.

*rescovopts* are **index(***varname***)**, **t(***timevar***)**, **by(***byvar***)**, and
**group(***grpvar***)**.

**index(***varname***)** is used within the **rescovariance()** option with
*rescov* **independent** or **unstructured**. *varname* is a
nonnegative-integer-valued variable that identifies the
observations within the lowest-level groups (for example,
**obsid**). The groups may be unbalanced in that different
groups may have different **index()** values, but you may not
have repeated **index()** values within any particular group.

**t(***timevar***)** is used within the **rescovariance()** option to specify a
time variable for the **ar**, **ma**, and **ctar1** structures.

With *rescov* **ar** and **ma**, *timevar* is an integer-valued time
variable used to order the observations within the
lowest-level groups and to determine the lags between
successive observations. Any nonconsecutive time values will
be treated as gaps. For the **ar** or **ma** structure, *#* + 1
parameters are estimated: *#* AR or *#* MA coefficients and one
overall error variance sigma^2_epsilon.

With *rescov* **ctar1**, *timevar* is a real-valued time variable.
The correlation between two error terms is the parameter rho,
raised to a power equal to the absolute value of the
difference between the **t()** values for those errors. For the
**ctar1** structure, two parameters are estimated: the
correlation parameter rho and one overall error variance
sigma^2_epsilon.

**by(***byvar***)** is for use within the **rescovariance()** option and
specifies that a set of distinct within-group error
covariance parameters be estimated for each category of
*byvar*. In other words, you can use **by()** to model
heteroskedasticity. *byvar* must be nonnegative-integer valued
and constant within the lowest-level groups.

**group(***grpvar***)** is used to identify the lowest-level groups
(panels) when modeling within-group error covariance
structures. *grpvar* is a nonnegative-integer-valued group
membership variable. This option lets you model within-group
error covariance structures at the lowest level of your model
hierarchy without having to include random effects at that
level in your model. This is useful, for instance, when
fitting nonlinear marginal or population-averaged models that
model the dependence between error terms directly, without
introducing random effects; see example 17. In the presence
of random effects at other levels of hierarchy in your model,
*grpvar* is assumed to be nested within those levels.

**resvariance(***resvarfunc* [**,** *resvaropts*]**)** specifies a heteroskedastic
variance structure of the within-group errors. It can be used with
the **rescorrelation()** option to specify flexible within-group error
covariance structures. The heteroskedastic variance structure is
modeled as Var(epsilon_{ij})=sigma^2 g^2(delta,upsilon_{ij}), where
sigma is an unknown scale parameter, g() is a function that models
heteroskedasticity (also known as variance function in the
literature), deltab is a vector of unknown parameters of the variance
function, and upsilon_{ij}'s are the values of a fixed covariate or
of the predicted mean hat{mu}_{ij}.

*resvarfunc*, omitting the arguments, is one of the following:
**identity**, **linear**, **power**, **exponential**, or **distinct**, and *resvaropts*
are options specific to each variance function.

**identity**, the default, specifies a homoskedastic variance
structure for the within-group errors;
g(delta,upsilon_{ij})=1, so that
Var(epsilon_{ij})=sigma^2=sigma^2_epsilon.

**linear** *varname* specifies that the within-group error variance
vary linearly with *varname*; that is, g(delta,upsilon_{ij}) =
sqrt{*varname*}_{ij}, so that
Var(epsilon_{ij})=sigma^2*varname*_{ij}. *varname* must be
positive.

**power** *varname*|**_yhat** [**,** **strata(***stratavar***)** __nocons__**tant**] specifies
that the within-group error variance, or more precisely the
variance function, be expressed in terms of a power of either
*varname* or the predicted mean **_yhat**, plus a constant term;
g(delta,upsilon_{ij}) = |v_{ij}|^{delta_1}+delta_2. If
**noconstant** is specified, the constant term delta_2 is
suppressed. In general, three parameters are estimated: a
scale parameter sigma, the power delta_1, and the constant
term delta_2. When **strata(***stratavar***)** is specified, the power
and constant parameters (but not the scale) are distinctly
estimated for each stratum. A total number of 2L+1
parameters are estimated (L power parameters, L constant
parameters, and scale sigma), where L is the number of strata
defined by variable *stratavar*.

**exponential** *varname*|**_yhat** [**,** **strata(***stratavar***)**] specifies that
the within-group error variance vary exponentially with
*varname* or with the predicted mean **_yhat**;
g(gamma,upsilon_{ij}) = exp(gamma v_{ij}). Two parameters
are estimated: a scale parameter sigma and an exponential
parameter gamma. When **strata(***stratavar***)** is specified, the
exponential parameter gamma (but not scale sigma) is
distinctly estimated for each stratum. A total number of L+1
parameters are estimated (L exponential parameters and scale
sigma), where L is the number of strata defined by variable
*stratavar*.

**distinct,** **index(***varname***)** [**group(***grpvar***)**] specifies that the
within-group errors have distinct variances, sigma^2_l, for
each value (index), l, of *varname*, v_{ij}; g(delta,v_{ij}) =
delta_{v_{ij}} with delta_{v_{ij}}=sigma_{v_{ij}}/sigma_1
(delta_1=1 for identifiability purposes) such that
Var(epsilon_{ij})=sigma^2_{v_{ij}}=sigma^2_1delta^2_{v_{ij}}
for l=1,2,...,L and v_{ij} in {1, 2, ..., L}. **index(***varname***)**
is required. **group(***grpvar***)** is required if there are no
random effects in the model. **resvariance(distinct)** in
combination with **rescorrelation(identity)** is equivalent to
**rescovariance(independent)**.

*resvaropts* are **strata(***stratavar***)**, __nocons__**tant**, **index()**, or
**group(***grpvar***)**.

**strata(***stratavar***)** is used within the **resvariance()** option with
*resvarfunc* **power** and **exponential**. **strata()** specifies that
the parameters of the variance function g() be distinctly
estimated for each stratum. The scale parameter sigma
remains constant across strata. In contrast,
**rescovariance()**'s **by(***byvar***)** suboption specifies that all
covariance parameters, including sigma (whenever applicable),
be estimated distinctly for each category of *byvar*.
*stratavar* must be nonnegative-integer valued and constant
within the lowest-level groups.

**noconstant** is used within the **resvariance()** option with
*resvarfunc* **power**. **noconstant** specifies that the constant
parameter be suppressed in the expression of the variance
function g().

**index(***varname***)** is used within the **resvariance()** option with
*resvarfunc* **distinct**. *varname* is a nonnegative-integer-valued
variable that identifies the observations within the
lowest-level groups (for example, **obsid**). The groups may be
unbalanced in that different groups may have different
**index()** values, but you may not have repeated **index()** values
within any particular group.

**group(***grpvar***)** is used within the **resvariance()** option with
*resvarfunc* **distinct**. It identifies the lowest-level groups
(panels) when no random effects are included in the model
specification such as with nonlinear marginal models. *grpvar*
is a nonnegative-integer-valued group membership variable.

**rescorrelation(***rescorr* [**,** *rescorropts*]**)** specifies a correlation structure
of the within-group errors. It can be used with the **resvariance()**
option to specify flexible within-group error covariance structures.

*rescorr* is one of the following: **identity**, **exchangeable**, **ar** [*#*], **ma**
[*#*], **ctar1**, or **unstructured**.

**identity**, the default, specifies that all within-group error
correlations be zeros.

**exchangeable** [**,** **by(***byvar***)** **group(***grpvar***)**] assumes that
within-group errors have a common correlation.

**ar** [*#*]**,** **t(***timevar***)** [**by(***byvar***)** **group(***grpvar***)**] assumes that
within-group errors have an AR(*#*) correlation structure. If
*#* is omitted, **ar 1** is assumed. The **t(***timevar***)** option is
required.

**ma** [*#*]**,** **t(***timevar***)** [**by(***byvar***)** **group(***grpvar***)**] assumes that
within-group errors have an MA(*#*) correlation structure. If
*#* is omitted, **ma 1** is assumed. The **t(***timevar***)** option is
required.

**ctar1,** **t(***timevar***)** [**by(***byvar***)** **group(***grpvar***)**] assumes that
within-group errors have a continuous-time AR(1) correlation
structure. The **t(***timevar***)** option is required.

**unstructured,** **index(***varname***)** [**group(***grpvar***)**] assumes that
within-group errors have distinct correlations. This is the
most general correlation structure in that no structure is
imposed on the correlation parameters. **group(***grpvar***)** is
required if there are no random effects in the model.

*rescorropts* are **index(***varname***)**, **t(***timevar***)**, **by(***byvar***)**, and
**group(***grpvar***)**.

**index(***varname***)** is used within the **rescorrelation()** option with
*rescorr* **unstructured**. *varname* is a
nonnegative-integer-valued variable that identifies the
observations within the lowest-level groups (for example,
**obsid**). The groups may be unbalanced in that different
groups may have different **index()** values, but you may not
have repeated **index()** values within any particular group.

**t(***timevar***)** is used within the **rescorrelation()** option to specify
a time variable for the **ar**, **ma**, and **ctar1** structures.

With *rescorr* **ar** and **ma**, *timevar* is an integer-valued time
variable used to order the observations within the
lowest-level groups and to determine the lags between
successive observations. Any nonconsecutive time values will
be treated as gaps. For the **ar** or **ma** structure, *#* AR or MA
coefficients are estimated.

With *rescorr* **ctar1**, *timevar* is a real-valued time variable.
For the continuous AR(1) correlation model, the correlation
between two errors is the parameter rho, raised to a power
equal to the absolute value of the difference between the **t()**
values for those errors.

**by(***byvar***)** is used within the **rescorrelation()** option and
specifies that a set of distinct within-group error
correlation parameters be estimated for each category of
*byvar*. *byvar* must be nonnegative-integer valued and constant
within the lowest-level groups.

**group(***grpvar***)** is used to identify the lowest-level groups
(panels) when modeling within-group error correlation
structures. *grpvar* is a nonnegative-integer-valued group
membership variable. This option lets you model within-group
error correlation structures at the lowest level of your
model hierarchy without having to include random effects at
that level in your model. This is useful, for instance, when
fitting nonlinear marginal or population-averaged models that
model the dependence between error terms directly, without
introducing random effects; see example 17. In the presence
of random effects at other levels of hierarchy in your model,
*grpvar* is assumed to be nested within those levels.

+-----------+
----+ Reporting +--------------------------------------------------------

**level(***#***)**; see **[R] estimation options**.

**variance**, the default, displays the random-effects and within-group error
parameter estimates as variances and covariances.

**stddeviations** displays the random-effects and within-group error
parameter estimates as standard deviations and correlations.

**noretable** suppresses the random-effects table from the output.

**nofetable** suppresses the fixed-effects table from the output.

**estmetric** displays all parameter estimates in one table using the metric
in which they are stored in **e(b)**. Random-effects parameter estimates
are stored as log-standard deviations and hyperbolic arctangents of
correlations. Within-group error parameter estimates are stored as
log-standard deviations and, when applicable, as hyperbolic
arctangents of correlations. Note that fixed-effects estimates are
always stored and displayed in the same metric.

**nolegend** suppresses the expression legend that appears before the
fixed-effects estimation table when functions of parameters or named
substitutable expressions are specified in the main equation or in
the **define()** options.

**noheader** suppresses the output header, either at estimation or upon
replay.

**nogroup** suppresses the display of group summary information (number of
groups, average group size, minimum, and maximum) from the output
header.

**nostderr** prevents **menl** from calculating standard errors for the estimated
random-effects parameters, although standard errors are still
provided for the fixed-effects parameters. Specifying this option
will speed up computation times.

*display_options*: **noci**, __nopv__**alues**, __noomit__**ted**, **vsquish**, __noempty__**cells**,
__base__**levels**, __allbase__**levels**, __nofvlab__**el**, **fvwrap(***#***)**, **fvwrapon(***style***)**,
**cformat(***%fmt***)**, **pformat(%***fmt***)**, **sformat(%***fmt***)**, and **nolstretch**; see **[R]**
**estimation options**.

+------------+
----+ EM options +-------------------------------------------------------

These options control the expectation-maximization (EM) iterations that
occur before estimation switches to the Lindstrom-Bates method. EM is
used to obtain starting values.

**emiterate(***#***)** specifies the number of EM iterations to perform. The
default is **emiterate(25)**.

**emtolerance(***#***)** specifies the convergence tolerance for the EM algorithm.
The default is **emtolerance(1e-10)**. EM iterations will be halted once
the log (restricted) likelihood changes by a relative amount less
than *#*. At that point, optimization switches to the Lindstrom-Bates
method.

**emlog** specifies that the EM iteration log be shown. The EM iteration log
is not displayed by default.

+--------------+
----+ Maximization +-----------------------------------------------------

*menlmaxopts*: __iter__**ate(***#***)**, __tol__**erance(***#***)**, __ltol__**erance(***#***)**, __nrtol__**erance(***#***)**,
__nonrtol__**erance**, **pnlsopts()**, **lmeopts()**, [**no**]__lo__**g**. The convergence is
declared when either **tolerance()** or **ltolerance()** is satisfied; see
*Stopping rules* in **[ME] menl** for details.

*menlmaxopts* control the maximization process of the Lindstrom-Bates,
the generalized nonlinear least-squares (GNLS), and the nonlinear
least-squares (NLS) algorithms. The Lindstrom-Bates algorithm is the
main optimization algorithm used for nonlinear models containing
random effects. The GNLS algorithm is used for the models without
random effects but with non-i.i.d. errors. The NLS algorithm is
used for the models without random effects and with i.i.d. errors.
The Lindstrom-Bates and GNLS algorithms are alternating algorithms --
they alternate between two optimization steps and thus support
options to control the overall optimization as well as the
optimization of each step. The Lindstrom-Bates algorithm alternates
between the penalized least-squares (PNLS) and the linear
mixed-effects (LME) optimization steps. The GNLS algorithm
alternates between the GNLS and ML or, if option **reml** is used, REML
steps. Option **pnlsopts()** controls the PNLS and GNLS steps, and
option **lmeopts()** controls the LME and ML/REML steps. The other
*menlmaxopts* control the overall optimization of the alternating
algorithms as well as the NLS optimization.

**iterate(***#***)** specifies the maximum number of iterations for the
alternating algorithms and the NLS algorithm. One alternating
iteration of the Lindstrom-Bates algorithm involves *#*_pnls PNLS
iterations as specified in **pnlsopts()**'s **iterate()** suboption and
*#*_lme LME iterations as specified in **lmeopts()**'s **iterate()**
suboption. Similarly, one alternating iteration of the GNLS
algorithm involves *#*_gnls GNLS iterations and *#*_ml ML/REML
iterations. The default is the current value of **set maxiter**,
which is **iterate(16000)** by default.

**tolerance(***#***)** specifies the tolerance for the parameter vector in the
alternating algorithms and the NLS algorithm. When the relative
change in the parameter vector from one (alternating) iteration
to the next is less than or equal to **tolerance()**, the parameter
convergence is satisfied. The default is **tolerance(1e-6)**.

**ltolerance(***#***)** specifies the tolerance for the linearization log
likelihood of the Lindstrom-Bates algorithm and for the log
likelihood of the GNLS and NLS algorithms. The linearization log
likelihood is the log likelihood from the LME optimization step
in the last iteration. When the relative change in the log
likelihood from one (alternating) iteration to the next is less
than or equal to **ltolerance()**, the log-likelihood convergence is
satisfied. The default is **ltolerance(1e-7)**.

**nrtolerance(***#***)** and **nonrtolerance** control the tolerance for the scaled
gradient.

**nrtolerance(***#***)** specifies the tolerance for the scaled gradient.
Convergence is declared when g(-H^{-1})g' is less than
**nrtolerance(***#***)**, where g is the gradient row vector and H is
the approximated Hessian matrix from the current iteration.
The default is **nrtolerance(1e-5)**.

**nonrtolerance** specifies that the default **nrtolerance()** criterion
be turned off.

**nrtolerance(***#***)** and **nonrtolerance** are allowed only with the NLS
algorithm.

**pnlsopts(***pnlsopts***)** controls the PNLS optimization step of the
Lindstrom-Bates alternating algorithm and the GNLS optimization
step of the GNLS alternating algorithm. *pnlsopts* include any of
the following: __iter__**ate(***#***)**, __ltol__**erance(***#***)**, __tol__**erance(***#***)**,
__nrtol__**erance(***#***)**, and *maximize_options*. The convergence of this
step within each alternating iteration is declared when
**nrtolerance()** and one of **tolerance()** or **ltolerance()** are
satisfied. This option is not allowed with the NLS algorithm.

**iterate(***#***)** specifies the maximum number of iterations for the
PNLS and GNLS optimization steps of the alternating
algorithms. The default is **iterate(5)**.

**ltolerance(***#***)** specifies the tolerance for the objective function
in the PNLS and GNLS optimization steps. When the relative
change in the objective function from one PNLS or GNLS
iteration to the next is less than or equal to **ltolerance()**,
the objective-function convergence is satisfied. The default
is **ltolerance(1e-7)**.

**tolerance(***#***)** specifies the tolerance for the vector of
fixed-effects parameters. When the relative change in the
coefficient vector from one PNLS or GNLS iteration to the
next is less than or equal to **tolerance()**, the parameter
convergence criterion is satisfied. The default is
**tolerance(1e-6)**.

**nrtolerance(***#***)** specifies the tolerance for the scaled gradient in
the PNLS and GNLS optimization steps. Convergence is
declared when g(-H^{-1})g' is less than **nrtolerance(***#***)**, where
g is the gradient row vector and H is the approximated
Hessian matrix from the current iteration. The default is
**nrtolerance(1e-5)**.

*maximize_options* are [**no**]__lo__**g**, __tr__**ace**, __showtol__**erance**,
__nonrtol__**erance**; see **[R] maximize**.

**lmeopts(***lmeopts***)** controls the LME optimization step of the
Lindstrom-Bates alternating algorithm and the ML/REML
optimization step of the GNLS alternating algorithm. *lmeopts*
include any of the following: __iter__**ate(***#***)**, __ltol__**erance(***#***)**,
__tol__**erance(***#***)**, __nrtol__**erance(***#***)**, and *maximize_options*. The
convergence of this step within each alternating iteration is
declared when **nrtolerance()** and one of **tolerance()** or
**ltolerance()** are satisfied. This option is not allowed with the
NLS algorithm.

**iterate(***#***)** specifies the maximum number of iterations for the LME
and ML/REML optimization steps of the alternating algorithms.
The default is **iterate(5)**.

**ltolerance(***#***)** specifies the tolerance for the log likelihood in
the LME and ML/REML optimization steps. When the relative
change in the log likelihood from one LME or ML/REML
iteration to the next is less than or equal to **ltolerance()**,
the log-likelihood convergence is satisfied. The default is
**ltolerance(1e-7)**.

**tolerance(***#***)** specifies the tolerance for the random-effects and
within-group error covariance parameters. When the relative
change in the vector of parameters from one LME or ML/REML
iteration to the next is less than or equal to **tolerance()**,
the convergence criterion for covariance parameters is
satisfied. The default is **tolerance(1e-6)**.

**nrtolerance(***#***)** specifies the tolerance for the scaled gradient in
the LME and ML/REML optimization steps. Convergence is
declared when g(-H^{-1})g' is less than **nrtolerance(***#***)**, where
g is the gradient row vector and H is the approximated
Hessian matrix from the current iteration. The default is
**nrtolerance(1e-5)**.

*maximize_options* are [**no**]__lo__**g**, __tr__**ace**, __grad__**ient**, **showstep**, __hess__**ian**,
__showtol__**erance**, __nonrtol__**erance**; see **[R] maximize**.

[**no**]__lo__**g**; see **[R] maximize**.

The following option is available with **menl** but is not shown in the
dialog box:

**coeflegend**; see **[R] estimation options**.

__Examples__

---------------------------------------------------------------------------
Setup
**. webuse orange**

Fit a two-level model without covariates
**. menl circumf = ({b1}+{U1[tree]})/(1+exp(-(age-{b2})/{b3}))**

Same as above, but use **define()** to simplify model specification and
highlight the 2-stage model formulation
**. menl circumf = {phi1:}/(1+exp(-(age-{b2})/{b3})),**
**define(phi1:{b1}+{U1[tree]})**

Add a random intercept,** {U2[tree]}**, in the exponent and allow correlation
between random intercepts **U1** and** U2**
**. menl circumf = {phi1:}/(1+exp(-(age-{phi2:})/{b3})),**
**define(phi1:{b1}+{U1[tree]})** **define(phi2:{b2}+{U2[tree]})**
**covariance(U1 U2, unstructured)**

Assume independent random intercepts **U1** and **U2**, and specify a
heteroskedastic within-subject error variance that varies as a power of
predicted mean values **_yhat**
**. menl circumf = {phi1:}/(1+exp(-(age-{phi2:})/{b3})),**
**define(phi1:{b1}+{U1[tree]})** **define(phi2:{b2}+{U2[tree]})**
**covariance(U1 U2, independent)** **resvariance(power _yhat,**
**noconstant)**

As above, but perform restricted maximum-likelihood estimation instead of
the default maximum-likelihood estimation
**. menl circumf = {phi1:}/(1+exp(-(age-{phi2:})/{b3})),**
**define(phi1:{b1}+{U1[tree]})** **define(phi2:{b2}+{U2[tree]})**
**covariance(U1 U2, independent) resvariance(power _yhat,**
**noconstant) reml**

Display standard deviations and correlations instead of default variances
and covariances
**. menl, stddeviations**

Fit a nonlinear marginal model with an exchangeable within-group error
covariance structure
**. menl circumf =** **{b1}/(1+exp(-(age-{b2})/{b3})),**
**rescovariance(exchangeable, group(tree))**

---------------------------------------------------------------------------
Setup
**. webuse unicorn**

Fit a two-level model with covariates
**. menl weight = {phi1:}+({phi2}-{phi1:})*exp(-{phi3:}*time),**
**define(phi1:{b10}+{b11}*1.female+{U0[id]})**
**define(phi3:{b30}+{b31}*cupcake)**

As above, but using efficient linear-combination specifications
**. menl weight = {phi1:}+({phi2}-{phi1:})*exp(-{phi3:}*time),**
**define(phi1: i.female U0[id])** **define(phi3: cupcake, xb)**

Include a random slope on continuous variable** cupcake**, and specify and
exchangeable covariance structure between random slope **U1** and random
intercept **U0**
**. menl weight = {phi1:}+({phi2}-{phi1:})*exp(-{phi3:}*time),**
**define(phi1: i.female U0[id])** **define(phi3: cupcake**
**c.cupcake#U1[id])** **covariance(U0 U1, exchangeable)**

---------------------------------------------------------------------------
Setup
**. webuse ovary**

Specify your own initial values for fixed effects
**. menl follicles =**
**{phi1:}+{b1}*sin(2*_pi*stime*{b2})+{b3}*cos(2*_pi*stime*{b2}),**
**define(phi1: U1[mare], xb) initial(phi1:_cons 12.2 b1 -3.0 b2 1**
**b3 -.88, fixed)**

As above, but specify an AR(1) covariance structure for the residuals
instead of the default identity structure
**. menl follicles =**
**{phi1:}+{b1}*sin(2*_pi*stime*{b2})+{b3}*cos(2*_pi*stime*{b2}),**
**define(phi1: U1[mare], xb)** **initial(phi1:_cons 12.2 b1 -3.0 b2 1**
**b3 -.88, fixed)** **rescovariance(ar 1, t(time))**

---------------------------------------------------------------------------
Setup
**. webuse glucose**

Three-level model of **glucose** on **time** with random intercepts **U1** and **UU2** at
the **subject** and **guar** levels, with **guar** nested within **subject**
**. menl glucose = {phi1:} +**
**{phi2:}*c.time#c.time#c.time*exp(-{phi3:}*time),** **define(phi1:**
**i.guar U1[subject])** **define(phi2: i.guar UU2[subject>guar])**
**define(phi3: i.guar, xb)**

As above, but specify a continuous-time AR(1) correlation structure for
the residuals
**. menl glucose = {phi1:} +**
**{phi2:}*c.time#c.time#c.time*exp(-{phi3:}*time),** **define(phi1:**
**i.guar U1[subject])** **define(phi2: i.guar UU2[subject>guar])**
**define(phi3: i.guar) rescorrelation(ctar1, t(time))**

---------------------------------------------------------------------------

__Stored results__

**menl** stores the following in **e()**:

Scalars
**e(N)** number of observations
**e(k)** number of parameters
**e(k_f)** number of fixed-effects parameters
**e(k_r)** number of random-effects parameters
**e(k_rs)** number of variances
**e(k_rc)** number of covariances
**e(k_res)** number of within-group error parameters
**e(k_eq)** number of equations
**e(k_feq)** number of fixed-effects equations
**e(k_req)** number of random-effects equations
**e(k_reseq)** number of within-group error equations
**e(df_m)** model degrees of freedom
**e(ll)** linearization log (restricted) likelihood
**e(chi2)** chi-squared
**e(p)** p-value for model test
**e(rank)** rank of **e(V)**
**e(rc)** return code
**e(converged)** **1** if converged, **0** otherwise

Macros
**e(cmd)** **menl**
**e(cmdline)** command as typed
**e(depvar)** name of dependent variable
**e(ivars)** grouping variables
**e(title)** title in estimation output
**e(varlist)** variables used in the specified equation
**e(eq_***depvar***)** user-specified equation
**e(expressions)** names of defined expressions, *expr_1*, *expr_2*,
..., *expr_k*
**e(expr_***expr_i***)** defined expression *expr_i*, i=1, ..., k
**e(hierarchy)** random-effects hierarchy structure,
**(***path***:***covtype***:***REs***) (**...**)**
**e(revars)** names of random effects
**e(rstructlab)** within-group error covariance output label
**e(timevar)** within-group error covariance **t()** variable, if
specified
**e(indexvar)** within-group error covariance **index()** variable,
if specified
**e(covbyvar)** within-group error covariance **by()** variable, if
specified
**e(stratavar)** within-group error variance **strata()** variable,
if specified
**e(corrbyvar)** within-group error correlation **by()** variable, if
specified
**e(rescovopt)** within-group error covariance option, if
**rescovariance()** specified
**e(resvaropt)** within-group error variance option, if
**resvariance()** specified
**e(rescorropt)** within-group error correlation option, if
**rescorrelation()** specified
**e(groupvar)** lowest-level **group()** variable, if specified
**e(chi2type)** **Wald**; type of model chi-squared test
**e(vce)** **conventional**
**e(method)** **ML** or **REML**
**e(opt)** type of optimization, **lbates**
**e(crittype)** optimization criterion, **linearization** **log**
**likelihood**
**e(properties)** **b V**
**e(estat_cmd)** program used to implement **estat**
**e(predict)** program used to implement **predict**
**e(marginsok)** predictions allowed by **margins**
**e(marginsnotok)** predictions disallowed by **margins**
**e(marginsdefault)** default **predict()** specification for **margins**
**e(asbalanced)** factor variables **fvset** as **asbalanced**
**e(asobserved)** factor variables **fvset** as **asobserved**

Matrices
**e(b)** coefficient vector
**e(Cns)** factor-variable constraint matrix
**e(V)** variance-covariance matrix of the estimators
**e(V_modelbased)** model-based variance
**e(b_sd)** random-effects and within-group error estimates
in the standard deviation metric
**e(V_sd)** VCE for parameters in the standard deviation
metric
**e(b_var)** random-effects and within-group error estimates
in the variance metric
**e(V_var)** VCE for parameters in the variance metric
**e(cov_***#***)** random-effects covariance structure at the
hierarchical level k - *#* + 1 in a k-level
model
**e(hierstats)** group-size statistics for each hierarchy

Functions
**e(sample)** marks estimation sample