\HeaderA{stepfun}{Step Function Class}{stepfun}
\aliasA{as.stepfun}{stepfun}{as.stepfun}
\aliasA{is.stepfun}{stepfun}{is.stepfun}
\aliasA{knots}{stepfun}{knots}
\aliasA{print.stepfun}{stepfun}{print.stepfun}
\aliasA{summary.stepfun}{stepfun}{summary.stepfun}
\keyword{dplot}{stepfun}
\begin{Description}\relax
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,...)} 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.
\end{Description}
\begin{Usage}
\begin{verbatim}
stepfun(x, y, f = as.numeric(right), ties = "ordered",
        right = FALSE)

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

## S3 method for class 'stepfun':
print(x, digits = getOption("digits") - 2, ...)

## S3 method for class 'stepfun':
summary(object, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{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[\code{y}] numeric vector one longer than \code{x}, giving the heights of
the function values \emph{between} the x values.
\item[\code{f}] a number between 0 and 1, indicating how interpolation outside
the given x values should happen.  See \code{\LinkA{approxfun}{approxfun}}.
\item[\code{ties}] Handling of tied \code{x} values. Either a function or
the string \code{"ordered"}.  See  \code{\LinkA{approxfun}{approxfun}}.
\item[\code{right}] logical, indicating if the intervals should be closed on
the right (and open on the left) or vice versa.
\item[\code{Fn, object}] an \R{} object inheriting from \code{"stepfun"}.
\item[\code{digits}] number of significant digits to use, see \code{\LinkA{print}{print}}.
\item[\code{...}] potentially further arguments (required by the generic).
\end{ldescription}
\end{Arguments}
\begin{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{\LinkA{plot.stepfun}{plot.stepfun}}) \code{"stepfun"} objects.

The \code{\LinkA{environment}{environment}} of \code{fn} contains all the
information needed;
\begin{ldescription}
\item[\code{"x","y"}] the original arguments
\item[\code{"n"}] number of knots (x values)
\item[\code{"f"}] continuity parameter
\item[\code{"yleft", "yright"}] the function values \emph{outside} the knots
\item[\code{"method"}] (always \code{== "constant"}, from
\code{\LinkA{approxfun}{approxfun}(.)}).
\end{ldescription}

The knots are also available via \code{\LinkA{knots}{knots}(fn)}.
\end{Value}
\begin{Author}\relax
Martin Maechler, \email{maechler@stat.math.ethz.ch} with some basic
code from Thomas Lumley.
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{ecdf}{ecdf}} for empirical distribution functions as
special step functions and \code{\LinkA{plot.stepfun}{plot.stepfun}} for \emph{plotting}
step functions.

\code{\LinkA{approxfun}{approxfun}} and \code{\LinkA{splinefun}{splinefun}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
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:
unclass(sfun0)
ls(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
\end{ExampleCode}
\end{Examples}

