Sequence-class {IRanges} | R Documentation |
The Sequence virtual class serves as the heart of the IRanges package
and has over 90 subclasses. It serves a similar role as vector
in base R. The Sequence class includes three slots: elementType
,
metadata
(via extension of the Annotated class), and
elementMetadata
. Their purpose is defined below.
The elementType
slot is the preferred location for Sequence
subclasses to store the type of data represented in the sequence. It is
designed to take a character of length 1 representing the class of the
sequence elements. While the Sequence class performs no validity checking
based on elementType
, if a subclass expects elements to be of a
given type, that subclass is expected to perform the necessary validity
checking. For example, the subclass IntegerList has
elementType = "integer"
and its validity method checks if this
condition is TRUE.
The Sequence class supports the storage of global and element-wise metadata
with its metadata
and elementMetadata
slots. The
metadata
slot can store a list of metadata pertaining to the whole
object and the elementMetadata
slot can store a
DataTable (or NULL
) for element-wise metadata with a
row for each element and a column for each metadata variable.
To be functional, a class that inherits from Sequence must define a
length
and names
methods as well as one or both of the
subscript methods "[["
and "["
.
In the following code snippets, x
is a Sequence object.
length(x)
:
Get the number of elements in x
.
NROW(x)
:
Defined as length(x)
for any Sequence object that is
not a DataTable object.
If x
is a DataTable object, then it's
defined as nrow(x)
.
names(x)
, names(x) <- value
:
Get or set the names of the elements in the Sequence.
elementType(x)
:
Get the scalar string naming the class from which all elements must
derive.
elementLengths(x)
:
Get the 'length' of each of the elements.
isEmpty(x)
:
Returns a logical indicating either if the sequence has no elements
or if all its elements are empty.
nlevels(x)
:
Returns the number of factor levels.
metadata(x)
, metadata(x) <- value
:
Get or set the list holding arbitrary R objects as annotations.
May be, and often is, empty.
elementMetadata(x), elementMetadata(x) <- value
:
Get or set the DataTable holding local metadata on each
element. The rows are named according to the names of the elements.
Optional, may be NULL
.
values(x), values(x) <- value
:
Alternative to elementMetadata
functions.
In the code snippets below, x
is a Sequence object or regular R vector
object. The R vector object methods for window
and seqselect
are defined in this package and the remaining methods are defined in base R.
x[i, drop=TRUE]
:
If defined, returns a new Sequence object made of selected elements
i
, which can be missing; an NA-free logical, numeric, or
character vector; or a logical Rle object. The drop
argument
specifies whether or not to coerce the returned sequence to a standard
vector.
x[i] <- value
:
Equivalent to seqselect(x, i) <- value
.
window(x, start = NA, end = NA, width = NA, frequency = NULL, delta = NULL, ...)
:
Extract the subsequence window from the Sequence object using:
start
, end
, width
frequency
, delta
"["
operator.
window(x, start = NA, end = NA, width = NA, keepLength = TRUE) <- value
:
Replace the subsequence window specified on the left (i.e. the subsequence
in x
specified by start
, end
and width
)
by value
.
value
must either be of class class(x)
, belong to a subclass
of class(x)
, be coercible to class(x)
, or be NULL
.
If keepLength
is TRUE
, the elements of value
are
repeated to create a Sequence with the same number of elements as the
width of the subsequence window it is replacing.
If keepLength
is FALSE
, this replacement method can modify
the length of x
, depending on how the length of the left
subsequence window compares to the length of value
.
seqselect(x, start=NULL, end=NULL, width=NULL)
:
Similar to window
, except that multiple consecutive subsequences
can be requested for concatenation. As such two of the three start
,
end
, and width
arguments can be used to specify the
consecutive subsequences. Alternatively, start
can take a Ranges
object or something that can be converted to a Ranges object like an
integer vector, logical vector or logical Rle. If the concatenation of
the consecutive subsequences is undesirable, consider using
Views
.
seqselect(x, start=NULL, end=NULL, width=NULL) <- value
:
Similar to window<-
, except that multiple consecutive subsequences
can be replaced by a value
whose length is a divisor of the number
of elements it is replacing. As such two of the three start
,
end
, and width
arguments can be used to specify the
consecutive subsequences. Alternatively, start
can take a Ranges
object or something that can be converted to a Ranges object like an
integer vector, logical vector or logical Rle.
head(x, n = 6L)
:
If n
is non-negative, returns the first n elements of the Sequence
object.
If n
is negative, returns all but the last abs(n)
elements
of the Sequence object.
tail(x, n = 6L)
:
If n
is non-negative, returns the last n elements of the Sequence
object.
If n
is negative, returns all but the first abs(n)
elements
of the Sequence object.
rev(x)
:
Return a new Sequence object made of the original elements in the reverse
order.
rep(x, times, length.out, each)
, rep.int(x, times)
:
Repeats the values in x
through one of the following conventions:
times
length(x)
, or to repeat the whole vector
if of length 1.length.out
each
x
is
repeated each
times.subset(x, subset)
:
Return a new Sequence object made of the subset using logical vector
subset
, where missing values are taken as FALSE.
In the code snippets below, x
is a Sequence object.
x[[i]]
:
If defined, return the selected element i
, where i
is an
numeric or character vector of length 1.
x$name
:
Similar to x[[name]]
, but name
is taken literally as an
element name.
In the code snippets below, x
is a Sequence object.
c(x, ...)
:
Combine x
and the Sequence objects in ...
together.
Any object in ...
must belong to the same class as x
,
or to one of its subclasses, or must be NULL
.
The result is an object of the same class as x
.
append(x, values, after = length(x))
: Insert the
Sequence
values
onto x
at the position given by
after
. values
must have an elementType
that extends
that of x
.
In the code snippets below, x
is a Sequence object.
lapply(X, FUN, ...)
:
Like the standard lapply
function defined in the
base package, the lapply
method for Sequence objects returns
a list of the same length as X
, with each element being the
result of applying FUN
to the corresponding element of X
.
sapply(X, FUN, ..., simplify = TRUE, USE.NAMES = TRUE)
:
Like the standard sapply
function defined in the
base package, the sapply
method for Sequence objects is a
user-friendly version of lapply
by default returning a vector
or matrix if appropriate.
mapply(FUN, ..., MoreArgs = NULL, SIMPLIFY = TRUE, USE.NAMES = TRUE)
:
Like the standard mapply
function defined in the
base package, the mapply
method for Sequence objects is a
multivariate version of sapply
.
tapply(X, INDEX, FUN = NULL, ..., simplify = TRUE)
:
Like the standard tapply
function defined in the
base package, the tapply
method for Sequence objects applies a
function to each cell of a ragged array, that is to each (non-empty)
group of values given by a unique combination of the levels of certain
factors.
endoapply(X, FUN, ...)
:
Similar to lapply
, but performs an endomorphism,
i.e. returns an object of class(X)
.
mendoapply(FUN, ..., MoreArgs = NULL)
:
Similar to mapply
, but performs an endomorphism
across multiple objects, i.e. returns an object of
class(list(...)[[1]])
.
shiftApply(SHIFT, X, Y, FUN, ..., OFFSET = 0L, simplify = TRUE, verbose = FALSE)
:
Let i
be the indices in SHIFT
,
X_i = window(X, 1 + OFFSET, length(X) - SHIFT[i])
, and
Y_i = window(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
X
, Y
FUN
match.fun
, to be
applied to each set of shifted vectors.FUN
.simplify
verbose
i
indices to track the iterations.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
start
, end
, and
width
methods.FUN
match.fun
, to be
applied to each window of x
.start
, end
, width
by
is missing, then must supply two of the
three.frequency
, delta
FUN
.simplify
In the code snippets below, x
is a Sequence object.
as.env(x, enclos = parent.frame())
:
Creates an environment from x
with a symbol for each
names(x)
. The values are not actually copied into the
environment. Rather, they are dynamically bound using
makeActiveBinding
. This prevents unnecessary copying
of the data from the external vectors into R vectors. The values
are cached, so that the data is not copied every time the symbol
is accessed.
as.list(x, ...)
, as(from, "list")
:
Turns x
into a standard list.
stack(x, indName = "space", valuesName = "values")
:
As with stack
on a list
,
constructs a DataFrame
with two columns: one for the
unlisted values, the other indicating the name of the element from
which each value was obtained. indName
specifies the column
name for the index (source name) column and valuesName
specifies the column name for the values.
The R base package defines some Higher-Order functions that are commonly
found in Functional Programming Languages. See ?Reduce
for the details, and, in particular, for a description of their arguments.
The IRanges package provides methods for Sequence objects, so, in addition
to be a vector, the x
argument can also be a Sequence object.
Reduce(f, x, init, right = FALSE, accumulate = FALSE)
:
Uses a binary function to successively combine the elements of x
and a possibly given initial value.
See ?Reduce
(in the base package) for the details.
Filter(f, x)
:
Extracts the elements of x
for which function f
is TRUE.
See ?Filter
(in the base package) for the details.
Find(f, x, right = FALSE, nomatch = NULL)
:
Extracts the first or last such element in x
.
See ?Find
(in the base package) for the details.
Map(f, ...)
:
Applies a function to the corresponding elements of given Sequence
objects.
See ?Map
(in the base package) for the details.
Position(f, x, right = FALSE, nomatch = NA_integer_)
:
Extracts the first or last such position in x
.
See ?Position
(in the base package) for the details.
In the code snippets below, envir
and data
are Sequence
objects.
eval(expr, envir, enclos = parent.frame())
:
Converts the Sequence object specified in envir
to an
environment using as.env
, with enclos
as its parent,
and then evaluates expr
within that environment.
with(data, expr, ...)
:
Equivalent to eval(quote(expr), data, ...)
.
P. Aboyoun
Annotated, DataTable, SimpleList, Ranges, Rle, XVector for example implementations
showClass("Sequence") # shows (some of) the known subclasses