**[R] ivpoisson** -- Poisson model with continuous endogenous covariates

__Syntax__

Generalized method of moments estimator

**ivpoisson** **gmm** *depvar* [*varlist1*] [**(***varlist2* **=** *varlist_iv***)**] [*if*] [*in*]
[*weight*] [**,** *reg_err_opt* *options*]

Control-function estimator

**ivpoisson** __cfunc__**tion** *depvar* [*varlist1*] **(***varlist2* **=** *varlist_iv***)** [*if*] [
*in*] [*weight*] [**,** *options*]

*reg_err_opt* Description
-------------------------------------------------------------------------
Model
__add__**itive** add regression errors to the conditional
mean term; the default
__mult__**iplicative** multiply regression errors by the
conditional mean term
-------------------------------------------------------------------------

*options* Description
-------------------------------------------------------------------------
Model
__nocons__**tant** suppress constant term
__exp__**osure(***varname_e***)** include ln(*varname_e*) in model with
coefficient constrained to 1
__off__**set(***varname_o***)** include *varname_o* in model with coefficient
constrained to 1
* __two__**step** use two-step GMM estimator; the default for
**ivpoisson gmm**
* __one__**step** use one-step GMM estimator; the default for
**ivpoisson cfunction**
* __i__**gmm** use iterative GMM estimator

Weight matrix
__wmat__**rix(***wmtype***)** specify weight matrix; *wmtype* may be
__r__**obust**, __cl__**uster** *clustvar*, or __un__**adjusted**
__c__**enter** center moments in weight-matrix computation
__winit__**ial(***iwtype*[**, **__indep__**endent**]**)**
specify initial weight matrix; *iwtype* may
be __un__**adjusted**, __i__**dentity**, or the name of a
Stata matrix (**independent** may not be
specified with **ivpoisson gmm**)

SE/Robust
**vce(***vcetype***)** *vcetype* may be __r__**obust**, __cl__**uster** *clustvar*,
__boot__**strap**, __jack__**knife**, or __un__**adjusted**

Reporting
__l__**evel(***#***)** set confidence level; default is **level(95)**
__ir__**r** report incidence-rate ratios
*display_options* control columns and column formats, row
spacing, line width, display of omitted
variables and base and empty cells, and
factor-variable labeling

Optimization
**from(***initial_values***)** specify initial values for parameters
# __igmmit__**erate(***#***)** specify maximum number of iterations for
iterated GMM estimator
# **igmmeps(***#***)** specify # for iterated GMM parameter
convergence criterion; default is
**igmmeps(1e-6)**
# **igmmweps(***#***)** specify # for iterated GMM weight-matrix
convergence criterion; default is
**igmmweps(1e-6)**
*optimization_options* control the optimization process; seldom
used
-------------------------------------------------------------------------
* You can specify at most one of these options.
# These options may be specified only when **igmm** is specified.
*varlist1* and *varlist_iv* may contain factor variables; see fvvarlist.
*depvar*, *varlist1*, *varlist2*, and *varlist_iv* may contain time-series
operators; see tsvarlist.
**bootstrap**, **by**, **jackknife**, **rolling**, and **statsby** are allowed; see prefix.
Weights are not allowed with the **bootstrap** prefix.
**aweight**s are not allowed with the **jackknife** prefix.
**aweight**s, **fweight**s, **iweight**s, and **pweight**s are allowed; see weight.
See **[R] ivpoisson postestimation** for features available after estimation.

__Menu__

**Statistics > Endogenous covariates > Poisson model with endogenous**
**covariates**

__Description__

**ivpoisson** estimates the parameters of a Poisson regression model in which
some of the covariates are endogenous. The model is also known as an
exponential conditional mean model in which some of the covariates are
endogenous. The model may be specified using either additive or
multiplicative error terms. The model is frequently used to model count
outcomes and is also used to model nonnegative outcome variables.

__Options__

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

**noconstant**, **exposure(***varname_e***)**, **offset(***varname_o***)**; see **[R] estimation**
**options**.

**additive**, the default, specifies that the regression errors be added to
the conditional mean term and have mean 0.

**multiplicative** specifies that the regression errors be multiplied by the
conditional mean term and have mean 1.

**twostep**, **onestep**, and **igmm** specify which estimator is to be used.

**twostep** requests the two-step GMM estimator. **gmm** obtains parameter
estimates based on the initial weight matrix, computes a new weight
matrix based on those estimates, and then reestimates the parameters
based on that weight matrix. **twostep** is the default for **ivpoisson**
**gmm**.

**onestep** requests the one-step GMM estimator. The parameters are
estimated based on an initial weight matrix, and no updating of the
weight matrix is performed except when calculating the appropriate
variance-covariance (VCE) matrix. **onestep** is the default for
**ivpoisson cfunction**.

**igmm** requests the iterative GMM estimator. **gmm** obtains parameter
estimates based on the initial weight matrix, computes a new weight
matrix based on those estimates, reestimates the parameters based on
that weight matrix, computes a new weight matrix, and so on, to
convergence. Convergence is declared when the relative change in the
parameter vector is less than **igmmeps()**, the relative change in the
weight matrix is less than **igmmweps()**, or **igmmiterate()** iterations
have been completed. Hall (2005, sec. 2.4 and 3.6) mentions that
there may be gains to finite-sample efficiency from using the
iterative estimator.

+---------------+
----+ Weight matrix +----------------------------------------------------

**wmatrix(***wmtype***)** specifies the type of weight matrix to be used in
conjunction with the two-step and iterated GMM estimators.

Specifying **wmatrix(robust)** requests a weight matrix that is
appropriate when the errors are independent but not necessarily
identically distributed. **wmatrix(robust)** is the default.

Specifying **wmatrix(cluster** *clustvar***)** requests a weight matrix that
accounts for arbitrary correlation among observations within clusters
identified by *clustvar*.

Specifying **wmatrix(unadjusted)** requests a weight matrix that is
suitable when the errors are homoskedastic.

**wmatrix()** cannot be specified if **onestep** is also specified.

**center** requests that the sample moments be centered (demeaned) when
computing GMM weight matrices. By default, centering is not done.

**winitial(***wmtype*[**,** **independent**]**)** specifies the weight matrix to use to
obtain the first-step parameter estimates.

Specifying **winitial(unadjusted)** requests a weighting matrix that
assumes the error functions are independent and identically
distributed. This matrix is of the form (**Z**'**Z**)^-1, where **Z** represents
all the exogenous and instrumental variables.

**winitial(identity)** requests that the identity matrix be used.

**winitial(***matname***)** requests that Stata matrix *matname* be used.

Including the **independent** suboption creates a weight matrix that
assumes error functions are independent. Elements of the weight
matrix corresponding to covariances between any two error functions
are set equal to zero. This suboption only applies to **ivpoisson**
**cfunction**.

**winitial(unadjusted)** is the default for **ivpoisson gmm**.

**winitial(unadjusted, independent)** is the default for **ivpoisson**
**cfunction**.

+-----------+
----+ SE/Robust +--------------------------------------------------------

**vce(***vcetype***)** specifies the type of standard error reported, which
includes types that are robust to some kinds of misspecification
(**robust**), that allow for intragroup correlation (**cluster** *clustvar*),
and that use bootstrap or jackknife methods (**bootstrap**, **jackknife**);
see **[R] ***vce_option*.

**vce(unadjusted)** specifies that an unadjusted (nonrobust) VCE matrix
be used; this, along with the **twostep** option, results in the "optimal
two-step GMM" estimates often discussed in textbooks.
**vce(unadjusted)** may not be set in **ivpoisson cfunction**.

The default *vcetype* is based on the *wmtype* specified in the **wmatrix()**
option. If **wmatrix()** is specified but **vce()** is not, then *vcetype* is
set equal to *wmtype*. To override this behavior in** ivpoisson gmm** and
obtain an unadjusted (nonrobust) VCE matrix, specify **vce(unadjusted)**.
The default *vcetype* for **ivpoisson cfunction** is **robust**.

Specifying **vce(bootstrap)** or **vce(jackknife)** results in standard
errors based on the bootstrap or jackknife, respectively. See **[R]**
*vce_option*, **[R] bootstrap**, and **[R] jackknife** for more information on
these VCEs.

The syntax for *vcetype*s is identical to those for **wmatrix()**.

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

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

**irr** reports estimated 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 or stored. **irr** may be
specified at estimation or when replaying previously estimated
results. **irr** is not allowed with **additive**.

*display_options*: **noci**, __nopv__**alues**, __noomit__**ted**, **vsquish**, __noempty__**cells**,
__base__**levels**, __allbase__**levels**, __nofvlab__**el**, **fvwrap(***#***)**, **fvwrapon(***style***)**,
**cformat(***%fmt***)**, **pformat(%***fmt***)**, **sformat(%***fmt***)**, and **nolstretch**; see **[R]**
**estimation options**.

+--------------+
----+ Optimization +-----------------------------------------------------

**from(***initial_values***)** specifies the initial values to begin the
estimation. You can specify a 1 x k matrix, where k is the number of
parameters in the model, or you can specify a parameter name, its
initial value, another parameter name, its initial value, and so on.
For example, to initialize the coefficient for **male** to 1.23 and the
constant **_cons** to 4.57, you would type

**ivpoisson** ...**,** **from(male 1.23 _cons 4.57)** ...

Initial values declared using this option override any that are
declared within substitutable expressions. If you specify a
parameter that does not appear in your model, **ivpoisson** exits with
error code 480. If you specify a matrix, the values must be in the
same order in which the parameters are declared in your model.
**ivpoisson** ignores the row and column names of the matrix.

**igmmiterate(***#***)**, **igmmeps(***#***)**, and **igmmweps(***#***)** control the iterative process
for the iterative GMM estimator for **ivpoisson**. These options can be
specified only if you also specify **igmm**.

**igmmiterate(***#***)** specifies the maximum number of iterations to perform
with the iterative GMM estimator. The default is the number set
using **set maxiter**, which is 16,000 by default.

**igmmeps(***#***)** specifies the convergence criterion used for successive
parameter estimates when the iterative GMM estimator is used.
The default is **igmmeps(1e-6)**. Convergence is declared when the
relative difference between successive parameter estimates is
less than **igmmeps()** and the relative difference between
successive estimates of the weight matrix is less than
**igmmweps()**.

**igmmweps(***#***)** specifies the convergence criterion used for successive
estimates of the weight matrix when the iterative GMM estimator
is used. The default is **igmmweps(1e-6)**. Convergence is declared
when the relative difference between successive parameter
estimates is less than **igmmeps()** and the relative difference
between successive estimates of the weight matrix is less than
**igmmweps()**.

*optimization_options*: __tech__**nique()**, **conv_maxiter()**, **conv_ptol()**,
**conv_vtol()**, **conv_nrtol()**, and **tracelevel()**. **technique()** specifies
the optimization technique to use; **gn** (the default), **nr**, **dfp**, and
**bfgs** are allowed. **conv_maxiter()** specifies the maximum number of
iterations; **conv_ptol()**, **conv_vtol()**, and **conv_nrtol()** specify the
convergence criteria for the parameters, gradient, and scaled
Hessian, respectively. **tracelevel()** allows you to obtain additional
details during the iterative process. See **[M-5] optimize()**.

__Examples__

---------------------------------------------------------------------------
Setup
**. webuse website**

Generalized method of moments: additive errors
**. ivpoisson gmm visits ad female** **(time = phone frfam)**

---------------------------------------------------------------------------
Setup
**. webuse trip**

Generalized method of moments: multiplicative errors
**. ivpoisson gmm trips cbd ptn worker weekend (tcost=pt),**
**multiplicative**

Display incidence-rate ratios
**. ivpoisson, irr**

Control-function method
**. ivpoisson cfunction trips cbd ptn worker weekend (tcost=pt)**

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

__Stored results__

**ivpoisson** stores the following in **e()**:

Scalars
**e(N)** number of observations
**e(k)** number of parameters
**e(k_eq)** number of equations
**e(k_aux)** number of auxiliary parameters
**e(k_dv)** number of dependent variables
**e(Q)** criterion function
**e(J)** Hansen *J* chi-squared statistic
**e(J_df)** *J* statistic degrees of freedom
**e(N_clust)** number of clusters
**e(rank)** rank of **e(V)**
**e(ic)** number of iterations used by iterative GMM
estimator
**e(converged)** **1** if converged, **0** otherwise

Macros
**e(cmd)** **ivpoisson**
**e(cmdline)** command as typed
**e(depvar)** dependent variable of regression
**e(instd)** instrumented variable
**e(insts)** instruments
**e(wtype)** weight type
**e(wexp)** weight expression
**e(title)** title in estimation output
**e(clustvar)** name of cluster variable
**e(offset1)** offset variable for first equation
**e(winit)** initial weight matrix used
**e(winitname)** name of user-supplied initial weight matrix
**e(estimator)** **gmm** or **cfunction**
**e(additive)** **additive** if additive errors specified
**e(multiplicative)** **multiplicative** if multiplicative errors specified
**e(gmmestimator)** **onestep**, **twostep**, or **igmm**
**e(wmatrix)** *wmtype* specified in **wmatrix()**
**e(vce)** *vcetype* specified in **vce()**
**e(vcetype)** title used to label Std. Err.
**e(technique)** optimization technique
**e(properties)** **b V**
**e(estat_cmd)** program used to implement **estat**
**e(predict)** program used to implement **predict**
**e(footnote)** program used to implement footnote display
**e(marginsok)** predictions allowed by **margins**
**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(V)** variance-covariance matrix
**e(init)** initial values of the estimators
**e(Wuser)** user-supplied initial weight matrix
**e(W)** weight matrix used for final round of estimation
**e(S)** moment covariance matrix used in robust VCE
computations
**e(V_modelbased)** model-based variance

Functions
**e(sample)** marks estimation sample

__Reference__

Hall, A. R. 2005. *Generalized Method of Moments*. Oxford: Oxford
University Press.