stepfun                package:stats                R Documentation

Step Function Class

Description:

     Given the vectors (x[1],..., x[n]) and (y[0],y[1],..., y[n]) (one
     value more!), 'stepfun(x,y,...)' returns an interpolating 'step'
     function, say 'fn'. I.e., fn(t) = c[i] (constant) for t in ( x[i],
     x[i+1]) and at the abscissa values, if (by default) 'right =
     FALSE', fn(x[i]) = y[i] and for 'right = TRUE', fn(x[i]) = y[i-1],
     for i=1,...,n.

     The value of the constant c[i] above depends on the 'continuity'
     parameter 'f'. For the default, 'right = FALSE, f = 0', 'fn' is a
     _cadlag_ function, i.e., continuous at right, limit ('the point')
     at left. In general, c[i] is interpolated in between the
     neighbouring y values, c[i] = (1-f)*y[i] + f*y[i+1]. Therefore,
     for non-0 values of 'f', 'fn' may no longer be a proper step
     function, since it can be discontinuous from both sides, unless
     'right = TRUE, f = 1' which is right-continuous.

Usage:

     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, ...)

Arguments:

       x: numeric vector giving the knots or jump locations of the step
          function for 'stepfun()'.  For the other functions, 'x' is as
          'object' below.

       y: numeric vector one longer than 'x', giving the heights of the
          function values _between_ the x values.

       f: a number between 0 and 1, indicating how interpolation
          outside the given x values should happen.  See 'approxfun'.

    ties: Handling of tied 'x' values. Either a function or the string
          '"ordered"'.  See  'approxfun'.

   right: logical, indicating if the intervals should be closed on the
          right (and open on the left) or vice versa.

Fn, object: an R object inheriting from '"stepfun"'.

  digits: number of significant digits to use, see 'print'.

     ...: potentially further arguments (required by the generic).

Value:

     A function of class '"stepfun"', say 'fn'. There are methods
     available for summarizing ('"summary(.)"'), representing
     ('"print(.)"') and plotting  ('"plot(.)"', see 'plot.stepfun')
     '"stepfun"' objects.

     The 'environment' of 'fn' contains all the information needed; 

 "x","y": the original arguments

     "n": number of knots (x values)

     "f": continuity parameter

"yleft", "yright": the function values _outside_ the knots

"method": (always '== "constant"', from 'approxfun(.)').

     The knots are also available via 'knots(fn)'.

Author(s):

     Martin Maechler, maechler@stat.math.ethz.ch with some basic code
     from Thomas Lumley.

See Also:

     'ecdf' for empirical distribution functions as special step
     functions and 'plot.stepfun' for _plotting_ step functions.

     'approxfun' and '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:
     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

