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 IntegerRanges 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 IntegerRanges 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

- The `unlist` and `relist` functions in the base and utils packages, respectively.

- The `split` and `unsplit` functions in the base package.

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

### 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.14.12 Index]