expand-methods: Unlist the list-like columns of a DataFrame object

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

Unlist the list-like columns of a DataFrame object

Description

expand transforms a DataFrame object into a new DataFrame object where the columns specified by the user are unlisted. The transformed DataFrame object has the same colnames as the original but typically more rows.

Usage

## S4 method for signature 'DataFrame'
expand(x, colnames, keepEmptyRows = FALSE, recursive = TRUE)

Arguments

x	A DataFrame object with list-like columns or a Vector object with list-like metadata columns (i.e. with list-like columns in mcols(x)).
colnames	A character or numeric vector containing the names or indices of the list-like columns to unlist. The order in which columns are unlisted is controlled by the column order in this vector. This defaults to all of the recursive (list-like) columns in x.
keepEmptyRows	A logical indicating if rows containing empty list elements in the specified colnames should be retained or dropped. When TRUE, list elements are replaced with NA and all rows are kept. When FALSE, rows with empty list elements in the colnames columns are dropped.
recursive	If TRUE, expand each column recursively, with the result representing their cartesian product. If FALSE, expand all of the columns in parallel, which requires that they all share the same skeleton.

Value

A DataFrame object that has been expanded row-wise to match the length of the unlisted columns.

See Also

• DataFrame objects.

Examples

library(IRanges)
aa <- CharacterList("a", paste0("d", 1:2), paste0("b", 1:3), c(), "c")
bb <- CharacterList(paste0("sna", 1:2),"foo", paste0("bar",1:3),c(),"hica")
df <- DataFrame(aa=aa, bb=bb, cc=11:15)

## Expand by all list-like columns (aa, bb), dropping rows with empty
## list elements:
expand(df)

## Expand the aa column only:
expand(df, colnames="aa", keepEmptyRows=TRUE)
expand(df, colnames="aa", keepEmptyRows=FALSE)

## Expand the aa and then the bb column:
expand(df, colnames=c("aa","bb"), keepEmptyRows=TRUE)
expand(df, colnames=c("aa","bb"), keepEmptyRows=FALSE)

## Expand the aa and dd column in parallel:
df$dd <- relist(seq_along(unlist(aa)), aa)
expand(df, colnames=c("aa","dd"), recursive=FALSE)

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