\HeaderA{polr}{Ordered Logistic or Probit Regression}{polr}
\keyword{models}{polr}
\begin{Description}\relax
Fits a logistic or probit regression model to an ordered factor
response.  The default logistic case is \emph{proportional odds
logistic regression}, after which the function is named.
\end{Description}
\begin{Usage}
\begin{verbatim}
polr(formula, data, weights, start, ..., subset, na.action,
     contrasts = NULL, Hess = FALSE, model = TRUE,
     method = c("logistic", "probit", "cloglog", "cauchit"))
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{formula}] a formula expression as for regression models, of the form
\code{response \textasciitilde{} predictors}. The response should be a factor
(preferably an ordered factor), which will be interpreted as an
ordinal response, with levels ordered as in the factor.  
The model must have an intercept: attempts to remove one will
lead to a warning and be ignored.  An offset may be used.  See the
documentation of \code{\LinkA{formula}{formula}} for other details.

\item[\code{data}] an optional data frame in which to interpret the variables occurring
in \code{formula}.

\item[\code{weights}] optional case weights in fitting.  Default to 1.

\item[\code{start}] initial values for the parameters.  This is in the format
\code{c(coefficients, zeta)}: see the Values section.

\item[\code{...}] additional arguments to be passed to \code{\LinkA{optim}{optim}}, most often a
\code{control} argument.

\item[\code{subset}] expression saying which subset of the rows of the data should  be used
in the fit.  All observations are included by default.

\item[\code{na.action}] a function to filter missing data.

\item[\code{contrasts}] a list of contrasts to be used for some or all of
the factors appearing as variables in the model formula.

\item[\code{Hess}] logical for whether the Hessian (the observed information matrix)
should be returned.  Use this if you intend to call \code{summary} or
\code{vcov} on the fit.

\item[\code{model}] logical for whether the model matrix should be returned.

\item[\code{method}] logistic or probit or complementary log-log or cauchit (corresponding
to a Cauchy latent variable).

\end{ldescription}
\end{Arguments}
\begin{Details}\relax
This model is what Agresti (2002) calls a \emph{cumulative link}
model.  The basic interpretation is as a \emph{coarsened} version of a
latent variable \eqn{Y_i}{} which has a logistic or normal or
extreme-value or Cauchy distribution
with scale parameter one and a linear model for the mean.  The ordered
factor which is observed is which bin \eqn{Y_i}{} falls into with
breakpoints
\deqn{\zeta_0 = -\infty < \zeta_1 < \cdots < \zeta_K = \infty}{zeta_0 = -Inf < zeta_1 < \dots < zeta_K = Inf}
This leads to the model
\deqn{\mbox{logit} P(Y \le k | x) = \zeta_k - \eta}{logit P(Y <= k | x) = zeta_k - eta}
with \emph{logit} replaced by \emph{probit} for a normal latent
variable, and \eqn{\eta}{eta} being the linear predictor, a linear
function of the explanatory variables (with no intercept).  Note
that it is quite common for other software to use the opposite sign
for \eqn{\eta}{} (and hence the coefficients \code{beta}).

In the logistic case, the left-hand side of the last display is the
log odds of category \eqn{k}{} or less, and since these are log odds
which differ only by a constant for different \eqn{k}{}, the odds are
proportional.  Hence the term \emph{proportional odds logistic
regression}.

In the complementary log-log case, we have a \emph{proportional
hazards} model for grouped survival times.

There are methods for the standard model-fitting functions, including
\code{\LinkA{predict}{predict}}, \code{\LinkA{summary}{summary}}, \code{\LinkA{vcov}{vcov}},
\code{\LinkA{anova}{anova}}, \code{\LinkA{model.frame}{model.frame}} and an
\code{extractAIC} method for use with \code{\LinkA{stepAIC}{stepAIC}}.  There
are also \code{\LinkA{profile}{profile}} and \code{\LinkA{confint}{confint}} methods.
\end{Details}
\begin{Value}
A object of class \code{"polr"}.  This has components

\begin{ldescription}
\item[\code{coefficients}] the coefficients of the linear predictor, which has no
intercept.
\item[\code{zeta}] the intercepts for the class boundaries.
\item[\code{deviance}] the residual deviance.
\item[\code{fitted.values}] a matrix, with a column for each level of the response.
\item[\code{lev}] the names of the response levels.
\item[\code{terms}] the \code{terms} structure describing the model.
\item[\code{df.residual}] the number of residual degrees of freedoms,
calculated using the weights.
\item[\code{edf}] the (effective) number of degrees of freedom used by the model
\item[\code{n, nobs}] the (effective) number of observations, calculated using the
weights. (\code{nobs} is for use by \code{\LinkA{stepAIC}{stepAIC}}.
\item[\code{call}] the matched call.
\item[\code{method}] the matched method used.
\item[\code{convergence}] the convergence code returned by \code{optim}.
\item[\code{niter}] the number of function and gradient evaluations used by
\code{optim}.
\item[\code{Hessian}] (if \code{Hess} is true).
\item[\code{model}] (if \code{model} is true).
\end{ldescription}
\end{Value}
\begin{References}\relax
Agresti, A. (2002) \emph{Categorical Data.} Second edition.  Wiley.

Venables, W. N. and Ripley, B. D. (2002)
\emph{Modern Applied Statistics with S.} Fourth edition.  Springer.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{optim}{optim}}, \code{\LinkA{glm}{glm}}, \code{\LinkA{multinom}{multinom}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
options(contrasts = c("contr.treatment", "contr.poly"))
house.plr <- polr(Sat ~ Infl + Type + Cont, weights = Freq, data = housing)
house.plr
summary(house.plr)
## slightly worse fit from
summary(update(house.plr, method = "probit"))
## although it is not really appropriate, can fit
summary(update(house.plr, method = "cloglog"))

predict(house.plr, housing, type = "p")
addterm(house.plr, ~.^2, test = "Chisq")
house.plr2 <- stepAIC(house.plr, ~.^2)
house.plr2$anova
anova(house.plr, house.plr2)

house.plr <- update(house.plr, Hess=TRUE)
pr <- profile(house.plr)
confint(pr)
plot(pr)
pairs(pr)
\end{ExampleCode}
\end{Examples}

