https://github.com/cran/cobs
Tip revision: 4719166ac96865c6f3b3511be87177f70b244656 authored by Martin Maechler on 11 August 2010, 00:00:00 UTC
version 1.2-1
version 1.2-1
Tip revision: 4719166
conreg.Rd
\name{conreg}
\alias{conreg}
\title{Convex / Concave Regression}
\description{
Compute a univariate concave or convex regression, i.e.,
for given vectors, \eqn{x,y,w} in \eqn{R^n}, where \eqn{x} has to be
strictly sorted (\eqn{x_1 < x_2 < \ldots < x_n}), compute an
\eqn{n}-vector \eqn{m} minimizing the weighted sum of squares
\eqn{\sum_{i=1}^n {w_i (y_i - m_i)^2}}{sum(i=1..n; w_i * (y_i - m_i)^2)}
under the constraints
\deqn{(m_i - m_{i-1})/(x_i - x_{i-1}) \ge (m_{i+1} - m_i)/(x_{i+1} - x_i),}{%
(m[i] - m[i-1])/(x[i] - x[i-1]) >= (m[i+1] - m[i])/(x[i+1] - x[i]),}
for \eqn{1 \le i \le n}{1 <= i <= n} and
\eqn{m_0 := m_{n+1} := -\infty}{m[0] := m[n+1] := -Inf},
for concavity.
For convexity (\code{convex=TRUE}), replace \eqn{\ge}{>=} by
\eqn{\le}{<=} and \eqn{-\infty}{-Inf} by \eqn{+\infty}{+Inf}.
}
\usage{
conreg(x, y = NULL, w = NULL, convex = FALSE,
tol = 1e-07, maxit = c(200, 20), adjTol = TRUE, verbose = FALSE)
}
\arguments{
\item{x, y}{numeric vectors giving the values of the predictor and
response variable. Alternatively a single \dQuote{plotting}
structure (two-column matrix / y-values only / list, etc) can be
specified: see \code{\link{xy.coords}}.}
\item{w}{optional vector of weights of the same length as \code{x};
defaults to all 1.}
\item{convex}{logical indicating if convex or concave regression is desired.}
\item{tol}{convergence tolerance; do not make this too small!}
\item{maxit}{maximal number of (outer and inner) iterations of knot
selection.}
\item{adjTol}{logical indicating if the convergence test tolerance is
to be adjusted (increased) in some cases.}
\item{verbose}{logical indicating if knot placement iterations should
be \dQuote{reported}.}
}
\details{
The algorithm is an active-set method, needing some numerical
tolerance because of rounding errors in computation of finite
difference rations.
% ## TODO {this was 'matlab'}:
% ## --- dessen Zwischenschritte auch graphisch illustriert werden.
}
\value{
an object of class \code{conreg} which is basically a list with components
\item{x}{sorted (and possibly aggregated) abscissa values \code{x}.}
\item{y}{corresponding y values.}
\item{yf}{corresponding fitted values.}
\item{iKnots}{integer vector giving indices of the \emph{knots},
i.e. locations where the fitted curve has kinks.
Formally, these are exactly those indices where the constraint is
fulfilled strictly, i.e., those \eqn{i} where
\deqn{(m_i - m_{i-1})/(x_i-x_{i-1}) > (m_{i+1} - m_i)/(x_{i+1}-x_i).}{%
(m[i] - m[i-1])/(x[i] - x[i-1]) > (m[i+1] - m[i])/(x[i+1] - x[i]).}
}
\item{call}{the \code{\link{call}} to \code{conreg()} used.}
\item{..}{... FIXME ...}
\item{..}{... FIXME ...}
Note that there are several methods defined for \code{conreg} objects,
see \code{\link{predict.conreg}}.
Notably \code{print} and \code{plot}; also
\code{\link{predict}}, \code{\link{residuals}}, \code{\link{fitted}},
\code{\link{knots}}.
}
%\references{ ~put references to the literature/web site here ~ }
\author{Lutz Duembgen programmed the original Matlab code in July 2006;
Martin Maechler ported it to \R, tested, catch infinite loops, added
more options, improved tolerance, etc; from April 27, 2007.
% Ported to R and enhanced:
% - work for unordered, even duplicated 'x'
% - made slightly faster; more options;
% - detect infinite loop; auto-adjust tol;
% - changed tol (prec) to 1e-7
% - new arg. convex == FALSE <==> concave == TRUE
% - define "class" and many methods, plot, predict, ...
%
% Martin Maechler, 27.-28. Apr 2007
}
\seealso{\code{\link[stats]{isoreg}} for isotone (monotone) regression;
CRAN packages \pkg{ftnonpar}, \pkg{cobs}, \pkg{logcondens}.
}
\examples{
## Generated data :
N <- 100
f <- function(X) 4*X*(1 - X)
xx <- seq(0,1, length=501)# for plotting true f()
set.seed(1)
x <- sort(runif(N))
y <- f(x) + 0.2 * rnorm(N)
plot(x,y, cex = 0.6)
lines(xx, f(xx), col = "blue", lty=2)
rc <- conreg(x,y)
lines(rc, col = 2)
title("Concave Regression in R")
## Trivial cases work too:
r.1 <- conreg(1,7)
r.2 <- conreg(1:2,7:6)
r.3 <- conreg(1:3,c(4:5,1))
r.3. <- conreg(1:3,c(4:5,8))
stopifnot(resid(r.1) == 0,
resid(r.2) == 0,
resid(r.3) == 0,
all.equal(fitted(r.3.),
c(11,17,23)/3, tol=1e-12))
}
\keyword{regression}
\keyword{smooth}