splitAsList: Divide a vector-like object into groups

In Bioconductor/S4Vectors: Foundation of vector-like and list-like containers in Bioconductor

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

Bioconductor/S4Vectors documentation built on Nov. 17, 2024, 6:55 p.m.