1\name{amlpoisson}
2\alias{amlpoisson}
3%- Also NEED an '\alias' for EACH other topic documented here.
4\title{ Poisson Regression by Asymmetric Maximum Likelihood Estimation }
5\description{
6  Poisson quantile regression estimated by maximizing an
7  asymmetric likelihood function.
8
9}
10\usage{
11amlpoisson(w.aml = 1, parallel = FALSE, imethod = 1, digw = 4,
12           link = "loglink")
13}
14%- maybe also 'usage' for other objects documented here.
15\arguments{
16
17  \item{w.aml}{
18  Numeric, a vector of positive constants controlling the percentiles.
19  The larger the value the larger the fitted percentile value
20  (the proportion of points below the ``w-regression plane'').
21  The default value of unity results in the ordinary maximum likelihood
22  (MLE) solution.
23
24  }
25  \item{parallel}{
26  If \code{w.aml} has more than one value then
27  this argument allows the quantile curves to differ by the same amount
28  as a function of the covariates.
29  Setting this to be \code{TRUE} should force the quantile curves to
30  not cross (although they may not cross anyway).
31  See \code{\link{CommonVGAMffArguments}} for more information.
32
33  }
34  \item{imethod}{
35  Integer, either 1 or 2 or 3. Initialization method.
36  Choose another value if convergence fails.
37
38  }
39  \item{digw }{
40  Passed into \code{\link[base]{Round}} as the \code{digits} argument
41  for the \code{w.aml} values;
42  used cosmetically for labelling.
43
44  }
45  \item{link}{
46  See \code{\link{poissonff}}.
47
48  }
49}
50\details{
51  This method was proposed by Efron (1992) and full details can
52  be obtained there.
53% Equation numbers below refer to that article.
54  The model is essentially a Poisson regression model
55  (see \code{\link{poissonff}}) but the usual deviance is replaced by an
56  asymmetric squared error loss function; it is multiplied by
57  \eqn{w.aml} for positive residuals.
58  The solution is the set of regression coefficients that minimize the
59  sum of these deviance-type values over the data set, weighted by
60  the \code{weights} argument (so that it can contain frequencies).
61  Newton-Raphson estimation is used here.
62
63}
64\value{
65  An object of class \code{"vglmff"} (see \code{\link{vglmff-class}}).
66  The object is used by modelling functions such as \code{\link{vglm}}
67  and \code{\link{vgam}}.
68
69
70}
71\references{
72  Efron, B. (1991).
73  Regression percentiles using asymmetric squared error loss.
74  \emph{Statistica Sinica},
75  \bold{1}, 93--125.
76
77  Efron, B. (1992).
78  Poisson overdispersion estimates based on the method of
79  asymmetric maximum likelihood.
80  \emph{Journal of the American Statistical Association},
81  \bold{87}, 98--107.
82
83  Koenker, R. and Bassett, G. (1978).
84  Regression quantiles.
85  \emph{Econometrica},
86  \bold{46}, 33--50.
87
88  Newey, W. K. and Powell, J. L. (1987).
89  Asymmetric least squares estimation and testing.
90  \emph{Econometrica},
91  \bold{55}, 819--847.
92
93}
94
95\author{ Thomas W. Yee }
96\note{
97  On fitting, the \code{extra} slot has list components \code{"w.aml"}
98  and \code{"percentile"}. The latter is the percent of observations
99  below the ``w-regression plane'', which is the fitted values.  Also,
100  the individual deviance values corresponding to each element of the
101  argument \code{w.aml} is stored in the \code{extra} slot.
102
103
104  For \code{amlpoisson} objects, methods functions for the generic
105  functions \code{qtplot} and \code{cdf} have not been written yet.
106
107
108  About the jargon, Newey and Powell (1987) used the name
109  \emph{expectiles} for regression surfaces obtained by asymmetric
110  least squares.
111  This was deliberate so as to distinguish them from the original
112  \emph{regression quantiles} of Koenker and Bassett (1978).
113  Efron (1991) and Efron (1992) use the general name
114  \emph{regression percentile} to apply to all forms of asymmetric
115  fitting.
116  Although the asymmetric maximum likelihood method very nearly gives
117  regression percentiles in the strictest sense for the normal and
118  Poisson cases, the phrase \emph{quantile regression} is used loosely
119  in this \pkg{VGAM} documentation.
120
121
122  In this documentation the word \emph{quantile} can often be
123  interchangeably replaced by \emph{expectile}
124  (things are informal here).
125
126
127}
128
129\section{Warning }{
130  If \code{w.aml} has more than one value then the value returned by
131  \code{deviance} is the sum of all the (weighted) deviances taken over
132  all the \code{w.aml} values.
133  See Equation (1.6) of Efron (1992).
134
135}
136\seealso{
137  \code{\link{amlnormal}},
138  \code{\link{amlbinomial}},
139  \code{\link{extlogF1}},
140  \code{\link{alaplace1}}.
141
142}
143
144\examples{
145set.seed(1234)
146mydat <- data.frame(x = sort(runif(nn <- 200)))
147mydat <- transform(mydat, y = rpois(nn, exp(0 - sin(8*x))))
148(fit <- vgam(y ~ s(x), fam = amlpoisson(w.aml = c(0.02, 0.2, 1, 5, 50)),
149             mydat, trace = TRUE))
150fit@extra
151
152\dontrun{
153# Quantile plot
154with(mydat, plot(x, jitter(y), col = "blue", las = 1, main =
155     paste(paste(round(fit@extra$percentile, digits = 1), collapse = ", "),
156           "percentile-expectile curves")))
157with(mydat, matlines(x, fitted(fit), lwd = 2)) }
158}
159\keyword{models}
160\keyword{regression}
161
162