Group elements of a vector-like object into a list-like object
Because relist and split both impose restrictions on
the kind of grouping that they support (e.g. every element in the input
object needs to go in a group and can only go in one group), the
IRanges package introduces the extractList generic function
for performing arbitrary groupings.
## relist() ## -------- ## S4 method for signature 'ANY,List' relist(flesh, skeleton) ## S4 method for signature 'Vector,list' relist(flesh, skeleton) ## extractList() ## ------------- extractList(x, i) ## regroup() ## --------- regroup(x, g)
flesh, x |
A vector-like object. |
skeleton |
A list-like object. Only the "shape" (i.e. element lengths) of
|
f |
An atomic vector or a factor (possibly in Rle form). |
i |
A list-like object. Unlike for |
g |
A Grouping or an object coercible to one. For
|
Like split, relist and extractList have in common
that they return a list-like object where all the list elements have the
same class as the original vector-like object.
Methods that return a List derivative return an object of class
relistToClass(x).
By default, extractList(x, i) is equivalent to:
relist(x[unlist(i)], i)
An exception is made when x is a data-frame-like object. In that
case x is subsetted along the rows, that is, extractList(x, i)
is equivalent to:
relist(x[unlist(i), ], i)
This is more or less how the default method is implemented, except for
some optimizations when i is a IntegerRanges object.
relist and split can be seen as special cases of
extractList:
relist(flesh, skeleton) is equivalent to
extractList(flesh, PartitioningByEnd(skeleton))
split(x, f) is equivalent to
extractList(x, split(seq_along(f), f))It is good practise to use extractList only for cases not covered
by relist or split. Whenever possible, using relist
or split is preferred as they will always perform more efficiently.
In addition their names carry meaning and are familiar to most R
users/developers so they'll make your code easier to read/understand.
Note that the transformation performed by relist or split
is always reversible (via unlist and unsplit, respectively),
but not the transformation performed by extractList (in general).
The regroup function splits the elements of unlist(x)
into a list according to the grouping g. Each element of
unlist(x) inherits its group from its parent element of
x. regroup is different from relist and
split, because x is already grouped, and the goal is to
combine groups.
The relist methods behave like utils::relist except that they
return a List object. If skeleton has names, then they are
propagated to the returned value.
extractList returns a list-like object parallel to i and with
the same "shape" as i (i.e. same element lengths).
If i has names, then they are propagated to the returned value.
All these functions return a list-like object where the list elements have
the same class as x. relistToClass gives
the exact class of the returned object.
Hervé Pagès
The unlist and relist
functions in the base and utils packages, respectively.
The split methods defined in the
S4Vectors package.
Vector, List,
Rle, and DataFrame objects
in the S4Vectors package.
relistToClass is documented in the man
page for List objects.
IntegerRanges objects.
## On an Rle object: x <- Rle(101:105, 6:2) i <- IRanges(6:10, 16:12, names=letters[1:5]) extractList(x, i) ## On a DataFrame object: df <- DataFrame(X=x, Y=LETTERS[1:20]) extractList(df, i)
Please choose more modern alternatives, such as Google Chrome or Mozilla Firefox.