Rle-class {S4Vectors} | 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.

### Constructor

  `Rle(values, lengths)`: This constructor creates an Rle instance 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. `lengths` can be missing in which case `values` is turned into an Rle.

### Getters

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

### Setters

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

#### From atomic vector to Rle

In the code snippets below, `from` is an atomic vector:

  `as(from, "Rle")`: This coercion creates an Rle instances out of an atomic vector `from`.

#### From Rle to other objects

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

  `as.vector(x, mode="any")`, `as(from, "vector")`: Creates an atomic vector based on the values contained in `x`. The vector will be coerced to the requested `mode`, unless `mode` is "any", in which case the most appropriate type is chosen.

  `as.factor(x)`, `as(from, "factor")`: Creates a factor object based on the values contained in `x`.

  `as.data.frame(x)`, `as(from, "data.frame")`: Creates a `data.frame` with a single column holding the result of `as.vector(x)`.

  `decode(x)`: Converts an Rle to its native form, such as an atomic vector or factor. Calling `decode` on a non-Rle will return `x` by default, so it is generally safe for ensuring that an object is native.

### General Methods

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

  `x[i, drop=getOption("dropRle", default=FALSE)]`: 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[i] <- value`: Replaces elements in `x` specified by `i` with corresponding elements in `value`. Supports the same types for `i` as `x[i]`.

  `x %in% table`: Returns a logical Rle representing set membership in `table`.

  `c(x, ..., ignore.mcols=FALSE)`: Concatenate Rle object `x` and the Rle objects in `...` together. See `?c` in this package (the S4Vectors package) for more information about concatenating Vector derivatives.

  `append(x, values, after = length(x))`: Insert one Rle into another Rle.

  `values`

    the Rle to insert.

  `after`

    the subscript in `x` after which the values are to be inserted.

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

  `is.unsorted(x, na.rm = FALSE, strictly = FALSE)`: Returns a logical value specifying if `x` is unsorted.

  `na.rm`

    remove missing values from check.

  `strictly`

    check for _strictly_ increasing values.

  `length(x)`: Returns the underlying vector length of `x`.

  `match(x, table, nomatch = NA_integer_, incomparables = NULL)`: Matches the values in `x` to `table`:

  `table`

    the values to be matched against.

  `nomatch`

    the value to be returned in the case when no match is found.

  `incomparables`

    a vector of values that cannot be matched. Any value in `x` matching a value in this vector is assigned the `nomatch` value.

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

  `show(object)`: Prints out the Rle object in a user-friendly way.

  `order(..., na.last=TRUE, decreasing=FALSE, method=c("auto", "shell", "radix"))`: Returns a permutation which rearranges its first argument into ascending or descending order, breaking ties by further arguments. See `order`.

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

  `subset(x, subset)`: Returns a new Rle object made of the subset using logical vector `subset`.

  `table(...)`: Returns a table containing the counts of the unique values. Supported arguments include `useNA` with values of ‘no’ and ‘ifany’. Multiple Rle's must be concatenated with `c()` before calling `table`.

  `tabulate(bin, nbins = max(bin, 1L, na.rm = TRUE))`: Just like `tabulate`, except optimized for Rle.

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

### Set Operations

In the code snippets below, `x` and `y` are Rle object or some other vector-like object:

  `setdiff(x, y)`: Returns the unique elements in `x` that are not in `y`.

  `union(x, y)`: Returns the unique elements in either `x` or `y`.

  `intersect(x, y)`: Returns the unique elements in both `x` and `y`.

### Author(s)

P. Aboyoun

### See Also

Rle-utils, Rle-runstat, and aggregate for more operations on Rle objects.

`rle`

Vector-class

### Examples

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

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

      diff(x)
      unique(x)
      sort(x)
      x[c(1,3,5,7,9)]
      x > 4

      x2 <- Rle(LETTERS[c(21:26, 25:26)], 8:1)
      table(x2)

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

[Package S4Vectors version 0.18.3 Index]