% File src/library/stats/man/stepfun.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2014 R Core Team
% Distributed under GPL 2 or later

\name{stepfun}
\title{Step Functions - Creation and Class}
\alias{stepfun}
\alias{is.stepfun}
\alias{as.stepfun}
\alias{print.stepfun}
\alias{summary.stepfun}
\alias{knots}
\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], \dots, x[n])} and
  \eqn{(y_0,y_1,\ldots, y_n)}{(y[0], y[1], \dots, y[n])} (one value
  more!), \code{stepfun(x, y, \dots)} returns an interpolating
  \sQuote{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}{i=1, \dots, n}.

  The value of the constant \eqn{c_i}{c[i]} above depends on the
  \sQuote{continuity} parameter \code{f}.
  For the default, \code{right = FALSE, f = 0},
  \code{fn} is a \emph{cadlag} function, i.e., continuous from the right,
  limits from the left, so that the function is piecewise constant on
  intervals that include their \emph{left} endpoint.
  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 left-continuous (i.e., constant
  pieces contain their right endpoint).
}
\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;
    \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 via \code{\link{knots}(fn)}.
}
\author{
  Martin Maechler, \email{maechler@stat.math.ethz.ch} with some basic
  code from Thomas Lumley.
}
\note{
  The objects of class \code{"stepfun"} are not intended to be used for
  permanent storage and may change structure between versions of \R (and
  did at \R 3.0.0).  They can usually be re-created by
  \preformatted{    eval(attr(old_obj, "call"), environment(old_obj))}
  since the data used is stored as part of the object's environment.
}
\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 = 0.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
}
\keyword{dplot}