help xtpoisson dialog: xtpoisson
also see: xtpoisson postestimation
-------------------------------------------------------------------------------
Title
[XT] xtpoisson -- Fixed-effects, random-effects, and population-averaged
Poisson models
Syntax
Random-effects (RE) model
xtpoisson depvar [indepvars] [if] [in] [weight] [, re RE_options]
Conditional fixed-effects (FE) model
xtpoisson depvar [indepvars] [if] [in] [weight] , fe [FE_options]
Population-averaged (PA) model
xtpoisson depvar [indepvars] [if] [in] [weight] , pa [PA_options]
RE_options description
-------------------------------------------------------------------------
Model
noconstant suppress constant term
re use random-effects estimator; the default
exposure(varname) include ln(varname) in model with
coefficient constrained to 1
offset(varname) include varname in model with coefficient
constrained to 1
normal use a normal distribution for random effects
instead of gamma
constraints(constraints) apply specified linear constraints
collinear keep collinear variables
SE
vce(vcetype) vcetype may be oim, bootstrap, or jackknife
Reporting
level(#) set confidence level; default is level(95)
irr report incidence-rate ratios
noskip fit constant-only model and perform
likelihood-ratio test
nocnsreport do not display constraints
display_options control spacing and display of omitted
variables and base and empty cells
Integration
intmethod(intmethod) integration method; intmethod may be
mvaghermite, aghermite, or ghermite;
default is intmethod(mvaghermite)
intpoints(#) use # quadrature points; default is
intpoints(12)
Maximization
maximize_options control the maximization process; seldom
used
+ coeflegend display coefficients' legend instead of
coefficient table
-------------------------------------------------------------------------
+ coeflegend does not appear in the dialog box.
FE_options description
-------------------------------------------------------------------------
Model
fe use fixed-effects estimator
noconstant suppress constant term
exposure(varname) include ln(varname) in model with
coefficient constrained to 1
offset(varname) include varname in model with coefficient
constrained to 1
constraints(constraints) apply specified linear constraints
collinear keep collinear variables
SE
vce(vcetype) vcetype may be oim, bootstrap, or jackknife
Reporting
level(#) set confidence level; default is level(95)
irr report incidence-rate ratios
noskip fit constant-only model and perform
likelihood-ratio test
nocnsreport do not display constraints
display_options control spacing and display of omitted
variables and base and empty cells
Maximization
maximize_options control the maximization process; seldom
used
+ coeflegend display coefficients' legend instead of
coefficient table
-------------------------------------------------------------------------
+ coeflegend does not appear in the dialog box.
PA_options description
-------------------------------------------------------------------------
Model
noconstant suppress constant term
pa use population-averaged estimator
exposure(varname) include ln(varname) in model with
coefficient constrained to 1
offset(varname) include varname in model with coefficient
constrained to 1
Correlation
corr(correlation) within-group correlation structure
force estimate even if observations unequally
spaced in time
SE/Robust
vce(vcetype) vcetype may be conventional, robust,
bootstrap, or jackknife
nmp use divisor N-P instead of the default N
scale(parm) override the default scale parameter; parm
may be x2, dev, phi, or #
Reporting
level(#) set confidence level; default is level(95)
irr report incidence-rate ratios
display_options control spacing and display of omitted
variables and base and empty cells
Optimization
optimize_options control the optimization process; seldom
used
+ coeflegend display coefficients' legend instead of
coefficient table
-------------------------------------------------------------------------
+ coeflegend does not appear in the dialog box.
correlation description
-------------------------------------------------------------------------
exchangeable exchangeable
independent independent
unstructured unstructured
fixed matname user-specified
ar # autoregressive of order #
stationary # stationary of order #
nonstationary # nonstationary of order #
-------------------------------------------------------------------------
A panel variable must be specified. For xtpoisson, pa, correlation
structures other than exchangeable and independent require that a time
variable also be specified. Use xtset.
indepvars may contain factor variables; see fvvarlist.
depvar and indepvars may contain time-series operators; see tsvarlist.
by and statsby are allowed; see prefix.
iweights, fweights, and pweights are allowed for the population-averaged
model, and iweights are allowed in the random-effects and fixed-effects
models; see weight. Weights must be constant within panel.
See [XT] xtpoisson postestimation for features available after
estimation.
Menu
Statistics > Longitudinal/panel data > Count outcomes > Poisson
regression (FE, RE, PA)
Description
xtpoisson fits random-effects, conditional fixed-effects, and
population-averaged Poisson models. Whenever we refer to a fixed-effects
model, we mean the conditional fixed-effects model.
By default, the population-averaged model is an equal-correlation model;
xtpoisson assumes corr(exchangeable). See [XT] xtgee for details on how
to fit other population-averaged models.
Options for RE model
+-------+
----+ Model +------------------------------------------------------------
noconstant; see [R] estimation options.
re, the default, requests the random-effects estimator.
exposure(varname), offset(varname); see [R] estimation options.
normal specifies that the random effects follow a normal distribution
instead of a gamma distribution.
constraints(constraints), collinear; see [R] estimation options.
+----+
----+ SE +---------------------------------------------------------------
vce(vcetype) specifies the type of standard error reported, which
includes types that are derived from asymptotic theory and that use
bootstrap or jackknife methods; see [XT] vce_options.
+-----------+
----+ Reporting +--------------------------------------------------------
level(#); see [R] estimation options.
irr reports exponentiated coefficients e^b rather than coefficients b.
For the Poisson model, exponentiated coefficients are interpreted as
incidence-rate ratios.
noskip; see [R] estimation options.
nocnsreport; see [R] estimation options.
display_options: noomitted, vsquish, noemptycells, baselevels,
allbaselevels; see [R] estimation options.
+-------------+
----+ Integration +------------------------------------------------------
intmethod(intmethod), intpoints(#); 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. Some of these options are not
available if intmethod(ghermite) is specified. These options are
seldom used.
The following option is available with xtpoisson but is not shown in the
dialog box:
coeflegend; see [R] estimation options.
Options for FE model
+-------+
----+ Model +------------------------------------------------------------
fe requests the fixed-effects estimator.
exposure(varname), offset(varname), constraints(constraints), collinear;
see [R] estimation options.
+----+
----+ SE +---------------------------------------------------------------
vce(vcetype) specifies the type of standard error reported, which
includes types that are derived from asymptotic theory and that use
bootstrap or jackknife methods; see [XT] vce_options.
+-----------+
----+ Reporting +--------------------------------------------------------
level(#); see [R] estimation options.
irr reports exponentiated coefficients e^b rather than coefficients b.
For the Poisson model, exponentiated coefficients are interpreted as
incidence-rate ratios.
noskip; see [R] estimation options.
nocnsreport; see [R] estimation options.
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. These options are seldom used.
The following option is available with xtpoisson but is not shown in the
dialog box:
coeflegend; see [R] estimation options.
Options for PA model
+-------+
----+ Model +------------------------------------------------------------
noconstant; see [R] estimation options.
pa requests the population-averaged estimator.
exposure(varname), offset(varname); see [R] estimation options.
+-------------+
----+ Correlation +------------------------------------------------------
corr(correlation), force; see [R] estimation options.
+-----------+
----+ SE/Robust +--------------------------------------------------------
vce(vcetype) specifies the type of standard error reported, which
includes types that are derived from asymptotic theory, that are
robust to some kinds of misspecification, and that use bootstrap or
jackknife methods; see [XT] vce_options.
vce(conventional), the default, uses the conventionally derived
variance estimator for generalized least squares regression.
nmp, scale(x2|dev|phi|#); see [XT] vce_options.
+-----------+
----+ Reporting +--------------------------------------------------------
level(#); see [R] estimation options.
irr reports exponentiated coefficients e^b rather than coefficients b.
For the Poisson model, exponentiated coefficients are interpreted as
incidence-rate ratios.
display_options: noomitted, vsquish, noemptycells, baselevels,
allbaselevels; see [R] estimation options.
+--------------+
----+ Optimization +-----------------------------------------------------
optimize_options control the iterative optimization process. These
options are seldom used.
iterate(#) specifies the maximum number of iterations. When the
number of iterations equals #, the optimization stops and presents
the current results, even if the convergence tolerance has not been
reached. The default value of iterate() is 100.
tolerance(#) specifies the tolerance for the coefficient vector.
When the relative change in the coefficient vector from one iteration
to the next is less than or equal to #, the optimization process is
stopped. tolerance(1e-6) is the default.
nolog suppress the display of the iteration log.
trace specifies that the current estimates should be printed at each
iteration.
The following option is available with xtpoisson but is not shown in the
dialog box:
coeflegend; see [R] estimation options.
Technical note
The random-effects model is calculated using quadrature, which is an
approximation whose accuracy depends partially on the number of
integration points used. We can use the quadchk command to see if
changing the number of integration points affects the results. If the
results change, the quadrature approximation is not accurate given the
number of integration points. Try increasing the number of integration
points using the intpoints() option and again run quadchk. Do not
attempt to interpret the results of estimates when the coefficients
reported by quadchk differ substantially. See [XT] quadchk for details
and [XT] xtprobit for an example.
Because the xtpoisson, re normal likelihood function is calculated by
Gauss-Hermite quadrature, on large problems, the computations can be
slow. Computation time is roughly proportional to the number of points
used for the quadrature.
Examples
Setup
. webuse ships
. xtset ship
Random-effects model
. xtpoisson accident op_75_79 co_65_69 co_70_74 co_75_79,
exposure(service) irr
Fixed-effects model
. xtpoisson accident op_75_79 co_65_69 co_70_74 co_75_79,
exposure(service) irr fe
Random-effects model with random effects following normal distribution
. xtpoisson accident op_75_79 co_65_69 co_70_74 co_75_79,
exposure(service) irr normal
Equal-correlation population-averaged model with robust variance
. xtpoisson accident op_75_79 co_65_69 co_70_74 co_75_79,
exposure(service) pa vce(robust) irr
Saved results
xtpoisson, re saves the following in e():
Scalars
e(N) number of observations
e(N_g) number of groups
e(N_cd) number of completely determined observations
e(k) number of parameters
e(k_aux) number of auxiliary parameters
e(k_eq) number of equations
e(k_eq_model) number of equations in model Wald test
e(k_dv) number of dependent variables
e(k_autoCns) number of base, empty, and omitted constraints
e(df_m) model degrees of freedom
e(ll) log likelihood
e(ll_0) log likelihood, constant-only model
e(ll_c) log likelihood, comparison model
e(chi2) chi-squared
e(chi2_c) chi-squared for comparison test
e(sigma_u) panel-level standard deviation
e(alpha) the value of alpha
e(g_min) smallest group size
e(g_avg) average group size
e(g_max) largest group size
e(p) significance
e(rank) rank of e(V)
e(rank0) rank of e(V) for constant-only model
e(ic) number of iterations
e(rc) return code
e(converged) 1 if converged, 0 otherwise
Macros
e(cmd) xtpoisson
e(cmdline) command as typed
e(depvar) name of dependent variable
e(ivar) variable denoting groups
e(wtype) weight type
e(wexp) weight expression
e(title) title in estimation output
e(offset) offset
e(chi2type) Wald or LR; type of model chi-squared test
e(chi2_ct) Wald or LR; type of model chi-squared test
corresponding to e(chi2_c
e(vce) vcetype specified in vce()
e(vcetype) title used to label Std. Err.
e(method) requested estimation method
e(distrib) Gamma; the distribution of the random effect
e(diparm#) display transformed parameter #
e(opt) type of optimization
e(which) max or min; whether optimizer is to perform
maximization or minimization
e(ml_method) type of ml method
e(user) name of likelihood-evaluator program
e(technique) maximization technique
e(singularHmethod) m-marquardt or hybrid; method used when Hessian is
singular
e(crittype) optimization criterion
e(properties) b V
e(predict) program used to implement predict
e(asbalanced) factor variables fvset as asbalanced
e(asobserved) factor variables fvset as asobserved
Matrices
e(b) coefficient vector
e(Cns) constraints matrix
e(ilog) iteration log
e(gradient) gradient vector
e(V) variance-covariance matrix of the estimators
Functions
e(sample) marks estimation sample
xtpoisson, re normal saves the following in e():
Scalars
e(N) number of observations
e(N_g) number of groups
e(N_cd) number of completely determined observations
e(k) number of parameters
e(k_aux) number of auxiliary parameters
e(k_eq) number of equations
e(k_eq_model) number of equations in model Wald test
e(k_dv) number of dependent variables
e(k_autoCns) number of base, empty, and omitted constraints
e(df_m) model degrees of freedom
e(ll) log likelihood
e(ll_0) log likelihood, constant-only model
e(ll_c) log likelihood, comparison model
e(chi2) chi-squared
e(chi2_c) chi-squared for comparison test
e(sigma_u) panel-level standard deviation
e(n_quad) number of quadrature points
e(g_min) smallest group size
e(g_avg) average group size
e(g_max) largest group size
e(p) significance
e(rank) rank of e(V)
e(rank0) rank of e(V) for constant-only model
e(ic) number of iterations
e(rc) return code
e(converged) 1 if converged, 0 otherwise
Macros
e(cmd) xtpoisson
e(cmdline) command as typed
e(depvar) name of dependent variable
e(ivar) variable denoting groups
e(wtype) weight type
e(wexp) weight expression
e(title) title in estimation output
e(offset) offset
e(offset1) ln(varname), where varname is variable from
exposure()
e(chi2type) Wald or LR; type of model chi-squared test
e(chi2_ct) Wald or LR; type of model chi-squared test
corresponding to e(chi2_c
e(vce) vcetype specified in vce()
e(vcetype) title used to label Std. Err.
e(intmethod) integration method
e(distrib) Gaussian; the distribution of the random effect
e(diparm#) display transformed parameter #
e(opt) type of optimization
e(which) max or min; whether optimizer is to perform
maximization or minimization
e(ml_method) type of ml method
e(user) name of likelihood-evaluator program
e(technique) maximization technique
e(singularHmethod) m-marquardt or hybrid; method used when Hessian is
singular
e(crittype) optimization criterion
e(properties) b V
e(predict) program used to implement predict
e(asbalanced) factor variables fvset as asbalanced
e(asobserved) factor variables fvset as asobserved
Matrices
e(b) coefficient vector
e(Cns) constraints matrix
e(ilog) iteration log
e(gradient) gradient vector
e(V) variance-covariance matrix of the estimators
Functions
e(sample) marks estimation sample
xtpoisson, fe saves the following in e():
Scalars
e(N) number of observations
e(N_g) number of groups
e(k) number of parameters
e(k_eq) number of equations
e(k_eq_model) number of equations in model Wald test
e(k_dv) number of dependent variables
e(k_autoCns) number of base, empty, and omitted constraints
e(df_m) model degrees of freedom
e(ll) log likelihood
e(ll_0) log likelihood, constant-only model
e(ll_c) log likelihood, comparison model
e(chi2) chi-squared
e(g_min) smallest group size
e(g_avg) average group size
e(g_max) largest group size
e(p) significance
e(rank) rank of e(V)
e(ic) number of iterations
e(rc) return code
e(converged) 1 if converged, 0 otherwise
Macros
e(cmd) xtpoisson
e(cmdline) command as typed
e(depvar) name of dependent variable
e(ivar) variable denoting groups
e(wtype) weight type
e(wexp) weight expression
e(title) title in estimation output
e(offset) offset
e(chi2type) LR; type of model chi-squared test
e(vce) vcetype specified in vce()
e(vcetype) title used to label Std. Err.
e(method) requested estimation method
e(opt) type of optimization
e(which) max or min; whether optimizer is to perform
maximization or minimization
e(ml_method) type of ml method
e(user) name of likelihood-evaluator program
e(technique) maximization technique
e(singularHmethod) m-marquardt or hybrid; method used when Hessian is
singular
e(crittype) optimization criterion
e(properties) b V
e(predict) program used to implement predict
e(asbalanced) factor variables fvset as asbalanced
e(asobserved) factor variables fvset as asobserved
Matrices
e(b) coefficient vector
e(Cns) constraints matrix
e(ilog) iteration log
e(gradient) gradient vector
e(V) variance-covariance matrix of the estimators
Functions
e(sample) marks estimation sample
xtpoisson, pa saves the following in e():
Scalars
e(N) number of observations
e(N_g) number of groups
e(df_m) model degrees of freedom
e(chi2) chi-squared
e(df_pear) degrees of freedom for Pearson chi-squared
e(chi2_dev) chi-squared test of deviance
e(chi2_dis) chi-squared test of deviance dispersion
e(deviance) deviance
e(dispers) deviance dispersion
e(phi) scale parameter
e(g_min) smallest group size
e(g_avg) average group size
e(g_max) largest group size
e(rank) rank of e(V)
e(tol) target tolerance
e(dif) achieved tolerance
e(rc) return code
Macros
e(cmd) xtgee
e(cmd2) xtpoisson
e(cmdline) command as typed
e(depvar) name of dependent variable
e(ivar) variable denoting groups
e(family) Poisson
e(link) log; link function
e(corr) correlation structure
e(scale) x2, dev, phi, or #; scale parameter
e(wtype) weight type
e(wexp) weight expression
e(offset) offset
e(chi2type) Wald; type of model chi-squared test
e(vce) vcetype specified in vce()
e(vcetype) covariance estimation method
e(robust_prolog) program to prepare estimates for linearized VCE
computations
e(robust_epilog) program to finalize estimates after linearized VCE
computations
e(crittype) optimization criterion
e(properties) b V
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(R) estimated working correlation matrix
e(V) variance-covariance matrix of the estimators
e(V_modelbased) model-based variance
Functions
e(sample) marks estimation sample
Also see
Manual: [XT] xtpoisson
Help: [XT] xtpoisson postestimation;
[XT] quadchk, [XT] xtgee, [XT] xtnbreg, [R] poisson
