Stata 15 help for xtmepoisson

xtmepoisson has been renamed to meqrpoisson. xtmepoisson continues to work but, as of Stata 13, is no longer an official part of Stata. This is the original help file, which we will no longer update, so some links may no longer work.

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

Title

[XT] xtmepoisson -- Multilevel mixed-effects Poisson regression

Syntax

xtmepoisson 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 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 _all representing one group comprising all observations.

fe_options Description ------------------------------------------------------------------------- Model noconstant suppress constant term from the fixed-effects equation exposure(varname_e) include ln(varname_e) in model with coefficient constrained to 1 offset(varname_o) include varname_o 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 ------------------------------------------------------------------------- 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) irr report fixed-effects coefficients as incidence-rate 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 to Poisson regression display_options control column formats, row 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 legend instead of statistics -------------------------------------------------------------------------

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, mi estimate, rolling, and statsby are allowed; see prefix. coeflegend does not appear in the dialog box. See [XT] xtmepoisson postestimation for features available after estimation.

Menu

Statistics > Longitudinal/panel data > Multilevel mixed-effects models > Mixed-effects Poisson regression

Description

xtmepoisson fits mixed-effects models for count 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 Poisson. 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.

exposure(varname_e) specifies a variable that reflects the amount of exposure over which the depvar events were observed for each observation; ln(varname_e) is included in the fixed-effects portion of the model with coefficient constrained to be 1.

offset(varname_o) specifies that varname_o 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|unstructured

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 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.

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 xtmepoisson not omit collinear variables from the 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.

+-------------+ ----+ 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, that is, 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, but doing so is not recommended.

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.

irr reports the fixed-effects coefficients transformed to incidence-rate 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. irr 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 xtmepoisson from performing a likelihood-ratio test that compares the mixed-effects Poisson model with standard (marginal) Poisson regression. This option may also be specified upon replay to suppress this test from the output.

display_options: noomitted, vsquish, noemptycells, baselevels, allbaselevels, cformat(%fmt), pformat(%fmt), sformat(%fmt), and nolstretch; see [R] estimation options.

+--------------+ ----+ 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 xtmepoisson 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 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 xtmepoisson 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; 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 xtmepoisson 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 xtmepoisson would be of the form

. xtmepoisson 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,

. xtmepoisson 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

. xtmepoisson 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

. xtmepoisson 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, xtmepoisson allows the special group designation _all. xtmepoisson also allows the factor variable notation R.varname, which is shorthand for describing the levels of varname as a series of indicator variables. See example 5 in [XT] xtmelogit for more details.

Examples

--------------------------------------------------------------------------- Setup . webuse epilepsy

Two-level random-intercept model, analogous to xtpoisson . xtmepoisson seizures treat lbas lbas_trt lage v4 || subject:

Two-level random-intercept and random-coefficient model . xtmepoisson seizures treat lbas lbas_trt lage visit || subject: visit

Two-level random-intercept and random-coefficient model, correlated random effects . xtmepoisson seizures treat lbas lbas_trt lage visit || subject: visit, cov(unstructured) intpoints(9)

Replay results with incidence-rate ratios and variances/covariances . xtmepoisson, irr variance

--------------------------------------------------------------------------- Setup . webuse melanoma

Three-level nested model, observations nested region nested within nation . xtmepoisson deaths uv c.uv#c.uv, exposure(expected) || nation: || region:

Four-level nested model, fit using laplace . xtmepoisson deaths uv c.uv#c.uv, exposure(expected) || nation: || region: || county:, laplace

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

Saved results

xtmepoisson 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) xtmepoisson e(cmdline) command as typed e(depvar) name of dependent variable e(ivars) grouping variables e(exposurevar) exposure variable e(model) Poisson e(title) title in estimation output e(offset) linear offset variable 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(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(Cns) constraints matrix 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


© Copyright 1996–2018 StataCorp LLC   |   Terms of use   |   Privacy   |   Contact us   |   What's new   |   Site index