Rle-class {IRanges} | R Documentation

## Rle objects

### Description

The Rle class is a general container for storing an atomic vector that is stored in a run-length encoding format. It is based on the `rle` function from the base package.

### Constructors

  `Rle(values)`: This constructor creates an Rle instances out of an atomic vector `values`.
  `Rle(values, lengths)`: This constructor creates an Rle instances out of an atomic vector or factor object `values` and an integer or numeric vector `lengths` with all positive elements that represent how many times each value is repeated. The length of these two vectors must be the same.
  `as(from, "Rle")`: This constructor creates an Rle instances out of an atomic vector `from`.

### Accessors

In the code snippets below, `x` is an Rle object:

  `runLength(x)`: Returns the run lengths for `x`.
  `runValue(x)`: Returns the run values for `x`.
  `nrun(x)`: Returns the number of runs in `x`.
  `start(x)`: Returns the starts of the runs for `x`.
  `end(x)`: Returns the ends of the runs for `x`.
  `width(x)`: Same as `runLength(x)`.

### Replacers

In the code snippets below, `x` is an Rle object:

  `runLength(x) <- value`: Replaces `x` with a new Rle object using run values `runValue(x)` and run lengths `value`.
  `runValue(x) <- value`: Replaces `x` with a new Rle object using run values `value` and run lengths `runLength(x)`.

### Coercion

In the code snippets below, `x` and `from` are Rle objects:

  `as.vector(x)`, `as(from, "vector")`: Creates an atomic vector of the most appropriate type based on the values contained in `x`.
  `as.logical(x)`, `as(from, "logical")`: Creates a logical vector based on the values contained in `x`.
  `as.integer(x)`, `as(from, "integer")`: Creates an integer vector based on the values contained in `x`.
  `as.numeric(x)`, `as(from, "numeric")`: Creates a numeric vector based on the values contained in `x`.
  `as.complex(x)`, `as(from, "complex")`: Creates a complex vector based on the values contained in `x`.
  `as.character(x)`, `as(from, "character")`: Creates a character vector based on the values contained in `x`.
  `as.raw(x)`, `as(from, "raw")`: Creates a raw vector based on the values contained in `x`.
  `as.factor(x)`, `as(from, "factor")`: Creates a factor object based on the values contained in `x`.
  `as(from, "IRanges")`: Creates an IRanges instance from a logical Rle. Note that this instance is guaranteed to be normal.
  `as(from, "NormalIRanges")`: Creates a NormalIRanges instance from a logical Rle.

### Group Generics

Rle objects have support for S4 group generic functionality:

`Arith`
  `"+"`, `"-"`, `"*"`, `"^"`, `"%%"`, `"%/%"`, `"/"`
`Compare`
  `"=="`, `">"`, `"<"`, `"!="`, `"<="`, `">="`
`Logic`
  `"&"`, `"|"`
`Ops`
  `"Arith"`, `"Compare"`, `"Logic"`
`Math`
  `"abs"`, `"sign"`, `"sqrt"`, `"ceiling"`, `"floor"`, `"trunc"`, `"cummax"`, `"cummin"`, `"cumprod"`, `"cumsum"`, `"log"`, `"log10"`, `"log2"`, `"log1p"`, `"acos"`, `"acosh"`, `"asin"`, `"asinh"`, `"atan"`, `"atanh"`, `"exp"`, `"expm1"`, `"cos"`, `"cosh"`, `"sin"`, `"sinh"`, `"tan"`, `"tanh"`, `"gamma"`, `"lgamma"`, `"digamma"`, `"trigamma"`
`Math2`
  `"round"`, `"signif"`
`Summary`
  `"max"`, `"min"`, `"range"`, `"prod"`, `"sum"`, `"any"`, `"all"`
`Complex`
  `"Arg"`, `"Conj"`, `"Im"`, `"Mod"`, `"Re"`

See S4groupGeneric for more details.

### General Methods

In the code snippets below, `x` is an Rle object:

  `x[i, drop = !is.null(getOption("dropRle")) && getOption("dropRle")]`: Subsets `x` by index `i`, where `i` can be positive integers, negative integers, a logical vector of the same length as `x`, an Rle object of the same length as `x` containing logical values, or an IRanges object. When `drop = FALSE` returns an Rle object. When `drop = TRUE`, returns an atomic vector.
  `x %in% table`: Returns a logical Rle representing set membership in `table`.
  `aggregate(x, by, FUN, start = NULL, end = NULL, width = NULL, frequency = NULL, delta = NULL, ..., simplify = TRUE))`: Generates summaries on the specified windows and returns the result in a convenient form:
  `by`
    An object with `start`, `end`, and `width` methods.
  `FUN`
    The function, found via `match.fun`, to be applied to each window of `x`.
  `start`, `end`, `width`
    the start, end, or width of the window. If `by` is missing, then must supply two of the three.
  `frequency`, `delta`
    Optional arguments that specify the sampling frequency and increment within the window.
  ...
    Further arguments for `FUN`.
  `simplify`
    A logical value specifying whether or not the result should be simplified to a vector or matrix if possible.
  `c(x, ...)`: Combines a set of Rle objects.
  `findRange(x, vec)`: Returns an IRanges object representing the ranges in Rle `vec` that are referenced by the indices in the integer vector `x`.
  `findRun(x, vec)`: Returns an integer vector indicating the run indices in Rle `vec` that are referenced by the indices in the integer vector `x`.
  `head(x, n = 6L)`: If `n` is non-negative, returns the first n elements of `x`. If `n` is negative, returns all but the last `abs(n)` elements of `x`.
  `is.na(x)`: Returns a logical Rle indicating with values are `NA`.
  `length(x)`: Returns the underlying vector length of `x`.
  `rep(x, times, length.out, each)`, `rep.int(x, times)`: Repeats the values in `x` through one of the following conventions:
  `times`
    Vector giving the number of times to repeat each element if of length `length(x)`, or to repeat the whole vector if of length 1.
  `length.out`
    Non-negative integer. The desired length of the output vector.
  `each`
    Non-negative integer. Each element of `x` is repeated `each` times.
  `rev(x)`: Reverses the order of the values in `x`.
  `shiftApply(SHIFT, X, Y, FUN, ..., OFFSET = 0L, simplify = TRUE, verbose = FALSE))`: Let `i` be the indices in `SHIFT`, `X_i = subseq(X, 1 + OFFSET, length(X) - SHIFT[i])`, and `Y_i = subseq(Y, 1 + SHIFT[i], length(Y) - OFFSET)`. Calculates the set of `FUN(X_i, Y_i, ...)` values and return the results in a convenient form:
  `SHIFT`
    A non-negative integer vector of shift values.
  `X`, `Y`
    The Rle objects to shift.
  `FUN`
    The function, found via `match.fun`, to be applied to each set of shifted vectors.
  ...
    Further arguments for `FUN`.
  OFFSET
    A non-negative integer offset to maintain throughout the shift operations.
  `simplify`
    A logical value specifying whether or not the result should be simplified to a vector or matrix if possible.
  `verbose`
    A logical value specifying whether or not to print the `i` indices to track the iterations.
  `show(object)`: Prints out the Rle object in a user-friendly way.
  `sort(x, decreasing = FALSE, na.last = NA)`: Sorts the values in `x`.
  `decreasing`
    If `TRUE`, sort values in decreasing order. If `FALSE`, sort values in increasing order.
  `na.last`
    If `TRUE`, missing values are placed last. If `FALSE`, they are placed first. If `NA`, they are removed.
  `subseq(x, start = NA, end = NA, width = NA)`: Extract the subsequence from `x` specified by two of the three following values: `start`, `end`, and `width`. This is more efficient for extracting consecutive values than `[`.
  `summary(object, ..., digits = max(3, getOption("digits") - 3))`: Summarizes the Rle object using an atomic vector convention. The `digits` argument is used for number formatting with `signif()`.
  `table(...)`: Returns a table containing the counts of the unique values.
  `tail(x, n = 6L)`: If `n` is non-negative, returns the last n elements of `x`. If `n` is negative, returns all but the first `abs(n)` elements of `x`.
  `unique(x, incomparables = FALSE, ...)`: Returns the unique run values. The `incomparables` argument takes a vector of values that cannot be compared with `FALSE` being a special value that means that all values can be compared.
  `window(x, start = NULL, end = NULL, width = NULL, frequency = NULL, delta = NULL, ...)`: Extract the subsequence window from `x` specified by:
  `start`, `end`, `width`
    The start, end, or width of the window. Two of the three are required.
  `frequency`, `delta`
    Optional arguments that specify the sampling frequency and increment within the window.

### Logical Data Methods

In the code snippets below, `x` is an Rle object:

  `!x`: Returns logical negation (NOT) of `x`.
  `which(x)`: Returns an integer vector representing the `TRUE` indices of `x`.

### Numerical Data Methods

In the code snippets below, `x` is an Rle object:

  `pmax(..., na.rm = FALSE)`, `pmax.int(..., na.rm = FALSE)`: Parallel maxima of the Rle input values. Removes `NA`s when `na.rm = TRUE`.
  `pmin(..., na.rm = FALSE)`, `pmin.int(..., na.rm = FALSE)`: Parallel minima of the Rle input values. Removes `NA`s when `na.rm = TRUE`.
  `diff(x, lag = 1, differences = 1`: Returns suitably lagged and iterated differences of `x`.
  `lag`
    An integer indicating which lag to use.
  `differences`
    An integer indicating the order of the difference.
  `mean(x, na.rm = FALSE)`: Calculates the mean of `x`. Removes `NA`s when `na.rm = TRUE`.
  `var(x, y = NULL, na.rm = FALSE)`: Calculates the variance of `x` or covariance of `x` and `y` if both are supplied. Removes `NA`s when `na.rm = TRUE`.
  `cov(x, y, use = "everything")`, `cor(x, y, use = "everything")`: Calculates the covariance and correlation respectively of Rle objects `x` and `y`. The `use` argument is an optional character string giving a method for computing covariances in the presence of missing values. This must be (an abbreviation of) one of the strings `"everything"`, `"all.obs"`, `"complete.obs"`, `"na.or.complete"`, or `"pairwise.complete.obs"`.
  `sd(x, na.rm = FALSE)`: Calculates the standard deviation of `x`. Removes `NA`s when `na.rm = TRUE`.
  `median(x, na.rm = FALSE)`: Calculates the median of `x`. Removes `NA`s when `na.rm = TRUE`.
  `quantile(x, probs = seq(0, 1, 0.25), na.rm = FALSE, names = TRUE, type = 7, ...)`: Calculates the specified quantiles of `x`.
  `probs`
    A numeric vector of probabilities with values in [0,1].
  `na.rm`
    If `TRUE`, removes `NA`s from `x` before the quantiles are computed.
  `names`
    If `TRUE`, the result has names describing the quantiles.
  `type`
    An integer between 1 and 9 selecting one of the nine quantile algorithms detailed in `quantile`.
  ...
    Further arguments passed to or from other methods.
  `mad(x, center = median(x), constant = 1.4826, na.rm = FALSE, low = FALSE, high = FALSE)`: Calculates the median absolute deviation of `x`.
  `center`
    The center to calculate the deviation from.
  `constant`
    The scale factor.
  `na.rm`
    If `TRUE`, removes `NA`s from `x` before the mad is computed.
  `low`
    If `TRUE`, compute the 'lo-median'.
  `high`
    If `TRUE`, compute the 'hi-median'.

### Character Data Methods

In the code snippets below, `x` is an Rle object:

  `nchar(x, type = "chars", allowNA = FALSE)`: Returns an integer Rle representing the number of characters in the corresponding values of `x`.
  `type`
    One of `c("bytes", "chars", "width")`.
  `allowNA`
    Should `NA` be returned for invalid multibyte strings rather than throwing an error?
  `substr(x, start, stop)`, `substring(text, first, last = 1000000L)`: Returns a character Rle containing the specified substrings beginning at `start`/`first` and ending at `stop`/`last`.
  `chartr(old, new, x)`: Returns a character translated version of `x`.
  `old`
    A character string specifying the characters to be translated.
  `new`
    A character string specifying the translations.
  `tolower(x)`: Returns a lower case version of `x`.
  `toupper(x)`: Returns an upper case version of `x`.
  `sub(pattern, replacement, x, ignore.case = FALSE, extended = TRUE, perl = FALSE, fixed = FALSE, useBytes = FALSE)`: Returns a character Rle with replacements based on matches determined by regular expression matching. See `sub` for a description of the arguments.
  `gsub(pattern, replacement, x, ignore.case = FALSE, extended = TRUE, perl = FALSE, fixed = FALSE, useBytes = FALSE)`: Returns a character Rle with replacements based on matches determined by regular expression matching. See `gsub` for a description of the arguments.

### Author(s)

P. Aboyoun

### See Also

`rle`, Sequence-class, S4groupGeneric, IRanges-class

### Examples

      x <- Rle(10:1, 1:10)
      x

      runLength(x)
      runValue(x)
      nrun(x)

      diff(x)
      unique(x)
      sort(x)
      sqrt(x)
      x^2 + 2 * x + 1
      x[c(1,3,5,7,9)]
      subseq(x, 4, 14)
      range(x)
      table(x)
      sum(x)
      mean(x)
      x > 4
      aggregate(x, x > 4, mean)
      aggregate(x, FUN = mean, start = 1:(length(x) - 50), end = 51:length(x))

      y <- Rle(c(TRUE,TRUE,FALSE,FALSE,TRUE,FALSE,TRUE,TRUE,TRUE))
      y
      as.vector(y)
      rep(y, 10)
      c(y, x > 5)

      z <- c("the", "quick", "red", "fox", "jumps", "over", "the", "lazy", "brown", "dog")
      z <- Rle(z, seq_len(length(z)))
      chartr("a", "@", z)
      toupper(z)

[Package IRanges version 1.2.3 Index]