.-
help for ^rpoisson^                                               (STB-46: sg98)
.-



Poisson regression with random effects
--------------------------------------

^rpoisson^ [varlist] [^if^ exp] [^in^ range] [ ^,^ ^e^xposure^(^varname^)^ 
      ^m^ethod^(^ { ^ml^ | ^pe^ | ^ps^ | ^fi^ } ^)^ ^fv^ar^(^#^) cl^uster^(^varlist^)^
      ^r^obust ^l^evel^(^#^) nol^og ^ir^r]


Description
-----------

^rpoisson^ fits a log-linear poisson regression model with random
effects ("frailties"). The model is assumed to apply to the rates
obtained by dividing the expected value of an event count by a rate
denominator (such as the "person-years" of observation, or "exposure").
Frailties are random rate multipliers, assumed to be drawn from a 
gamma distribution with unit mean and unknown variance. The ^cluster^
option defines subgroups all members of which  share the same frailty.
If this option is not specified, frailty is  assumed to operate at the
level of the individual unit and the model becomes the same as the
negative binomial model for overdispersed counts (see [R] nbreg, [R]
glm).

As usual for regression commands, the variable list should start with
the dependent variable (the event count), followed by the explanatory
variables. 

Optionally, Huber's formula (the "information sandwich") may be used to 
compute robust estimates of standard errors of the regression coefficients. 
This option need not be invoked in the first call to ^rpoisson^, but may be 
specified in a later call (without a varlist).

The program works by alternating between maximum likelihood estimation of
regression coefficients for fixed frailty variance, and estimation of frailty
variance for fixed regression coefficients. Several methods of estimation of
the frailty variance are provided for: maximum likelihood, maximum pseudo-
likelihood, and by a "posterior expectation" method. Alternatively the
frailty variance may be fixed to a known constant. This latter option is 
useful when comparing deviances of different regression  models.


Options
-------

^exposure(^varname^)^ supplies the variable which contains the rate 
denominators.

^cluster(^varlist^)^ defines the groups of observations which share the
same frailty.

^robust^ specifies that robust standard errors are to be calculated for
the regression coefficients (see [U] 26.10 Obtaining robust variance
estimates). When the model is first fitted, the usual model-based
standard errors are listed also.

^irr^ specifies that regression coefficients are to be displayed in their
exponentiated form, as rate-ratios.

^method(ml^|^pe^|^ps^|^fi)^ specifies the method used to estimate frailty variance:
   ^ml^ - maximum likelihood
   ^pe^ - posterior expectation method
   ^ps^ - maximum pseudo-likelihood
   ^fi^ - frailty variance is fixed

^fvar(^#^)^ provides either a fixed value or an initial estimate of the 
frailty variance. An initial estimateThis will usually only be needed if 
difficulty is experienced obtaining convergence of the iterations.

^level(^#^)^ gives the level for the confidence intervals (default 95).

^nolog^ turns off the iteration log

Note that ^robust^ and ^irr^ may be invoked when "replaying" a previously
fitted model. However, once ^robust^ has been used, the robust standard
errors will remain in force for all subsequent replays and for carrying
out Wald tests using ^testparm^.


Examples
--------

  . ^rpoisson d x1 x2, e(y) cl(id) m(ml)^ - full ml, observations grouped by ^id^

  . ^rpoisson , ir^                       - display coefficients as rate ratios

  . ^rpoisson , ro ir^                    - calculate robust confidence intervals


Author
------

       David Clayton
       MRC Biostatistical Unit, Cambridge
       david.clayton@@mrc-bsu.cam.ac.uk


Also see
--------

    STB:  sg98 (STB-46)
 Manual:  ^[R] glm^, ^[R] nbreg^
          ^[U] 26.10 Obtaining robust variance estimates^