\name{ecdf}
\alias{ecdf}
\alias{plot.ecdf}
\alias{print.ecdf}
\title{Empirical Cumulative Distribution Function}
\usage{
ecdf(x)

\method{plot}{ecdf}(\dots, verticals = FALSE, col.01line = "gray70")

\method{print}{ecdf}(x, digits= getOption("digits") - 2, \dots)
}
\arguments{
  \item{x}{numeric vector of \dQuote{observations} in \code{ecdf};  for
    the methods, an object of class \code{"ecdf"}, typically.}
  \item{\dots}{arguments to be passed to \code{\link{plot.stepfun}}, the
    first of which should be an \R object of class \code{"ecdf"}.}
  \item{verticals}{see \code{\link{plot.stepfun}}.}
  \item{col.01line}{numeric or character specifying the color of the
    horizontal lines at y=0 and 1, see \code{\link{colors}}.}
  \item{digits}{number of significant digits to use, see
    \code{\link{print}}.}
}
\description{
  Compute or plot an empirical cumulative distribution function.
}
\details{
  The e.c.d.f. (empirical cumulative distribution function)
  \eqn{F_n}{Fn} is a step
  function with jump \eqn{1/n} at each observation (possibly with
  multiple jumps at one place if there are ties).

  For observations
  \code{x}\eqn{= (}\eqn{x_1,x_2}{x1,x2}, \ldots \eqn{x_n)}{xn)},
  \eqn{F_n}{Fn} is the fraction of observations less or equal to \eqn{t},
  i.e.,
  \deqn{F_n(t) = \#\{x_i\le t\}\ / n
               = \frac1 n\sum_{i=1}^n \mathbf{1}_{[x_i \le t]}.}{
    Fn(t) = #\{x_i \le t\} / n  =  1/n sum(i=1,n) Indicator(xi <= t).}

  The function \code{plot.ecdf} which implements the \code{\link{plot}}
  method for \code{ecdf} objects, is implemented via a call to
  \code{\link{plot.stepfun}}; see its documentation.
}
\value{
  For \code{ecdf}, a function of class \code{"ecdf"}, inheriting from the
  \code{"\link{stepfun}"} class.
}
\author{
  Martin Maechler, \email{maechler@stat.math.ethz.ch}.
}
\seealso{\code{\link{stepfun}}, the more general class of step functions,
  \code{\link{approxfun}} and \code{\link{splinefun}}.
}
\examples{
##-- Simple didactical  ecdf  example:
Fn <- ecdf(rnorm(12))
Fn; summary(Fn)
12*Fn(knots(Fn)) == 1:12 ## == 1:12  if and only if there are no ties !

y <- round(rnorm(12),1); y[3] <- y[1]
Fn12 <- ecdf(y)
Fn12
print(knots(Fn12), dig=2)
12*Fn12(knots(Fn12)) ## ~= 1:12  if there where no ties

summary(Fn12)
summary.stepfun(Fn12)
print(ls.Fn12 <- ls(env= environment(Fn12)))
##[1] "f"  "method"  "n"  "ties"   "x"  "y"  "yleft"  "yright"

12 * Fn12((-20:20)/10)

###----------------- Plotting --------------------------

op <- par(mfrow=c(3,1), mgp=c(1.5, 0.8,0), mar= .1+c(3,3,2,1))

F10 <- ecdf(rnorm(10))
summary(F10)

plot(F10)
plot(F10, verticals= TRUE, do.p = FALSE)

plot(Fn12)# , lwd=2) dis-regarded
xx <- unique(sort(c(seq(-3,2, length=201), knots(Fn12))))
lines(xx, Fn12(xx), col='blue')
abline(v=knots(Fn12),lty=2,col='gray70')

plot(xx, Fn12(xx), type='b', cex=.1)#- plot.default
plot(Fn12, col.h='red', add= TRUE)  #- plot method
abline(v=knots(Fn12),lty=2,col='gray70')
plot(Fn12, verticals=TRUE, col.p='blue', col.h='red',col.v='bisque')
par(op)

##-- this works too (automatic call to  ecdf(.)):
plot.ecdf(rnorm(24))
}
\keyword{dplot}
\keyword{hplot}

\eof
\name{plot.stepfun}
\alias{plot.stepfun}
\alias{lines.stepfun}
\title{Plot Step Functions}
\description{
  Method of the generic \code{\link{plot}} for \code{\link{stepfun}}
  objects and utility for plotting piecewise constant functions.
}
\usage{
\method{plot}{stepfun}(x, xval, xlim, ylim,
     xlab = "x", ylab = "f(x)", main = NULL,
     add = FALSE, verticals = TRUE, do.points = TRUE,
     pch = par("pch"), col.points=par("col"), cex.points=par("cex"),
     col.hor = par("col"), col.vert= par("col"),
     lty = par("lty"), lwd = par("lwd"), \dots)

\method{lines}{stepfun}(x, \dots)
}
\arguments{
  \item{x}{an \R object inheriting from \code{"stepfun"}.}
  \item{xval}{numeric vector of abscissa values at which to evaluate
    \code{x}.  Defaults to \code{\link{knots}(x)} restricted to \code{xlim}.}
  \item{xlim,ylim}{numeric(2) each; range of \code{x} or \code{y} values
    to use.  Both have sensible defaults.}
  \item{xlab,ylab}{labels of x and y axis.}
  \item{main}{main title.}
  \item{add}{logical; if \code{TRUE} only \emph{add} to an existing plot.}
  \item{verticals}{logical;  if \code{TRUE}, draw vertical lines at steps.}
  \item{do.points}{logical;  if \code{true}, also draw points at the
    (\code{xlim} restricted) knot locations.}
  \item{pch}{character; point character if \code{do.points}.}
  \item{col.points}{character or integer code; color of points if
    \code{do.points}.}
  \item{cex.points}{numeric; character expansion factor if \code{do.points}.}
  \item{col.hor}{color of horizontal lines.}
  \item{col.vert}{color of vertical lines.}
  \item{lty, lwd}{line type and thickness for all lines.}
  \item{\dots}{further arguments of \code{\link{plot}(.)}, or if\code{(add)}
    \code{\link{segments}(.)}.}
}
\value{
  A list with two components
  \item{t}{abscissa (x) values, including the two outermost ones.}
  \item{y}{y values \sQuote{in between} the \code{t[]}.}
}
\author{Martin Maechler \email{maechler@stat.math.ethz.ch}, 1990,
    1993; ported to \R, 1997.}
\seealso{\code{\link{ecdf}} for empirical distribution functions as
  special step functions,
  \code{\link{approxfun}} and \code{\link{splinefun}}.
}
\examples{
y0 <- c(1,2,4,3)
sfun0  <- stepfun(1:3, y0, f = 0)
sfun.2 <- stepfun(1:3, y0, f = .2)
sfun1  <- stepfun(1:3, y0, right = TRUE)

tt <- seq(0,3, by=0.1)
op <- par(mfrow=c(2,2))
plot(sfun0); plot(sfun0, xval=tt, add=TRUE, col.h="bisque")
plot(sfun.2);plot(sfun.2,xval=tt, add=TRUE, col.h="orange")
plot(sfun1);lines(sfun1, xval=tt, col.h="coral")
##-- This is  revealing :
plot(sfun0, verticals= FALSE,
     main = "stepfun(x, y0, f=f)  for f = 0, .2, 1")
for(i in 1:3)
  lines(list(sfun0,sfun.2,stepfun(1:3,y0,f = 1))[[i]], col.h=i, col.v=i)
legend(2.5, 1.9, paste("f =", c(0,0.2,1)), col=1:3, lty=1, y.inter=1); par(op)

# Extend and/or restrict 'viewport':
plot(sfun0, xlim = c(0,5), ylim = c(0, 3.5),
     main = "plot(stepfun(*), xlim= . , ylim = .)")

##-- this works too (automatic call to  ecdf(.)):
plot.stepfun(rt(50, df=3), col.vert = "gray20")
}
\keyword{hplot}
\eof
\name{stepfun}
\alias{stepfun}
\alias{is.stepfun}
\alias{as.stepfun}
%\alias{as.stepfun.default}
\alias{print.stepfun}
\alias{summary.stepfun}
\alias{knots}
%\alias{knots.stepfun}
\title{Step Function Class}
\usage{
stepfun(x, y, f = as.numeric(right), ties = "ordered", right = FALSE)

is.stepfun(x)
knots(Fn, \dots)
as.stepfun(x, \dots)

\method{print}{stepfun}(x, digits = getOption("digits") - 2, \dots)

\method{summary}{stepfun}(object, \dots)
}
\arguments{
  \item{x}{numeric vector giving the knots or jump locations of the step
    function for \code{stepfun()}.  For the other functions, \code{x} is
    as \code{object} below.}
  \item{y}{numeric vector one longer than \code{x}, giving the heights of
    the function values \emph{between} the x values.}
  \item{f}{a number between 0 and 1, indicating how interpolation outside
    the given x values should happen.  See \code{\link{approxfun}}.}
  \item{ties}{Handling of tied \code{x} values. Either a function or
    the string \code{"ordered"}.  See  \code{\link{approxfun}}.}
  \item{right}{logical, indicating if the intervals should be closed on
    the right (and open on the left) or vice versa.}

  \item{Fn, object}{an \R object inheriting from \code{"stepfun"}.}
  \item{digits}{number of significant digits to use, see \code{\link{print}}.}
  \item{\dots}{potentially further arguments (required by the generic).}
}
\description{
  Given the vectors \eqn{(x_1,\ldots, x_n)}{(x[1],\ldots, x[n])} and
  \eqn{(y_0,y_1,\ldots, y_n)}{(y[0],y[1],\ldots, y[n])} (one value
  more!), \code{stepfun(x,y,\dots)} returns an interpolating
  \dQuote{step} function, say \code{fn}. I.e., \eqn{fn(t) =
    c}\eqn{_i}{[i]} (constant) for \eqn{t \in (x_i, x_{i+1})}{t in (
    x[i], x[i+1])} and at the abscissa values, if (by default)
  \code{right = FALSE}, \eqn{fn(x_i) = y_i}{fn(x[i]) = y[i]} and for
  \code{right = TRUE}, \eqn{fn(x_i) = y_{i-1}}{fn(x[i]) = y[i-1]}, for
  \eqn{i=1,\ldots,n}.

  The value of the constant \eqn{c_i}{c[i]} above depends on the
  \dQuote{continuity} parameter \code{f}.
  For the default, \code{right = FALSE, f = 0},
  \code{fn} is a \dQuote{cadlag} function, i.e., continuous at right,
  limit (\dQuote{the point}) at left.
  In general, \eqn{c_i}{c[i]} is interpolated in between the
  neighbouring \eqn{y} values,
  \eqn{c_i= (1-f) y_i + f\cdot y_{i+1}}{c[i] = (1-f)*y[i] + f*y[i+1]}.
  Therefore, for non-0 values of \code{f}, \code{fn} may no longer be a proper
  step function, since it can be discontinuous from both sides, unless
  \code{right = TRUE, f = 1} which is right-continuous.
}
\value{
  A function of class \code{"stepfun"}, say \code{fn}.
%
  There are methods available for summarizing (\code{"summary(.)"}),
  representing (\code{"print(.)"}) and plotting  (\code{"plot(.)"}, see
  \code{\link{plot.stepfun}}) \code{"stepfun"} objects.

  The \code{\link{environment}} of \code{fn} contains all the
  information needed;
  \itemize{
    \item{"x","y"}{the original arguments}
    \item{"n"}{number of knots (x values)}
    \item{"f"}{continuity parameter}
    \item{"yleft", "yright"}{the function values \emph{outside} the knots;}
    \item{"method"}{(always \code{== "constant"}, from
      \code{\link{approxfun}(.)}).}
  }
  The knots are also available by \code{\link{knots}(fn)}.
}
\author{
  Martin Maechler, \email{maechler@stat.math.ethz.ch} with some basic
  code from Thomas Lumley.
}
\seealso{\code{\link{ecdf}} for empirical distribution functions as
  special step functions and \code{\link{plot.stepfun}} for \emph{plotting}
  step functions.

  \code{\link{approxfun}} and \code{\link{splinefun}}.
}
\examples{
y0 <- c(1,2,4,3)
sfun0  <- stepfun(1:3, y0, f = 0)
sfun.2 <- stepfun(1:3, y0, f = .2)
sfun1  <- stepfun(1:3, y0, f = 1)
sfun1c <- stepfun(1:3, y0, right=TRUE)# hence f=1
sfun0
summary(sfun0)
summary(sfun.2)

## look at the internal structure:
print.default(sfun0)
ls.str(envir = environment(sfun0))

x0 <- seq(0.5,3.5, by = 0.25)
rbind(x=x0, f.f0 = sfun0(x0), f.f02= sfun.2(x0),
      f.f1 = sfun1(x0), f.f1c = sfun1c(x0))
## Identities :
stopifnot(identical(y0[-1], sfun0 (1:3)),# right = FALSE
          identical(y0[-4], sfun1c(1:3)))# right = TRUE
}
\keyword{dplot}
\eof
