help xtmelogit dialog: xtmelogit
also see: xtmelogit postestimation
-------------------------------------------------------------------------------
Title
[XT] xtmelogit -- Multilevel mixed-effects logistic regression
Syntax
xtmelogit 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 a random effect among the levels of a factor variable
levelvar: R.varname [, re_options]
levelvar is the grouping variable for the random effects at that level,
or _all for the inclusive group comprising all observations.
fe_options description
-------------------------------------------------------------------------
Model
noconstant suppress the constant 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 the constant from the
random-effects equation
collinear keep collinear variables
-------------------------------------------------------------------------
options description
-------------------------------------------------------------------------
Model
binomial(varname|#) set binomial trials if data are in
binomial form
Integration
laplace use Laplacian approximation; equivalent
to intpoints(1)
intpoints(# [# ...]) set the number of integration
(quadrature) points; default is 7
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
noretable suppress random-effects table
nofetable suppress fixed-effects table
estmetric show parameter estimates in the
estimation metric
noheader suppress output header
nogroup suppress table summarizing groups
nolrtest do not perform LR test comparing with
logistic regression
display_options control spacing and display of omitted
variables and base and empty cells
Maximization
maximize_options control the maximization process during
gradient-based optimization; 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 coefficients' legend instead of
coefficient table
-------------------------------------------------------------------------
+ coeflegend does not appear in the dialog box.
vartype description
-------------------------------------------------------------------------
independent one variance parameter per random effect, all
covariances zero; the default unless a factor
variable is specified
exchangeable equal variances for random effects, and one
common pairwise covariance
identity equal variances for random effects, all
covariances zero; the default if factor
variables are specified
unstructured all variances-covariances distinctly estimated
-------------------------------------------------------------------------
indepvars may contain factor variables; see fvvarlist.
indepvars and varlist may contain time-series operators; see tsvarlist.
bootstrap, by, jackknife, rolling, and statsby are allowed; see prefix.
See [XT] xtmelogit postestimation for features available after
estimation.
Menu
Statistics > Longitudinal/panel data > Multilevel mixed-effects models >
Mixed-effects logistic regression
Description
xtmelogit fits mixed-effects models for binary/binomial responses. Mixed
models contain both fixed effects and random effects. The fixed effects
are analogous to standard regression coefficients and are estimated
directly. The random effects are not directly estimated (although they
may be obtained postestimation) but are summarized according to their
estimated variances and covariances. Random effects may take the form of
either random intercepts or random coefficients, and the grouping
structure of the data may consist of multiple levels of nested groups.
The distribution of the random effects is assumed to be Gaussian. The
conditional distribution of the response given the random effects is
assumed to be Bernoulli, with success probability determined by the
logistic cumulative distribution function (c.d.f.). Because the log
likelihood for this model has no closed form, it is approximated by
adaptive Gaussian quadrature.
Options
+-------+
----+ Model +------------------------------------------------------------
noconstant suppresses the constant (intercept) term and may be specified
for the fixed effects equation and for any 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), where vartype is
independent | exchangeable | identity | unstructure
specifies the structure of the covariance matrix for the random
effects and may be specified for each random-effects equation. An
independent covariance structure allows a distinct variance for each
random effect within a random-effects equation and assumes that all
covariances are zero. exchangeable covariances have common variances
and one common pairwise covariance. identity is short for "multiple
of the identity"; that is, all variances are equal and all
covariances are zero. unstructured allows all variances and
covariances to be distinct. If an equation consists of p random
effects, the unstructured covariance matrix will have p(p+1)/2
parameters to be estimated.
covariance(independent) is the default, except when the
random-effects equation consists of the factor variable specification
R.varname, in which case covariance(identity) is the default, and
only covariance(identity) and covariance(exchangeable) are allowed.
collinear specifies that xtmelogit not omit collinear variables from a
random-effects equation. Usually there is no reason to leave
collinear variables in place, and 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. The number of binomial trials is given either as varname,
which allows this number to vary over the observations, or as the
constant #. If binomial() is not specified, depvar is treated as
Bernoulli, with any nonzero, nonmissing values indicating positive
responses.
+-------------+
----+ Integration +------------------------------------------------------
laplace specifies that log likelihoods be calculated using the Laplacian
approximation, equivalent to adaptive Gaussian quadrature with one
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 and/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 estimates of the
fixed effects. If your interest lies primarily with the
fixed-effects estimates, the Laplace approximation may be a viable
faster alternative to adaptive quadrature with multiple integration
points.
Specifying a factor variable (R.varname) increases the dimension of
the random effects by the number of distinct values of varname, i.e.,
the number of factor levels. 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 have factor variables in your
random-effects equations, the laplace option is assumed. You can
override this behavior by using the intpoints() option.
intpoints(# [# ...]) sets the number of integration points for adaptive
Gaussian quadrature. The more 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 and/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.
+-----------+
----+ Reporting +--------------------------------------------------------
level(#); see [R] estimation options.
or reports the fixed-effects coefficients transformed to odds ratios,
i.e., 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 at
estimation or when replaying previously estimated results.
variance displays the random-effects parameter estimates as variances and
covariances. The default is to display them 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 the estimation metric.
Fixed-effects estimates are unchanged from those normally displayed,
but random-effects parameter estimates are displayed as log-standard
deviations and hyperbolic arctangents of correlations, with equation
names that organize them by level.
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.
nolrtest prevents xtmelogit from performing a likelihood-ratio test that
compares the mixed-effects logistic model with standard (marginal)
logistic regression. This option may also be specified upon replay
to suppress this test from the output.
display_options: noomitted, vsquish, noemptycells, baselevels,
allbaselevels; see [R] estimation options.
+--------------+
----+ Maximization +-----------------------------------------------------
maximize_options: difficult, technique(algorithm_spec), iterate(#),
[no]log, trace, gradient, showstep, hessian, showtolerance,
tolerance(#), ltolerance(#), nrtolerance(#), nonrtolerance,
from(init_specs); see [R] maximize. Those that require special
mention for xtmelogit 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)), which bypasses the initial optimization
stage; see below.
retolerance(#) specifies the convergence tolerance for the estimated
random effects used by adaptive Gaussian quadrature. Gaussian
quadrature points are adapted to be centered at the estimated random
effects given a current set of model parameters. Estimating these
random effects is an iterative procedure, with convergence declared
when the maximum relative change in the random effects is less than
retolerance(). The default retolerance() is 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 above. 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.
Both the matsqrt and matlog parameterizations ensure that
variance-covariance matrices are positive semidefinite. 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 xtmelogit takes place
in two stages. In the first stage, starting values are refined by
holding the quadrature points fixed between iterations. During the
second stage, quadrature points are adapted with each evaluation of
the log likelihood. Maximization options specified within
refineopts() control the first stage of optimization; i.e., 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 xtmelogit 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 xtmelogit would be of the form
. xtmelogit 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,
. xtmelogit 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
. xtmelogit 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
. xtmelogit 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,
xtmelogit allows the special group designation _all. xtmelogit also
allows the factor variable notation R.varname, which is shorthand for
describing the levels of varname as a series of indicator variables. See
[XT] xtmelogit for more details.
Examples
---------------------------------------------------------------------------
Setup
. webuse bangladesh
Random-intercept model, analogous to xtlogit
. xtmelogit c_use urban age child* || district:
Random-intercept and random-coefficient model
. xtmelogit c_use urban age child* || district: urban
Random-intercept and random-coefficient model, correlated random effects
. xtmelogit c_use urban age child* || district: urban, cov(unstruct)
---------------------------------------------------------------------------
Setup
. webuse towerlondon, clear
Two-level nested model, subject nested within family
. xtmelogit dtlm difficulty i.group || family: || subject:
Two-level nested model, altering the number of integration points
. xtmelogit dtlm difficulty i.group || family: || subject:,
intpoints(4 5)
Replaying fixed effects as odds ratios
. xtmelogit, or
and with variance components listed as variances and covariances
. xtmelogit, or variance
---------------------------------------------------------------------------
Setup
. webuse fifeschool, clear
. gen byte attain_gt_6 = attain > 6
Two-way crossed random effects
. xtmelogit attain_gt_6 sex || _all:R.sid || pid:
---------------------------------------------------------------------------
Saved results
xtmelogit saves the following in e():
Scalars
e(N) number of observations
e(k) number of parameters
e(k_f) number of FE parameters
e(k_r) number of RE parameters
e(k_rs) number of standard deviations
e(k_rc) number of correlations
e(df_m) fixed-effects model degrees of freedom
e(ll) log likelihood
e(chi2) chi-squared
e(p) p-value for chi-squared
e(ll_c) log-likelihood, comparison model
e(chi2_c) chi-squared, comparison model
e(df_c) degrees of freedom, comparison model
e(p_c) p-value, comparison model
e(rank) rank of e(V)
e(reparm_rc) return code, final reparameterization
e(rc) return code
e(converged) 1 if converged, 0 otherwise
Macros
e(cmd) xtmelogit
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(n_quad) number of integration points
e(laplace) laplace, if Laplace approximation
e(chi2type) Wald; type of model chi-squared test
e(vce) bootstrap or jackknife if defined
e(vcetype) title used to label Std. Err.
e(method) ML
e(opt) type of optimization
e(ml_method) type of ml method
e(technique) maximization technique
e(crittype) optimization criterion
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(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
Also see
Manual: [XT] xtmelogit
Help: [XT] xtmelogit postestimation;
[XT] xtmepoisson, [XT] xtmixed, [XT] xtlogit, [XT] xtreg, [XT]
xtrc, [XT] xtgee
