R: Step Functions - Creation and Class

stepfun {stats} | R Documentation

## Step Functions - Creation and 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 from the right, limits from the left, so that the function is piecewise constant on intervals that include their left endpoint. 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 left-continuous (i.e., constant pieces contain their right endpoint).

### 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)`.

### Note

The objects of class `"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

        eval(attr(old_obj, "call"), environment(old_obj))

since the data used is stored as part of the object's environment.

### 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 = 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

[Package stats version 4.0.5 Index]