\HeaderA{isoreg}{Isotonic / Monotone Regression}{isoreg}
\keyword{regression}{isoreg}
\keyword{smooth}{isoreg}
\begin{Description}\relax
Compute the isotonic (monotonely increasing nonparametric) least
squares regression which is piecewise constant.
\end{Description}
\begin{Usage}
\begin{verbatim}
isoreg(x, y = NULL)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x, y}] coordinate vectors of the regression points.  Alternatively a single
plotting structure can be specified: see \code{\LinkA{xy.coords}{xy.coords}}.

\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The algorithm determines the convex minorant \eqn{m(x)}{} of the
\emph{cumulative} data (i.e., \code{cumsum(y)}) which is piecewise
linear and the result is \eqn{m'(x)}{}, a step function with level
changes at locations where the convex \eqn{m(x)}{} touches the
cumulative data polygon and changes slope.\\
\code{\LinkA{as.stepfun}{as.stepfun}()} returns a \code{\LinkA{stepfun}{stepfun}}
object which can be more parsimonious.
\end{Details}
\begin{Value}
\code{isoreg()} returns an object of class \code{isoreg} which is
basically a list with components
\begin{ldescription}
\item[\code{x}] original (constructed) abscissa values \code{x}.
\item[\code{y}] corresponding y values.
\item[\code{yf}] fitted values corresponding to \emph{ordered} x values.
\item[\code{yc}] cumulative y values corresponding to \emph{ordered} x values.
\item[\code{iKnots}] integer vector giving indices where the fitted curve jumps,
i.e., where the convex minorant has kinks.
\item[\code{isOrd}] logical indicating if original x values were ordered
increasingly already.
\item[\code{ord}] \code{if(!isOrd)}: integer permutation \code{\LinkA{order}{order}(x)} of
\emph{original} \code{x}.
\item[\code{call}] the \code{\LinkA{call}{call}} to \code{isoreg()} used.
\end{ldescription}
\end{Value}
\begin{Note}\relax
The code should be improved to accept \emph{weights} additionally and
solve the corresponding weighted least squares problem.\\
\sQuote{Patches are welcome!}
\end{Note}
\begin{References}\relax
Barlow, R. E., Bartholomew, D. J., Bremner, J. M., and Brunk, H. D. (1972)
\emph{Statistical inference under order restrictions}; Wiley, London.

Robertson, T., Wright,F. T. and Dykstra, R. L. (1988)
\emph{Order Restricted Statistical Inference}; Wiley, New York.
\end{References}
\begin{SeeAlso}\relax
the plotting method \code{\LinkA{plot.isoreg}{plot.isoreg}} with more examples;
\code{\LinkA{isoMDS}{isoMDS}()} from the \pkg{MASS} package internally
uses isotonic regression.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
require(graphics)

(ir <- isoreg(c(1,0,4,3,3,5,4,2,0)))
plot(ir, plot.type = "row")

(ir3 <- isoreg(y3 <- c(1,0,4,3,3,5,4,2, 3)))# last "3", not "0"
(fi3 <- as.stepfun(ir3))
(ir4 <- isoreg(1:10, y4 <- c(5, 9, 1:2, 5:8, 3, 8)))
cat(sprintf("R^2 = %.2f\n",
            1 - sum(residuals(ir4)^2) / ((10-1)*var(y4))))

## If you are interested in the knots alone :
with(ir4, cbind(iKnots, yf[iKnots]))

## Example of unordered x[] with ties:
x <- sample((0:30)/8)
y <- exp(x)
x. <- round(x) # ties!
plot(m <- isoreg(x., y))
stopifnot(all.equal(with(m, yf[iKnots]),
                    as.vector(tapply(y, x., mean))))
\end{ExampleCode}
\end{Examples}

