Rle-runstat {S4Vectors} | R Documentation

## Fixed-width running window summaries

### Description

The `runsum`, `runmean`, `runmed`, `runwtsum`, `runq` functions calculate the sum, mean, median, weighted sum, and order statistic for fixed width running windows.

### Usage

    runsum(x, k, endrule = c("drop", "constant"), ...)

    runmean(x, k, endrule = c("drop", "constant"), ...)

    ## S4 method for signature 'Rle'
    smoothEnds(y, k = 3)

    ## S4 method for signature 'Rle'
    runmed(x, k, endrule = c("median", "keep", "drop", "constant"),
           algorithm = NULL, print.level = 0)

    runwtsum(x, k, wt, endrule = c("drop", "constant"), ...)

    runq(x, k, i, endrule = c("drop", "constant"), ...)

### Arguments

`x,y` | The data object.
`k` | An integer indicating the fixed width of the running window. Must be odd when `endrule != "drop"`.
`endrule` | A character string indicating how the values at the beginning and the end (of the data) should be treated. `"median"` see `runmed`; `"keep"` see `runmed`; `"drop"` do not extend the running statistics to be the same length as the underlying vectors; `"constant"` copies running statistic to the first values and analogously for the last ones making the smoothed ends constant.
`wt` | A numeric vector of length `k` that provides the weights to use.
`i` | An integer in [0, k] indicating which order statistic to calculate.
`algorithm,print.level` | See `?stats::runmed` for a description of these arguments.
`...` | Additional arguments passed to methods. Specifically, `na.rm`. When `na.rm = TRUE`, the `NA` and `NaN` values are removed. When `na.rm = FALSE`, `NA` is returned if either `NA` or `NaN` are in the specified window.

### Details

The `runsum`, `runmean`, `runmed`, `runwtsum`, and `runq` functions provide efficient methods for calculating the specified numeric summary by performing the looping in compiled code.

### Value

An object of the same class as `x`.

### Author(s)

P. Aboyoun and V. Obenchain

### See Also

`runmed`, Rle-class, RleList-class

### Examples

      x <- Rle(1:10, 1:10)
      runsum(x, k = 3)
      runsum(x, k = 3, endrule = "constant")
      runmean(x, k = 3)
      runwtsum(x, k = 3, wt = c(0.25, 0.5, 0.25))
      runq(x, k = 5, i = 3, endrule = "constant")

      ## Missing and non-finite values
      x <- Rle(c(1, 2, NA, 0, 3, Inf, 4, NaN))
      runsum(x, k = 2)
      runsum(x, k = 2, na.rm = TRUE)
      runmean(x, k = 2, na.rm = TRUE)
      runwtsum(x, k = 2, wt =  c(0.25, 0.5), na.rm = TRUE)
      runq(x, k = 2, i = 2, na.rm = TRUE) ## max value in window

      ## The .naive_runsum() function demonstrates the semantics of
      ## runsum(). This test ensures the behavior is consistent with
      ## base::sum().

      .naive_runsum <- function(x, k, na.rm=FALSE)
          sapply(0:(length(x)-k),
              function(offset) sum(x[1:k + offset], na.rm=na.rm))

      x0 <- c(1, Inf, 3, 4, 5, NA)
      x <- Rle(x0)
      target1 <- .naive_runsum(x0, 3, na.rm = TRUE)
      target2 <- .naive_runsum(x, 3, na.rm = TRUE)
      stopifnot(target1 == target2)
      current <- as.vector(runsum(x, 3, na.rm = TRUE))
      stopifnot(target1 == current)

      ## runmean() and runwtsum() :
      x <- Rle(c(2, 1, NA, 0, 1, -Inf))
      runmean(x, k = 3)
      runmean(x, k = 3, na.rm = TRUE)
      runwtsum(x, k = 3, wt = c(0.25, 0.50, 0.25))
      runwtsum(x, k = 3, wt = c(0.25, 0.50, 0.25), na.rm = TRUE)

      ## runq() :
      runq(x, k = 3, i = 1, na.rm = TRUE) ## smallest value in window
      runq(x, k = 3, i = 3, na.rm = TRUE) ## largest value in window

      ## When na.rm = TRUE, it is possible the number of non-NA
      ## values in the window will be less than the 'i' specified.
      ## Here we request the 4th smallest value in the window,
      ## which tranlates to the value at the 4/5 (0.8) percentile.
      x <- Rle(c(1, 2, 3, 4, 5))
      runq(x, k=length(x), i=4, na.rm=TRUE)

      ## The same request on a Rle with two missing values
      ## finds the value at the 0.8 percentile of the vector
      ## at the new length of 3 after the NA's have been removed.
      ## This translates to round((0.8) * 3).
      x <- Rle(c(1, 2, 3, NA, NA))
      runq(x, k=length(x), i=4, na.rm=TRUE)

[Package S4Vectors version 0.20.1 Index]