% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/poisson-fit.R
\name{ml_poisson}
\alias{ml_poisson}
\title{Fit Poisson model by Maximum Likelihood}
\usage{
ml_poisson(
  value,
  weights = NULL,
  data,
  subset = NULL,
  noint_value = FALSE,
  constraints = NULL,
  start = NULL,
  method = "NR",
  control = NULL,
  ...
)
}
\arguments{
\item{value}{Formula for the conditional mean (value) equation.}

\item{weights}{Optional weights variable. It can be either the name of the
variable in \code{data}, or a vector with the weights.}

\item{data}{Data frame.}

\item{subset}{Optional subset expression. Only observations for which this
expression evaluates to \code{TRUE} are used in the estimation. This can be
a logical vector or an expression (e.g. \code{subset = age > 30}).}

\item{noint_value}{Logical. Should the value equation omit the intercept?
Default is \code{FALSE}.}

\item{constraints}{Optional constraints on the parameters. Can be a character
vector of string constraints, a named list of string constraints, or a raw
maxLik constraints list. See \strong{Details}.}

\item{start}{Numeric vector of starting values for the coefficients. Required
if constraints are being supplied. If supplied without constraints they
will be ignored. See \strong{Details}.}

\item{method}{A string with the method used for optimization. See
\link[maxLik:maxLik]{maxLik} for options, and see \strong{Details}.}

\item{control}{A list of control parameters passed to \link[maxLik:maxLik]{maxLik}.
If \code{NULL} (default), a sensible set of options is chosen automatically
depending on whether constraints are used. See \link[maxLik:maxControl]{maxControl}.}

\item{...}{Additional arguments passed to \link[maxLik:maxLik]{maxLik}.}
}
\value{
An object of class \code{ml_poisson} that extends \code{mlmodel.count} and \code{mlmodel}.
}
\description{
Fit Poisson model by Maximum Likelihood
}
\details{
\strong{Important:} Do not use the usual R syntax to remove the intercept in the
formula (\code{- 1} or \code{+ 0}) for the value equation. Use the dedicated
argument \code{noint_value} instead.

Coefficient names in the fitted object use the prefixes \verb{value::}. This is for
consistency with other \code{mlmodel} estimators that model the scale (dispersion)
as well.

Either inequality or equality linear constraints are accepted, but not both.
A constraint cannot have a linear combination of more than two coefficients.

\strong{Important}: When \code{constraints} are supplied, \code{start} cannot be \code{NULL}.
You \strong{must} provide initial values that yield a feasible log-likelihood.
If no constraints are used, any supplied \code{start} is ignored.

When constraints are used, \code{ml_lm} automatically chooses the optimizer:
\itemize{
\item Equality constraints => Nelder-Mead (\code{"NM"})
\item Inequality constraints => BFGS (\code{"BFGS"})
}

In these cases your supplied \code{method} argument (if any) is ignored.

The Poisson model assumes equidispersion (mean = variance).
When the data show overdispersion (as is common), consider using
\link{ml_negbin} instead.
}
\examples{

# Poisson model
data(docvis)
fit_pois <- ml_poisson(docvis ~ age + educyr + totchr, 
                       data = docvis)

summary(fit_pois, vcov.type = "robust")

# Different predict types
head(predict(fit_pois, type = "response")$fit)   # Expected count
head(predict(fit_pois, type = "P(2,)")$fit)      # Probability of at least 2
head(predict(fit_pois, type = "P(3)")$fit)       # Probability of exactly 3

# Fitted values and residuals
head(fitted(fit_pois))
head(residuals(fit_pois))
head(residuals(fit_pois, type = "pearson"))

}
\seealso{
\link{ml_negbin}
}
\author{
Alfonso Sanchez-Penalver
}
