splitAsList {S4Vectors} | R Documentation

## Divide a vector-like object into groups

### Description

`split` divides the data in a vector-like object `x` into the groups defined by `f`.

NOTE: This man page is for the `split` methods defined in the S4Vectors package. See `?base::split` for the default method (defined in the base package).

### Usage

    ## S4 method for signature 'Vector,ANY'
    split(x, f, drop=FALSE, ...)

    ## S4 method for signature 'ANY,Vector'
    split(x, f, drop=FALSE, ...)

    ## S4 method for signature 'Vector,Vector'
    split(x, f, drop=FALSE, ...)

    ## S4 method for signature 'list,Vector'
    split(x, f, drop=FALSE, ...)

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

    relistToClass(x)

### Arguments

`x, f` | 2 vector-like objects of the same length. `f` will typically be a factor, but not necessarily.
`drop` | Logical indicating if levels that do not occur should be dropped (if `f` is a factor).
`...` | Extra arguments passed to any of the first 3 `split()` methods will be passed to `splitAsList()` (see Details below). Extra arguments passed to the last `split()` method will be passed to `base::split()` (see Details below). Extra arguments passed to `splitAsList()` will be passed to the specific method selected by method dispatch.

### Details

The first 3 `split()` methods just delegate to `splitAsList()`.

The last `split()` method just does:

        split(x, as.vector(f), drop=drop, ...)

`splitAsList()` is an S4 generic function. It is the workhorse behind the first 3 `split()` methods above. It behaves like `base::split()` except that it returns a List derivative instead of an ordinary list. The exact class of this List derivative depends only on the class of `x` and can be obtained independently with `relistToClass(x)`.

Note that `relistToClass(x)` is the opposite of `elementType(y)` in the sense that the former returns the class of the result of relisting (or splitting) `x` while the latter returns the class of the result of unlisting (or unsplitting) `y`. More formally, if `x` is an object that is relistable and `y` a list-like object:

        relistToClass(x) is class(relist(x, some_skeleton))
        elementType(y) is class(unlist(y))

Therefore, for any object `x` for which `relistToClass(x)` is defined and returns a valid class, `elementType(new(relistToClass(x)))` should return `class(x)`.

### Value

`splitAsList()` and the first 3 `split()` methods behave like `base::split()` except that they return a List derivative (of class `relistToClass(x)`) instead of an ordinary list. Like with `base::split()`, all the list elements in this object have the same class as `x`.

### See Also

- The `split` function in the base package.

- The `relist` methods and `extractList` generic function defined in the IRanges package.

- Vector and List objects.

- Rle and DataFrame objects.

### Examples

    ## On an Rle object:
    x <- Rle(101:105, 6:2)
    split(x, c("B", "B", "A", "B", "A"))

    ## On a DataFrame object:
    groups <- c("group1", "group2")
    DF <- DataFrame(
        a=letters[1:10],
        i=101:110,
        group=rep(factor(groups, levels=groups), c(3, 7))
    )
    split(DF, DF$group)

    ## Use splitAsList() if you need to split an ordinary vector into a
    ## List object:
    split(letters, 1:2)        # ordinary list
    splitAsList(letters, 1:2)  # List object

[Package S4Vectors version 0.28.1 Index]