**[ME] menl postestimation** -- Postestimation tools for menl

__Postestimation commands__

The following postestimation commands are of special interest after **menl**:

Command Description
-------------------------------------------------------------------------
**estat group** summarize the composition of the nested groups
**estat recovariance** display the estimated random-effects covariance
matrices
**estat sd** display variance components as standard deviations
and correlations
**estat wcorrelation** display model-implied within-cluster correlations and
standard deviations
-------------------------------------------------------------------------

The following standard postestimation commands are also available:

Command Description
-------------------------------------------------------------------------
**contrast** contrasts and ANOVA-style joint tests of estimates
**estat ic** Akaike's and Schwarz's Bayesian information criteria
(AIC and BIC)
**estat summarize** summary statistics for the estimation sample
**estat vce** variance-covariance matrix of the estimators (VCE)
**estimates** cataloging estimation results
**lincom** point estimates, standard errors, testing, and
inference for linear combinations of coefficients
**lrtest** likelihood-ratio test
**margins** marginal means, predictive margins, marginal effects,
and average marginal effects
**marginsplot** graph the results from margins (profile plots,
interaction plots, etc.)
**nlcom** point estimates, standard errors, testing, and
inference for nonlinear combinations of
coefficients
**predict** predictions, residuals, influence statistics, and
other diagnostic measures
**predictnl** point estimates, standard errors, testing, and
inference for generalized predictions
**pwcompare** pairwise comparisons of estimates
**test** Wald tests of simple and composite linear hypotheses
**testnl** Wald tests of nonlinear hypotheses
-------------------------------------------------------------------------

__Syntax for predict__

Syntax for obtaining predictions of random effects and their standard
errors

**predict** [*type*] *newvarsspec* [*if*] [*in*]**,** __ref__**fects** [**reses(***newvarsspec***)**
__relev__**el(***levelvar***)** *options*]

Syntax for predicting named substitutable expressions (parameters)

Predict specific parameters

**predict** [*type*] **(***newvar* **=** **{***param***:})** [**(***newvar* **=** **{***param***:})**] [...] [*if*] [
*in*] [**,** __fixed__**only** __relev__**el(***levelvar***)** *options*]

**predict** [*type*] *newvarsspec* [*if*] [*in*]**,** __param__**eters(***paramnames***)**
[__fixed__**only** __relev__**el(***levelvar***)** *options*]

Predict all parameters

**predict** [*type*] *newvarsspec* [*if*] [*in*]**,** __param__**eters** [__fixed__**only**
__relev__**el(***levelvar***)** *options*]

Syntax for obtaining other predictions

**predict** [*type*] *newvar* [*if*] [*in*] [**,** *statistic* __fixed__**only**
__relev__**el(***levelvar***)** *options*]

*newvarsspec* is *stub****** or *newvarlist*.

*paramnames* is *param* [*param* [...]] and *param* is a name of a substitutable
expression as specified in one of **menl**'s **define()** options.

*statistic* Description
-------------------------------------------------------------------------
Main
**yhat** prediction for the expected response
conditional on the random effects
**mu** synonym for **yhat**
__res__**iduals** residuals, response minus predicted values
* __rsta__**ndard** standardized residuals
-------------------------------------------------------------------------
Unstarred statistics are available both in and out of sample; type
**predict** *...* **if e(sample)** *...* if wanted only for the estimation sample.
Starred statistics are calculated only for the estimation sample, even
when **if e(sample)** is not specified.

*options* Description
-------------------------------------------------------------------------
Main
__iter__**ate(***#***)** maximum number of iterations when computing
random effects; default is **iterate(10)**
__tol__**erance(***#***)** convergence tolerance when computing random
effects; default is **tolerance(1e-6)**
-------------------------------------------------------------------------

__Menu for predict__

**Statistics > Postestimation**

__Description for predict__

**predict** creates a new variable containing predictions of mean values,
residuals, or standardized residuals. It can also create multiple new
variables containing estimates of random effects and their standard
errors or containing predicted named substitutable expressions.

__Options for predict__

+------+
----+ Main +-------------------------------------------------------------

**yhat** calculates the predicted values, which are the mean-response values
conditional on the random effects, mu(x', b, u). By default, the
predicted values account for random effects from all levels in the
model; however, if the **relevel(***levelvar***)** option is specified, then
the predicted values are fit beginning with the topmost level down to
and including level *levelvar*. For example, if **class**es are nested
within **school**s, then typing

**. predict yhat_school, yhat relevel(school)**

would produce school-level predictions. That is, the predictions
would incorporate school-specific random effects but not those for
each class nested within each school. If the **fixedonly** option is
specified, predicted values conditional on zero random effects,
mu(x', b, 0), are calculated based on the estimated fixed effects
(coefficients) in the model when the random effects are fixed at
their theoretical mean value of **0**.

**mu** is a synonym for **yhat**.

**parameters** and **parameters(***paramnames***)** calculate predictions for all or a
subset of the named substitutable expressions in the model. By
default, the predictions account for random effects from all levels
in the model; however, if the **relevel(***levelvar***)** option is specified,
then the predictions would incorporate random effects from the
topmost level down to and including level *levelvar*. Option
**parameters(***param***)** is useful with **margins**. **parameters()** does not
appear in the dialog box.

**reffects** calculates predictions of the random effects. For the
Lindstrom-Bates estimation method of **menl**, these are essentially the
best linear unbiased predictions of the random effects in the LME
approximated log likelihood; see *Inference based on linearization* in
**[ME] menl**. By default, estimates of all random effects in the model
are calculated. However, if the **relevel(***levelvar***)** option is
specified, then estimates of random effects for only level *levelvar*
in the model are calculated. For example, if **class**es are nested
within **school**s, then typing

**. predict b*, reffects relevel(school)**

would produce estimates at the school level. You must specify *q* new
variables, where *q* is the number of random-effects terms in the model
(or level). However, it is much easier to just specify *stub****** and let
Stata name the variables *stub***1**, *stub***2**, ..., *stubq* for you.

**reses(***newvarsspec***)** calculates the standard errors of the estimates of the
random effects. By default, standard errors for all random effects
in the model are calculated. However, if the **relevel(***levelvar***)** option
is specified, then standard errors of the estimates of the random
effects for only level *levelvar* in the model are calculated; see the
**reffects** option.

You must specify *q* new variables, where *q* is the number of
random-effects terms in the model (or level). However, it is much
easier to just specify *stub****** and let Stata name the variables *stub***1**,
*stub***2**, ..., *stubq* for you. The new variables will have the same
storage type as the corresponding random-effects variables.

The **reffects** and **reses()** options often generate multiple new
variables at once. When this occurs, the random effects (or standard
errors) contained in the generated variables correspond to the order
in which the variance components are listed in the output of **menl**.
Still, examining the variable labels of the generated variables (with
the **describe** command, for instance) can be useful in deciphering
which variables correspond to which terms in the model.

**residuals** calculates residuals, equal to the responses minus the
predicted values **yhat**. By default, the predicted values account for
random effects from all levels in the model; however, if the
**relevel(***levelvar***)** option is specified, then the predicted values are
fit beginning at the topmost level down to and including level
*levelvar*.

**rstandard** calculates standardized residuals, equal to the residuals
multiplied by the inverse square root of the estimated error
covariance matrix.

**fixedonly** specifies that all random effects be set to zero, equivalent to
using only the fixed portion of the model.

**relevel(***levelvar***)** specifies the level in the model at which predictions
involving random effects are to be obtained; see the options above
for the specifics. *levelvar* is the name of the model level; it is
the name of the variable describing the grouping at that level.

**iterate(***#***)** specifies the maximum number of iterations when computing
estimates of the random effects. The default is **iterate(10)**. This
option is relevant only to predictions that depend on random effects.
This option is not allowed if the **fixedonly** option is specified.

**tolerance(***#***)** specifies a convergence tolerance when computing estimates
of the random effects. The default is **tolerance(1e-6)**. This option is
relevant only to predictions that depend on random effects. This
option is not allowed if the **fixedonly** option is specified.

__Syntax for margins__

**margins** [*marginlist*] [**,** *options*]

**margins** [*marginlist*] **,** __pr__**edict(***statistic *...**)** [*options*]

*statistic* Description
-------------------------------------------------------------------------
**yhat** predicted values conditional on zero random effects;
implies **fixedonly**; the default
__param__**eters(***param***)** predicted named substitutable expression *param*
conditional on zero random effects; implies
**fixedonly**
__ref__**fects** not allowed with **margins**
__res__**iduals** not allowed with **margins**
__rsta__**ndard** not allowed with **margins**
-------------------------------------------------------------------------
The **fixedonly** option is assumed for the predictions used with **margins**.

Statistics not allowed with **margins** are functions of stochastic
quantities other than **e(b)**.

For the full syntax, see **[R] margins**.

__Menu for margins__

**Statistics > Postestimation**

__Description for margins__

**margins** estimates margins of response for predicted mean values or named
substitutable expressions.

__Examples__

---------------------------------------------------------------------------
Setup
**. webuse soybean**
**. menl weight = {phi1:}/(1+exp(-(time-{phi2:})/{phi3:})),**
**define(phi1: i.year U1[plot]) define(phi2: i.year i.variety)**
**define(phi3: i.year) resvariance(power _yhat, noconstant)**

Test the null hypothesis of homoskedastic within-plot errors
**. test _b[/Residual:delta] = 0**

Display estimated marginal standard deviations and correlations for plot
2 and list the corresponding observations in the data
**. estat wcorrelation, at(plot=2) list**

Calculate predicted values conditional on zero random effects
**. predict weight_f, yhat fixedonly**

Predict parameter **phi1** defined in the model specification
**. predict (phi1 = {phi1:})**

---------------------------------------------------------------------------
Setup
**. webuse wafer, clear**
**. menl current = {phi1:}+{phi2}*cos({phi3}*voltage + _pi/4),**
**define(phi1: voltage W0[wafer] S0[wafer>site]**
**c.voltage#(W1[wafer] S1[wafer>site]))**

Summarize composition of nested groups
**. estat group**

Predict random effects at the wafer level
**. predict u_wafer*, reffects relevel(wafer)**

Display estimated random-effects covariance matrix for the
**site**-within-**wafer** level
**. estat recovariance, relevel(site)**

Calculate predicted values at the wafer level
**. predict curr_wafer, yhat relevel(wafer)**

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