*! version 2.2.2 - 20 October 2015
help ppml

Title

ppml -- Poisson pseudo maximum likelihood

Syntax

ppml
depvar
indepvars
[if] [in]
[weight]
[, options]

strict selects the method to exclude regressors that may cause convergence problems

keep keeps the observations that would be perfectly predicted by excluded regressors

checkonly checks for the presence of regressors that may cause convergence problems but does
not perform the estimation

noconstant suppress constant term

offset(varname) include varname in model with coefficient constrained to 1

cluster(clustvar) specifies that the standard errors allow for intragroup correlation

technique(algorithm_spec) maximization technique

mu(varname) use varname as the initial estimate for the mean of depvar

maximize_options control the maximization process

fweights, aweights, iweights, and pweights are allowed; see weight.

See [R] glm postestimation for features available after estimation.

Description

ppml estimates Poisson regression by pseudo maximum likelihood. It differs from [R] poisson
because it uses the method of Santos Silva and Tenreyro (2010) to identify and drop regressors that may
cause the non-existence of the (pseudo) maximum likelihood estimates. Notice that the user should carefully
check whether the specification resulting from dropping the problematic regressors is interesting. If any of
the regressors that are dropped is a dummy variable, by default ppml will drop the observations with
the less frequent value of the excluded dummy. This is done to prevent the observations identified by the
dropped dummy from being treated as part of the base category. (This procedure can be overridden with the
option keep.) The user should ensure that this procedure is appropriate and should consider alternatives
such as dropping the entire set of dummies, or recoding the variable in fewer categories. Because ppml does
not check for the presence of problematic regressors after dropping these observations, there may be rare cases
in which ppml tries to find estimates that actually do not exist. In these situations the estimation
procedure will not converge, or convergence is spurious. In the latter case, ppml issues a warning that
the model is overfitting the observations with depvar=0. ppml also issues a warning if the dependent
variable or any of the regressors has large values that are likely to cause numerical problems and lead to
convergence difficulties. Once the subset of regressors and observations to be used is defined, ppml uses
the [R] glm command to perform the estimation. Therefore, ppml shares many characteristics of the
glm command, including its limitations.

Options

strict by default ppml uses a conservative method to exclude regressors that may cause convergence
problems. The strict option forces the exclusion of all variables that are potentially problematic. The
strict option should be used with great caution.

keep if any of the regressors that are dropped to ensure the existence of the estimates is a dummy
variable, by default ppml will drop the observations with the less frequent value of the excluded
dummy. The option keep overrides this and does not drop any observation

checkonly with this option, ppml checks for the presence of regressors that may cause convergence
problems but does not perform the estimation. The list of regressors that do not cause convergence problems and
the list of regressors that do are saved in e(included) and e(excluded). The observations that can be used
in the estimation are saved in e(sample). This option can be useful to detect and solve convergence issues with
other commands for limited dependent variables, such as nbreg and tobit; see examples below.

noconstant suppresses the constant term (intercept) in the model. This option should be used with great
caution, but can be useful in some rare cases (e.g., if one wants to estimate models where the coefficients satisfy
certain linear restrictions).

offset(varname) specifies that varname be included in the model with the coefficient constrained to be 1.

cluster(clustvar) by default ppml computes heteroskedasticity robust standard errors. The cluster(clustvar)
option specifies that the standard errors also allow for intragroup correlation, relaxing the usual
requirement that the observations be independent. That is, the observations are independent across groups
(clusters) but not necessarily within groups. clustvar specifies to which group each observation
belongs; clustvar can be a string variable. cluster(clustvar) affects the standard errors
and variance-covariance matrix of the estimators but not the estimated coefficients; see .

technique(algorithm_spec) specifies how the objective function is to be maximized. The following
algorithms are allowed:

technique(irls) specifies the irls algorithm used by [R] glm. This is the default option
because this method appears to be more robust to numerical problems than the alternative options.

technique(nr) specifies Stata's modified Newton-Raphson (NR) algorithm.

technique(bhhh) specifies the Berndt-Hall-Hall-Hausman (BHHH) algorithm.

technique(dfp) specifies the Davidon-Fletcher-Powell (DFP) algorithm.

technique(bfgs) specifies the Broyden-Fletcher-Goldfarb-Shanno
(BFGS) algorithm.

mu(varname) specifies varname as the initial estimate for the mean of depvar. This option
can be used only with default option technique(irls) and can be useful with models that
experience convergence difficulties.

maximize_options:
iterate(#),
trace,
search,
difficult,
gradient,
showstep,
hessian,
fisher(#),
showtolerance,
tolerance(#),
ltolerance(#),
nrtolerance(#),
nonrtolerance,
from(init_specs); see [R] maximize and [R] glm. Notes: Only the first two options can
be used with technique(irls); When other techniques are used, the option difficult is
highly recommended.

Remarks

ppml is not an official Stata command and was written by J.M.C. Santos Silva & Silvana Tenreyro.
We are greatful to Markus Baldauf for the help in developing this code. For further help and support,
please contact jmcss@surrey.ac.uk. Please notice that this software is provided as is, without warranty
of any kind, express or implied, including but not limited to the warranties of merchantability, fitness
for a particular purpose and noninfringement. In no event shall the authors be liable for any claim, damages
or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in
connection with the software or the use or other dealings in the software.

Examples

Setup

. use http://personal.lse.ac.uk/tenreyro/mock

ppml estimation (the dummy z is correctly dropped, the observations with z=1 are also dropped)

. ppml y x w z

ppml estimation with the keep option (the dummy z is correctly dropped but no observations are dropped; this is equivalent to not conditioning on z)

. ppml y x w z, k

ppml estimation (v is correctly dropped, no observations are dropped because v is not a dummy)

. ppml y x w v

ppml estimation with the strict option (w will be incorrectly dropped)

. ppml y x w z v, st

ppml with the checkonly option is used to solve convergence problems with nbreg (the dummy
z is correctly dropped, the observations with z=1 are also dropped)

. ppml y x z, check

. nbreg y `e(included)' if e(sample)==1

ppml with the checkonly option is used to solve convergence problems with tobit (the dummy
z is correctly dropped, the observations with z=1 are also dropped)

. ppml y x z, check

. tobit y `e(included)' if e(sample)==1, ll(0)

Saved results

By default, or with the option technique(irls), ppml saves the following output
in e() (see glm for further details):

Scalars

e(N) number of observations

e(k) number of parameters

e(k_omitted) number of variables omitted due to collinearity

e(k_excluded) number of variables excluded

e(k_eq_model) number of equations in model Wald test

e(df_m) model degrees of freedom

e(df) residual degrees of freedom

e(phi) scale parameter

e(disp) dispersion parameter

e(bic) model BIC

e(ll) log likelihood

e(r2) R-squared, computed as the square of the correlation between the dependent variable and its fitted values

e(N_clust) number of clusters

e(deviance) deviance

e(deviance_s) scaled deviance

e(deviance_p) Pearson deviance

e(deviance_ps) scaled Pearson deviance

e(dispers) dispersion

e(dispers_s) scaled dispersion

e(dispers_p) Pearson dispersion

e(dispers_ps) scaled Pearson dispersion

e(nbml) 1 if negative binomial parameter estimated via ML,
0 otherwise

e(vf) factor set by vfactor(), 1 if not set

e(power) power set by power(), opower()

e(rank) rank of e(V)

e(rc) return code

Macros

e(cmd) ppml

e(cmdline) command as typed

e(depvar) name of dependent variable

e(varfunc) name of variance function used

e(varfunct) Poisson

e(varfuncf) variance function

e(link) name of link function used

e(linkt) link title

e(linkf) link form

e(m) number of binomial trials

e(wtype) weight type

e(wexp) weight expression

e(clustvar) name of cluster variable

e(hac_lag) HAC lag

e(vce) vcetype specified in vce()

e(vcetype) title used to label Std. Err.

e(opt) irls

e(opt1) optimization title, line 1

e(opt2) optimization title, line 2

e(crittype) optimization criterion

e(properties) b V

e(predict) program used to implement predict

e(marginsnotok) predictions disallowed by margins

e(included) list of included regressors

e(excluded) list of excluded regressors

Matrices

e(b) coefficient vector

e(V) variance-covariance matrix of the estimators

e(V_modelbased) model-based variance

Functions

e(sample) marks estimation sample

For other choices of estimation algorithm, ppml saves the following output
in e() (see glm for further details):

Scalars

e(N) number of observations

e(k) number of parameters

e(k_omitted) number of variables omitted due to collinearity

e(k_excluded) number of variables excluded

e(k_eq) number of equations in e(b)

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(df) residual degrees of freedom

e(phi) scale parameter

e(aic) model AIC

e(bic) model BIC

e(ll) log likelihood

e(r2) R-squared, computed as the square of the correlation between the dependent variable and its fitted values

e(N_clust) number of clusters

e(chi2) chi-squared

e(p) significance

e(deviance) deviance

e(deviance_s) scaled deviance

e(deviance_p) Pearson deviance

e(deviance_ps) scaled Pearson deviance

e(dispers) dispersion

e(dispers_s) scaled dispersion

e(dispers_p) Pearson dispersion

e(dispers_ps) scaled Pearson dispersion

e(nbml) 1 if negative binomial parameter estimated via ML,
0 otherwise

e(vf) factor set by vfactor(), 1 if not set

e(power) power set by power(), opower()

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) ppml

e(cmdline) command as typed

e(depvar) name of dependent variable

e(varfunc) name of variance function used

e(varfunct) Poisson

e(varfuncf) variance function

e(link) name of link function used

e(linkt) link title

e(linkf) link form

e(m) number of binomial trials

e(wtype) weight type

e(wexp) weight expression

e(title) title in estimation output

e(clustvar) name of cluster variable

e(chi2type) Wald or LR; type of model chi-squared
test

e(hac_kernel) HAC kernel

e(vce) vcetype specified in vce()

e(vcetype) title used to label Std. Err.

e(opt) ml or irls

e(opt1) optimization title, line 1

e(opt2) optimization title, line 2

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(marginsnotok) predictions disallowed by margins

e(included) list of included regressors

e(excluded) list of excluded regressors

Matrices

e(b) coefficient vector

e(ilog) iteration log (up to 20 iterations)

e(gradient) gradient vector

e(V) variance-covariance matrix of the estimators

e(V_modelbased) model-based variance

Functions

e(sample) marks estimation sample

When the option checkonly is used, ppml only saves the following output
in e():

Scalars

e(N) number of observations

e(k) number of variables kept (including the intercept, if there is one)

e(k_omitted) number of variables omitted due to collinearity

e(k_excluded) number of variables excluded

Macros

e(cmd) ppml

e(included) list of included regressors

e(excluded) list of excluded regressors

Functions

e(sample) marks estimation sample

Reference

Santos Silva, J.M.C. and Tenreyro, Silvana (2010), "On the Existence of the Maximum Likelihood Estimates in Poisson Regression," Economics Letters,
107(2), pp. 310-312.

Also see

Manual: [R] glm [R] poisson

Last modified on 20 October 2015