\Header{smooth}{Median Smoothing}
\alias{print.tukeysmooth}{smooth}
\alias{summary.tukeysmooth}{smooth}
\keyword{robust}{smooth}
\keyword{smooth}{smooth}
\begin{Description}\relax
Tukey's smoothers, \emph{3RS3R}, \emph{3RSS}, \emph{3R}, etc.\end{Description}
\begin{Usage}
\begin{verbatim}
smooth(x, kind = c("3RS3R", "3RSS", "3RSR", "3R", "3", "S"), 
       twiceit = FALSE,
       endrule = "Tukey", do.ends = FALSE)

  print(smoothobj, ...)
summary(smoothobj, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] a vector or time series
\item[\code{kind}] a character string indicating the kind of smoother required;
defaults to \code{"3RS3R"}.
\item[\code{twiceit}] logical, indicating if the result should be ``twiced''.
Twicing a smoother \eqn{S(y)}{} means \eqn{S(y) + S(y - S(y))}{}, i.e.,
adding smoothed residuals to the smoothed values.  This decreases
bias (increasing variance).
\item[\code{endrule}] a character string indicating the rule for smoothing at the
boundary.  Either \code{"Tukey"} (default) or \code{"copy"}.
\item[\code{do.ends}] logical, indicating if the 3-splitting of ties should
also happen at the boundaries (``ends'').  This is only used for
\code{kind = "S"}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\emph{\code{3}} is Tukey's short notation for running \code{\Link{median}}s
of length \bold{3},
\\
\emph{\code{3R}} stands for \bold{R}epeated \emph{\code{3}} until
convergence, and
\\
\emph{\code{S}} for \bold{S}plitting of horizontal stretches of length 2 or 3.

Hence, \emph{\code{3RS3R}} is a concatenation of \code{3R}, \code{S}
and \code{3R}, \emph{\code{3RSS}} similarly,
whereas \emph{\code{3RSR}} means first \code{3R} 
and then \code{(S and 3)} \bold{R}epeated until convergence -- which
can be bad.\end{Details}
\begin{Value}
An object of class \code{"tukeysmooth"} (which has \code{print} and
\code{summary} methods) and is a vector or time series containing the
smoothed values with additional attributes.\end{Value}
\begin{Note}\relax
S and S-PLUS use a different (somewhat better) Tukey smoother in
\code{smooth(*)}. 
Note that there are other smoothing methods which provide
rather better results.  These were designed for hand calculations
and may be used mainly for didactical purposes.

Since \R{} version 1.2, \code{smooth} \emph{does} really implement
Tukey's end-point rule correctly (see argument \code{endrule}).

\code{kind = "3RSR"} has been the default till \R-1.1,
but it can have very bad properties, see the examples.

Note that repeated application of \code{smooth(*)} \emph{does}
smooth more, for the \code{"3RS*"} kinds.\end{Note}
\begin{References}\relax
Tukey, J. W. (1977).
\emph{Exploratory Data Analysis},
Reading Massachusetts: Addison-Wesley.\end{References}
\begin{SeeAlso}\relax
\code{\Link{lowess}}; \code{\Link{loess}},
\code{\Link{supsmu}} and
\code{\Link{smooth.spline}} in package \file{modreg}.\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
x1 <- c(4, 1, 3, 6, 6, 4, 1, 6, 2, 4, 2) # very artificial
(x3R <- smooth(x1, "3R")) # 2 iterations of "3"
smooth(x3R, kind = "S")

sm.3RS <- function(x, ...)
   smooth(smooth(x, "3R", ...), "S", ...)  
  
y <- c(1,1, 19:1)
plot(y, main = "misbehaviour of \"3RSR\"", col.main = 3)
lines(sm.3RS(y))
lines(smooth(y))
lines(smooth(y, "3RSR"), col = 3, lwd = 2)# the horror

x <- c(8:10,10, 0,0, 9,9)
plot(x, main = "breakdown of  3R  and  S  and hence  3RSS")
matlines(cbind(smooth(x,"3R"),smooth(x,"S"), smooth(x,"3RSS"),smooth(x)))
   
data(presidents)
presidents[is.na(presidents)] <- 0 # silly
summary(sm3 <- smooth(presidents, "3R"))
summary(sm2 <- smooth(presidents,"3RSS"))
summary(sm  <- smooth(presidents))

all.equal(c(sm2),c(smooth(smooth(sm3, "S"), "S"))) # 3RSS  === 3R S S 
all.equal(c(sm), c(smooth(smooth(sm3, "S"), "3R")))# 3RS3R === 3R S 3R  

plot(presidents, main = "smooth(presidents0, *) :  3R and default 3RS3R")
lines(sm3,col = 3, lwd = 1.5)
lines(sm, col = 2, lwd = 1.25)

## Didactical investigation:

showSmooth <- function(x, leg.x = 1, leg.y = max(x)) {
  ss <- cbind(x, "3c"  = smooth(x, "3", end="copy"),
                 "3"   = smooth(x, "3"),
                 "3Rc" = smooth(x, "3R", end="copy"),
                 "3R"  = smooth(x, "3R"),
              sm = smooth(x))
  k <- ncol(ss) - 1
  n <- length(x)
  slwd <- c(1,1,4,1,3,2)
  slty <- c(0, 2:(k+1))
  matplot(ss, main = "Tukey Smoothers", ylab = "y ;  sm(y)",
          type= c("p",rep("l",k)), pch= par("pch"), lwd= slwd, lty= slty)
  legend(leg.x, leg.y,
         c("Data",       "3   (copy)", "3  (Tukey)",
                 "3R  (copy)", "3R (Tukey)", "smooth()"),
         pch= c(par("pch"),rep(-1,k)), col=1:(k+1), lwd= slwd, lty= slty)
  ss
}

## 4 simple didactical examples, showing different steps in smooth():

op <- par(ask = interactive(), mfrow = c(1,1))
for(x in list(c(4, 6, 2, 2, 6, 3, 6, 6, 5, 2),
              c(3, 2, 1, 4, 5, 1, 3, 2, 4, 5, 2),
              c(2, 4, 2, 6, 1, 1, 2, 6, 3, 1, 6),
              x1,
             ))
    print(t(showSmooth(x)))
par(op)
\end{ExampleCode}
\end{Examples}

