## Stata 15 help for meqrlogit

```
[ME] meqrlogit -- Multilevel mixed-effects logistic regression (QR
decomposition)

Syntax

meqrlogit depvar fe_equation || re_equation [|| re_equation ...] [,
options]

where the syntax of fe_equation is

[indepvars] [if] [in] [, fe_options]

and the syntax of re_equation is one of the following:

for random coefficients and intercepts

levelvar: [varlist] [, re_options]

for random effects among the values of a factor variable

levelvar: R.varname [, re_options]

levelvar is a variable identifying the group structure for the random
effects at that level or is _all representing one group comprising all
observations.

fe_options                      Description
-------------------------------------------------------------------------
Model
noconstant                    suppress constant term from the
fixed-effects equation
offset(varname)               include varname in model with coefficient
constrained to 1
-------------------------------------------------------------------------

re_options                      Description
-------------------------------------------------------------------------
Model
covariance(vartype)           variance-covariance structure of the
random effects
noconstant                    suppress constant term from the
random-effects equation
collinear                     keep collinear variables
-------------------------------------------------------------------------

options                         Description
-------------------------------------------------------------------------
Model
binomial(varname|#)           set binomial trials if data are in
binomial form

Reporting
level(#)                      set confidence level; default is
level(95)
or                            report fixed-effects coefficients as odds
ratios
variance                      show random-effects parameter estimates
as variances and covariances; the
default
stddeviations                 show random-effects parameter estimates
as standard deviations and correlations
noretable                     suppress random-effects table
nofetable                     suppress fixed-effects table
estmetric                     show parameter estimates as stored in
e(b)
nogroup                       suppress table summarizing groups
display_options               control columns and column formats, row
spacing, line width, display of omitted
variables and base and empty cells, and
factor-variable labeling

Integration
intpoints(# [# ...])          set the number of integration
intpoints(7)
laplace                       use Laplacian approximation; equivalent
to intpoints(1)

Maximization
maximize_options              control the maximization process; seldom
used
retolerance(#)                tolerance for random-effects estimates;
default is retolerance(1e-8); seldom
used
reiterate(#)                  maximum number of iterations for
random-effects estimation; default is
reiterate(50); seldom used
matsqrt                       parameterize variance components using
matrix square roots; the default
matlog                        parameterize variance components using
matrix logarithms
refineopts(maximize_options)  control the maximization process during
refinement of starting values

coeflegend                    display legend instead of statistics
-------------------------------------------------------------------------

vartype                  Description
-------------------------------------------------------------------------
independent              one variance parameter per random effect, all
covariances 0; the default unless the R.
notation is used
exchangeable             equal variances for random effects, and one
common pairwise covariance
identity                 equal variances for random effects, all
covariances 0; the default if the R. notation
is used
unstructured             all variances and covariances to be distinctly
estimated
-------------------------------------------------------------------------

indepvars may contain factor variables; see fvvarlist.
indepvars and varlist may contain time-series operators; see tsvarlist.
bootstrap, by, jackknife, mi estimate, rolling, and statsby are allowed;
see prefix.
coeflegend does not appear in the dialog box.
See [ME] meqrlogit postestimation for features available after
estimation.

Statistics > Multilevel mixed-effects models > Estimation by QR
decomposition > Logistic regression

Description

meqrlogit is a legacy command for fitting mixed-effects models to binary
or binomial responses.  melogit is the modern command, and it offers more
functionality; see [ME] melogit. The two commands use different but
equivalent estimation methods. melogit performs optimization using
variance components in their original metric, whereas meqrlogit uses the
QR decomposition of the variance-components matrix.

Options

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

noconstant suppresses the constant (intercept) term and may be specified
for the fixed-effects equation and for any of or all the
random-effects equations.

offset(varname) specifies that varname be included in the fixed-effects
portion of the model with the coefficient constrained to be 1.

covariance(vartype) specifies the structure of the covariance matrix for
the random effects and may be specified for each random-effects
equation.  vartype is one of the following:  independent,
exchangeable, identity, or unstructured.

covariance(independent) covariance structure allows for a distinct
variance for each random effect within a random-effects equation and
assumes that all covariances are 0.  The default is
covariance(independent), except when the R.  notation is used, in
which case the default is covariance(identity) and only
covariance(identity) and covariance(exchangeable) are allowed.

covariance(exchangeable) structure specifies one common variance for
all random effects and one common pairwise covariance.

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

covariance(unstructured) allows for all variances and covariances to
be distinct.  If an equation consists of p random-effects terms, the
unstructured covariance matrix will have p(p+1)/2 unique parameters.

collinear specifies that meqrlogit not omit collinear variables from the
random-effects equation.  Usually, there is no reason to leave
collinear variables in place; in fact, doing so usually causes the
estimation to fail because of the matrix singularity caused by the
collinearity.  However, with certain models (for example, a
random-effects model with a full set of contrasts), the variables may
be collinear, yet the model is fully identified because of
restrictions on the random-effects covariance structure.  In such
cases, using the collinear option allows the estimation to take place
with the random-effects equation intact.

binomial(varname|#) specifies that the data are in binomial form; that
is, depvar records the number of successes from a series of binomial
trials.  This number of trials is given either as varname, which
allows this number to vary over the observations, or as the constant
#.  If binomial() is not specified (the default), depvar is treated
as Bernoulli, with any nonzero, nonmissing values indicating positive
responses.

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

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

or reports estimated fixed-effects coefficients transformed to odds
ratios, that is, exp(b) rather than b.  Standard errors and
confidence intervals are similarly transformed.  This option affects
how results are displayed, not how they are estimated.  or may be
specified either at estimation or upon replay.

variance, the default, displays the random-effects parameter estimates as
variances and covariances.

stddeviations displays the random-effects parameter estimates as standard
deviations and correlations.

noretable suppresses the random-effects table.

nofetable suppresses the fixed-effects table.

estmetric displays all parameter estimates in one table using the metric
in which they are stored in e(b).  The results are stored in the same
metric regardless of the parameterization of the variance components,
matsqrt or matlog, used at estimation time.  Random-effects parameter
estimates are stored as log-standard deviations and hyperbolic
arctangents of correlations, with equation names that organize them
by model level.  Note that fixed-effects estimates are always stored
and displayed in the same metric.

replay.

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

display_options:  noci, nopvalues, noomitted, vsquish, noemptycells,
baselevels, allbaselevels, nofvlabel, fvwrap(#), fvwrapon(style),
cformat(%fmt), pformat(%fmt), sformat(%fmt), and nolstretch; see [R]
estimation options.

+-------------+
----+ Integration +------------------------------------------------------

intpoints(# [# ...]) sets the number of integration points for adaptive
Gaussian quadrature.  The more integration points, the more accurate
the approximation to the log likelihood.  However, computation time
increases with the number of quadrature points, and in models with
many levels or many random coefficients, this increase can be
substantial.

You may specify one number of integration points applying to all
levels of random effects in the model, or you may specify distinct
numbers of points for each level.  intpoints(7) is the default; that
is, by default seven quadrature points are used for each level.

laplace specifies that log likelihoods be calculated using the Laplacian
integration point for each level in the model; laplace is equivalent
to intpoints(1).  Computation time increases as a function of the
number of quadrature points raised to a power equaling the dimension
of the random-effects specification.  The computational time saved by
using laplace can thus be substantial, especially when you have many
levels or random coefficients.

The Laplacian approximation has been known to produce biased
parameter estimates, but the bias tends to be more prominent in the
estimates of the variance components rather than in the estimates of
the fixed effects.  If your interest lies primarily with the
fixed-effects estimates, the Laplace approximation may be a viable
points.

When the R.varname notation is used, the dimension of the random
effects increases by the number of distinct values of varname.  Even
when this number is small to moderate, it increases the total
random-effects dimension to the point where estimation with more than
one quadrature point is prohibitively intensive.

For this reason, when you when you use the R. notation in your
random-effects equations, the laplace option is assumed.  You can
override this behavior by using the intpoints() option, but doing so
is not recommended.

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

maximize_options:  difficult, technique(algorithm_spec), iterate(#),
[no]log, trace, gradient, showstep, hessian, showtolerance,
tolerance(#), ltolerance(#), nrtolerance(#), nonrtolerance, and
from(init_specs); see [R] maximize.  Those that require special
mention for meqrlogit are listed below.

For the technique() option, the default is technique(nr).  The bhhh
algorithm may not be specified.

from(init_specs) is particularly useful when combined with
refineopts(iterate(0)) (see the description below), which bypasses
the initial optimization stage.

retolerance(#) specifies the convergence tolerance for the estimated
estimated as model parameters, random-effects estimators are used to
iterative procedure, with convergence declared when the maximum
relative change in the random effects is less than retolerance().
The default is retolerance(1e-8).  You should seldom have to use this
option.

reiterate(#) specifies the maximum number of iterations used when
estimating the random effects to be used in adapting the Gaussian
quadrature points; see the retolerance() option.  The default is
reiterate(50).  You should seldom have to use this option.

matsqrt (the default), during optimization, parameterizes variance
components by using the matrix square roots of the
variance-covariance matrices formed by these components at each model
level.

matlog, during optimization, parameterizes variance components by using
the matrix logarithms of the variance-covariance matrices formed by
these components at each model level.

The matsqrt parameterization ensures that variance-covariance
matrices are positive semidefinite, while matlog ensures matrices
that are positive definite.  For most problems, the matrix square
root is more stable near the boundary of the parameter space.
However, if convergence is problematic, one option may be to try the
alternate matlog parameterization.  When convergence is not an issue,
both parameterizations yield equivalent results.

refineopts(maximize_options) controls the maximization process during the
refinement of starting values.  Estimation in meqrlogit takes place
in two stages.  In the first stage, starting values are refined by
holding the quadrature points fixed between iterations.  During the
the log likelihood.  Maximization options specified within
refineopts() control the first stage of optimization; that is, they
control the refining of starting values.

maximize_options specified outside refineopts() control the second
stage.

The one exception to the above rule is the nolog option, which when
specified outside refineopts() applies globally.

from(init_specs) is not allowed within refineopts() and instead must
be specified globally.

Refining starting values helps make the iterations of the second
stage (those that lead toward the solution) more numerically stable.
In this regard, of particular interest is refineopts(iterate(#)),
with two iterations being the default.  Should the maximization fail
because of instability in the Hessian calculations, one possible
solution may be to increase the number of iterations here.

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

coeflegend; see [R] estimation options.

Remarks on specifying random-effects equations

Mixed models consist of fixed effects and random effects.  The fixed
effects are specified as regression parameters in a manner similar to
that of most other Stata estimation commands, that is, as a dependent
variable followed by a set of regressors.  The random-effects portion of
the model is specified by first considering the grouping structure of the
data.  For example, if random effects are to vary according to variable
school, then the call to meqrlogit would be of the form

. meqrlogit fixed_portion || school: ... , options

The variable lists that make up each equation describe how the random
effects enter into the model, either as random intercepts (constant term)
or as random coefficients on regressors in the data.  One may also
specify the variance-covariance structure of the within-equation random
effects, according to the four available structures described above.  For
example,

. meqrlogit f_p || school: z1, covariance(unstructured) options

will fit a model with a random intercept and random slope for variable z1
and treat the variance-covariance structure of these two random effects
as unstructured.

If the data are organized by a series of nested groups, for example,
classes within schools, then the random-effects structure is specified by
a series of equations, each separated by ||.  The order of nesting
proceeds from left to right.  For our example, this would mean that an
equation for schools would be specified first, followed by an equation
for classes.  As an example, consider

. meqrlogit f_p || school: z1, cov(un) || class: z2 z3, nocons
cov(ex) options

where variables school and class identify the schools and classes within
schools, respectively.  This model contains a random intercept and random
coefficient on z1 at the school level and has random coefficients on
variables z2 and z3 at the class level.  The covariance structure for the
random effects at the class level is exchangeable, meaning that the
random effects share a common variance, and they are allowed to be
correlated.  A simplification allowing for no correlation (while still
allowing a common variance) would be cov(identity).

Group variables may be repeated, allowing for more general covariance
structures to be constructed as block-diagonal matrices based on the four
original structures.  Consider

. meqrlogit f_p || school: z1 z2, nocons cov(id) || school: z3 z4,
nocons cov(un) options

which specifies four random coefficients at the school level.  The
variance-covariance matrix of the random effects is the 4 x 4 matrix
where the upper 2 x 2 diagonal block is a multiple of the identity matrix
and the lower 2 x 2 diagonal block is unstructured.  In effect, the
coefficients on z1 and z2 are constrained to be independent and share a
common variance.  The coefficients on z3 and z4 each have a distinct
variance and a variance distinct from that of the coefficients on z1 and
z2.  They are also allowed to be correlated, yet they are independent
from the coefficients on z1 and z2.

For mixed models with no nested grouping structure, thinking of the
entire estimation data as one group is convenient.  Toward this end,
meqrlogit allows the special group designation _all.  meqrlogit also
allows the R.varname notation, which is shorthand for describing the
levels of varname as a series of indicator variables.  See example 8 in
[ME] me for more details.

Examples

---------------------------------------------------------------------------
Setup

Two-level random-intercept model, analogous to xtlogit
. meqrlogit c_use urban age child* || district:

Two-level random-intercept and random-coefficient model
. meqrlogit c_use urban age child* || district: urban

Two-level random-intercept and random-coefficient model, correlated
random effects
. meqrlogit c_use urban age child* || district: urban, cov(unstruct)

---------------------------------------------------------------------------
Setup
. webuse towerlondon

Three-level nested model, subject nested within family
. meqrlogit dtlm difficulty i.group || family: || subject:

Three-level nested model, altering the number of integration points
. meqrlogit dtlm difficulty i.group || family: || subject:,
intpoints(4 5)

Replaying fixed effects as odds ratios
. meqrlogit, or

---------------------------------------------------------------------------
Setup
. webuse fifeschool
. gen byte attain_gt_6 = attain > 6

Two-way crossed random effects
. meqrlogit attain_gt_6 sex || _all:R.sid || pid:

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

Stored results

meqrlogit 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(df_m)                 model degrees of freedom
e(ll)                   log likelihood
e(chi2)                 chi-squared
e(p)                    p-value for model test
e(ll_c)                 log likelihood, comparison model
e(chi2_c)               chi-squared, comparison test
e(df_c)                 degrees of freedom, comparison test
e(p_c)                  p-value for comparison test
e(rank)                 rank of e(V)
e(ic)                   number of iterations
e(reparm_rc)            return code, final reparameterization
e(rc)                   return code
e(converged)            1 if converged, 0 otherwise

Macros
e(cmd)                  meqrlogit
e(cmdline)              command as typed
e(depvar)               name of dependent variable
e(ivars)                grouping variables
e(model)                logistic
e(title)                title in estimation output
e(offset)               offset
e(binomial)             binomial number of trials
e(redim)                random-effects dimensions
e(vartypes)             variance-structure types
e(revars)               random-effects covariates
e(laplace)              laplace, if Laplace approximation
e(chi2type)             Wald; type of model chi-squared
e(method)               ML
e(opt)                  type of optimization
e(ml_method)            type of ml method
e(technique)            maximization technique
e(datasignature)        the checksum
e(datasignaturevars)    variables used in calculation of checksum
e(properties)           b V
e(estat_cmd)            program used to implement estat
e(predict)              program used to implement predict
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(N_g)                  group counts
e(g_min)                group-size minimums
e(g_avg)                group-size averages
e(g_max)                group-size maximums
e(V)                    variance-covariance matrix of the estimators

Functions
e(sample)               marks estimation sample

```