extractList {IRanges}R Documentation

Group elements of a vector-like object into a list-like object

Description

relist and split are 2 common ways of grouping the elements of a vector-like object into a list-like object. The IRanges and S4Vectors packages define relist and split methods that operate on a Vector object and return a List object. Note that the split methods defined in S4Vectors delegate to the splitAsList function defined in IRanges and documented below.

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.

Usage

## relist()
## --------

## S4 method for signature 'ANY,List'
relist(flesh, skeleton)

## S4 method for signature 'Vector,list'
relist(flesh, skeleton)

## splitAsList()
## -------------

splitAsList(x, f, drop=FALSE, ...)

## extractList()
## -------------

extractList(x, i)

## regroup()
## ---------

regroup(x, g)

Arguments

flesh, x

A vector-like object.

skeleton

A list-like object. Only the "shape" (i.e. element lengths) of skeleton matters. Its exact content is ignored.

f

An atomic vector or a factor (possibly in Rle form).

drop

Logical indicating if levels that do not occur should be dropped (if f is a factor).

i

A list-like object. Unlike for skeleton, the content here matters (see Details section below). Note that i can be a Ranges object (a particular type of list-like object), and, in that case, extractList is particularly fast (this is a common use case).

g

A Grouping or an object coercible to one. For regroup, g groups the elements of x.

...

Arguments to pass to methods.

Details

relist, split, and extractList have in common that they return a list-like object where each list element has the same class as the original vector-like object. Thus they need to be able to select the appropriate List concrete subclass to use for this returned value. This selection is performed by relistToClass and is based only on the class of the original object.

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 Ranges object.

relist and split (or splitAsList) 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.

Value

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.

splitAsList behaves like base::split except that the former returns a List object instead of an ordinary list.

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.

Author(s)

Hervé Pagès

See Also

Examples

## 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)

[Package IRanges version 2.12.0 Index]