isoreg                 package:stats                 R Documentation

Isotonic / Monotone Regression

Description:

     Compute the isotonic (monotonely increasing nonparametric) least
     squares regression which is piecewise constant.

Usage:

     isoreg(x, y = NULL)

Arguments:

    x, y: coordinate vectors of the regression points.  Alternatively a
          single plotting structure can be specified: see 'xy.coords'. 

Details:

     The algorithm determines the convex minorant m(x) of the
     _cumulative_ data (i.e., 'cumsum(y)') which is piecewise linear
     and the result is m'(x), a step function with level changes at
     locations where the convex m(x) touches the cumulative data
     polygon and changes slope.
      'as.stepfun()' returns a 'stepfun' object which can be more
     parsimonious.

Value:

     'isoreg()' returns an object of class 'isoreg' which is basically
     a list with components 

       x: original (constructed) abscissa values 'x'.

       y: corresponding y values.

      yf: fitted values corresponding to _ordered_ x values.

      yc: cumulative y values corresponding to _ordered_ x values.

  iKnots: integer vector giving indices where the fitted curve jumps,
          i.e., where the convex minorant has kinks.

   isOrd: logical indicating if original x values were ordered
          increasingly already.

     ord: 'if(!isOrd)': integer permutation 'order(x)' of _original_
          'x'.

    call: the 'call' to 'isoreg()' used.

Note:

     The code should be improved to accept _weights_ additionally and
     solve the corresponding weighted least squares problem.
      'Patches are welcome!'

References:

     Barlow, R. E., Bartholomew, D. J., Bremner, J. M., and Brunk, H.
     D. (1972) _Statistical inference under order restrictions_; Wiley,
     London.

     Robertson, T., Wright,F. T. and Dykstra, R. L. (1988) _Order
     Restricted Statistical Inference_; Wiley, New York.

See Also:

     the plotting method 'plot.isoreg' with more examples; 'isoMDS()'
     from the 'MASS' package internally uses isotonic regression.

Examples:

     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))))

