1\name{plotDS}
2\alias{plotDS}
3\title{Plot Data and Smoother / Fitted Values}
4\description{
5  For one-dimensional nonparametric regression, plot the data and fitted
6  values, typically a smooth function, and optionally use segments to
7  visualize the residuals.
8}
9\usage{
10plotDS(x, yd, ys, xlab = "", ylab = "", ylim = rrange(c(yd, ys)),
11       xpd = TRUE, do.seg = TRUE, seg.p = 0.95,
12       segP = list(lty = 2, lwd = 1,   col = 2),
13       linP = list(lty = 1, lwd = 2.5, col = 3),
14       \dots)
15}
16\arguments{
17  \item{x, yd, ys}{numeric vectors all of the same length, representing
18    \eqn{(x_i, y_i)} and fitted (smooth) values \eqn{\hat{y}_i}{y^_i}.
19    \code{x} will be sorted increasingly if necessary, and \code{yd} and
20    \code{ys} accordingly.
21
22    Alternatively, \code{ys} can be an x-y list (as resulting from
23    \code{\link[grDevices]{xy.coords}}) containing fitted values on a
24    finer grid than the observations \code{x}.  In that case, the
25    observational values \code{x[]} \bold{must} be part of the larger
26    set; \code{\link{seqXtend}()} may be applied to construct such a set
27    of abscissa values.
28  }
29  \item{xlab, ylab}{x- and y- axis labels, as in \code{\link{plot.default}}.}
30  \item{ylim}{limits of y-axis to be used; defaults to a \emph{robust}
31    range of the values.}
32  \item{xpd}{see \code{\link{par}(xpd=.)}; by default do allow to draw
33    outside the plot region.}
34  \item{do.seg}{logical indicating if residual segments should be drawn,
35    at \code{x[i]}, from \code{yd[i]} to \code{ys[i]} (approximately,
36    see \code{seg.p}).}
37  \item{seg.p}{segment percentage of segments to be drawn, from
38    \code{yd} to \code{seg.p*ys + (1-seg.p)*yd}.}
39  \item{segP}{list with named components \code{lty, lwd, col} specifying
40    line type, width and color for the residual segments,
41    used only when \code{do.seg} is true.}
42  \item{linP}{list with named components \code{lty, lwd, col} specifying
43    line type, width and color for \dQuote{smooth curve lines}.}
44  \item{\dots}{further arguments passed to \code{\link{plot}}.}
45}
46\author{Martin Maechler, since 1990}
47\note{Non-existing components in the lists \code{segP} or \code{linP}
48  will result in the \code{\link{par}} defaults to be used.
49
50  \code{plotDS()} used to be called \code{pl.ds} up to November 2007.
51}
52\seealso{\code{\link{seqXtend}()} to construct more smooth \code{ys}
53  \dQuote{objects}.
54}
55\examples{
56 data(cars)
57 x <-  cars$speed
58 yd <- cars$dist
59 ys <- lowess(x, yd, f = .3)$y
60 plotDS(x, yd, ys)
61
62 ## More interesting : Version of example(Theoph)
63 data(Theoph)
64 Th4 <- subset(Theoph, Subject == 4)
65 ## just for "checking" purposes -- permute the observations:
66 Th4 <- Th4[sample(nrow(Th4)), ]
67 fm1 <- nls(conc ~ SSfol(Dose, Time, lKe, lKa, lCl), data = Th4)
68
69 ## Simple
70 plotDS(Th4$Time, Th4$conc, fitted(fm1),
71        sub  = "Theophylline data - Subject 4 only",
72        segP = list(lty=1,col=2), las = 1)
73
74 ## Nicer: Draw the smoother not only at x = x[i] (observations):
75 xsm <- unique(sort(c(Th4$Time, seq(0, 25, length = 201))))
76 ysm <- c(predict(fm1, newdata = list(Time = xsm)))
77 plotDS(Th4$Time, Th4$conc, ys = list(x=xsm, y=ysm),
78        sub  = "Theophylline data - Subject 4 only",
79        segP = list(lwd=2), las = 1)
80}
81\keyword{hplot}
82