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 NAs when na.rm = TRUE.
pmin(..., na.rm = FALSE), pmin.int(..., na.rm = FALSE): Parallel minima of the Rle input values. Removes NAs 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 NAs 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 NAs 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 NAs when na.rm = TRUE.
median(x, na.rm = FALSE): Calculates the median of x. Removes NAs 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 NAs 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 NAs 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.0 Index]